メインコンテンツまでスキップ

UID2 Client-Side Integration Guide for Prebid.js

このガイドは、Client-Side で DII(メールアドレスまたは電話番号) にアクセスでき、UID2 とインテグレーションして、RTB ビッドストリームで Prebid.js によって渡される UID2 token(Advertising Token) を生成したいパブリッシャー向けのものです。

Prebid.js を使って UID2 とインテグレーションするには、サイトの HTML と JavaScript を変更する必要があります。このガイドに従えば、Server-Side の作業は必要ありません。

Prebid.js Version​

この実装には Prebid.js version 8.21.0 以降が必要です。バージョン情報については、https://github.com/prebid/Prebid.js/releases を参照してください。

以前のバージョンの Prebid.js を使用する必要がある場合は、代わりに UID2 Client-Server Integration Guide for Prebid.js で説明している実装ソリューションを使用してください。

Integration Example​

UID2 Prebid.js Client-Side インテグレーション例は、以下のリンクから入手できます:

Integrating with Single Sign-On (SSO)​

シングルサインオン(SSO)プロバイダーとのインテグレーションに関する情報は、Publisher Integration with SSO Providers を参照してください。

Integration Overview: High-Level Steps​

以下のステップを完了する必要があります:

  1. Complete UID2 account setup and configure account
  2. Add Prebid.js to your site.
  3. Configure the UID2 module.

Complete UID2 Account Setup and Configure Account​

UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントをまだ作成していない場合は、まず Account Setup ページの手順に従ってください。

アカウントの初期設定が完了すると、UID2 ポータルにアクセスするための手順とリンクが送信されます。UID2 ポータルでは、本番環境のための credentials を作成し、提供する必要がある追加の値を設定できます。詳細については、Getting Started with the UID2 Portal を参照してください。

Client-Side インテグレーションには、UID2 ポータルの Client-Side Integration ページで以下の値を設定する必要があります:

ヒント

アカウント設定に必要なのは、ルートレベルのドメインだけです。たとえば、Prebid.js で UID2 を example.com、shop.example.com、example.org で使用する場合、ドメイン名 example.com と example.org だけを指定します。

Add Prebid.js to Your Site​

Prebid.js をサイトに追加するには、Prebid.js ドキュメントの Getting Started for Developers の手順に従ってください。

Prebid.js のパッケージをダウンロードする際に、User ID Modules セクションの下にある Unified ID 2.0 という名前のモジュールの横にあるチェックボックスをオンにして、UID2 モジュールを追加します。

Prebid.js をサイトに追加し、正常に動作していることを確認したら、UID2 モジュールを設定する準備が整います。

ヒント

UID2 モジュールがインストールされていることを確認するには、pbjs.installedModules array で uid2IdSystem 文字列を検索します。

Configure the UID2 Module​

UID2 module を設定するには、アカウント設定時に受け取った Public Key と Subscription ID、およびユーザーのハッシュ化された、またはハッシュ化されていないメールアドレスまたは電話番号を含むオブジェクトを使用して pbjs.setConfig を呼び出します。

いったん設定されると、UID2 module はユーザー用の UID2 Token を生成し、それをユーザーのブラウザに保存します。このモジュールは、あなたのサイトがユーザーのブラウザで開かれている限り、必要に応じてトークンを自動的にリフレッシュします。

UID2 module は、4つの DII フォーマットのいずれかを使用して、特定のユーザー用に設定することができます:

  • 正規化した、または正規化していないメールアドレス
  • 正規化とハッシュ化したメールアドレス
  • 正規化した電話番号
  • 正規化とハッシュ化した電話番号

Notes:

  • DII フォーマットはユーザーごとに異なる場合がありますが、送信できる値はユーザーごとに 1 つだけです。

  • すでにハッシュ化された DII をモジュールに渡したい場合は、以下の手順に従ってください:

    1. まず正規化します。
    2. 次に、SHA-256 ハッシングアルゴリズムを使用して結果をハッシュ化します。
    3. 次に、ハッシュ値のバイトを Base64 エンコードして結果をエンコードします。

    詳細は Normalization and Encoding を参照してください。例については、Configuring the UID2 Module: Code Example を参照してください。

  • UID2 module は、ハッシュ化された DII を UID2 Service に送信する前に暗号化します。

  • モジュールが複数回設定された場合、最新の設定値が使用されます。

Configuring the UID2 Module: Code Example​

以下のコードスニペットは、UID2 module を設定するさまざまな方法を示しています。

const baseConfig = {
  userSync: {
    userIds: [{
      name: 'uid2',
      params: {
        serverPublicKey: publicKey,
        subscriptionId: subscriptionId,
        // Choose only one of the following: email, emailHash, phone, or phoneHash
        email: 'user@example.com', // Normalized or non-normalized, unhashed email address
        // emailHash: 'tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=', // Normalized, hashed, and encoded email address
        // phone: '+12345678901', // Normalized phone number
        // phoneHash: 'EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=', // Normalized, hashed, and encoded phone number
      }
    }]
  }
};
注記

この例では、UID2 本番環境を使用していると仮定しています。インテグレーションテスト中は、params.uid2ApiBase を 'https://operator-integ.uidapi.com' に設定して UID2 インテグレーション環境を使用してください (資格情報については Getting Your Credentials を参照)。UID2 インテグレーション環境からのトークンはビッドストリームに渡すために有効ではありません。インテグレーション環境では、異なる Subscription ID と public key の値があります。

Storing the UID2 Token in the Browser​

デフォルトでは、UID2 モジュールはローカルストレージを使用してデータを保存します。代わりにクッキーを使用する場合は、次の例のように params.storage を cookie に設定します。

詳細は、Prebid ドキュメントの Unified ID 2.0 Configuration を参照してください。

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'uid2', 
      params: { 
        // default value is 'localStorage' 
        storage: 'cookie'   
      } 
    }] 
  } 
});

クッキーのサイズが大きくなる可能性があるため、問題になる可能性があります。ただし、ローカルストレージが選択肢にない場合、これは1つのアプローチです。

When to Pass DII to the UID2 Module​

UID2 module が設定されると、ユーザーのブラウザに既存の UID2 Token があるかどうかをチェックします。同じ DII から生成されたトークンがあり、まだ有効であるか、リフレッシュ可能である場合、モジュールはそれを使用し、必要に応じてリフレッシュします。

既存のトークンがないか、トークンの有効期限が切れていてリフレッシュできない場合、UID2 module は DII なしで新しいトークンを生成できません。

ヒント

各ページのロード時に、ユーザーの DII で UID2 module を構成します。これが推奨される方法です。

場合によっては、ユーザーの DII はページロード時に利用できず、DII の取得には何らかの関連コストがかかることがあります。たとえば、DII を取得するために API コールが必要な場合や、DII 情報を提供するためにユーザーにプロンプトが表示される場合があります。

UID2 Token の有効期限が切れてリフレッシュできない場合は、DII で UID2 module を設定して新しいトークンを生成する必要があります。これを行うには、次の例に示すように、pbjs.getUserIds().uid2 が返す値をチェックします:

const params = {}; 
 
if (!pbjs.getUserIds().uid2) { 
  // There is no token that can be used or refreshed. 
  // The UID2 module must be configured with DII to generate a new token. 
  params.email = getUserEmail(); 
  params.serverPublicKey = publicKey; 
  params.subscriptionId = subscriptionId; 
} 

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'uid2', 
      params: params 
    }] 
  } 
});

ユーザーが以前に UID2 をオプトアウトしている可能性があります。この場合、UID2 module はユーザーのオプトアウトを受け入れ、Prebid.js によって UID2 Token が生成されずに収集されません。

Checking the Integration​

UID2 module が正常に UID2 Token を生成したかどうかを確認するには pbjs.getUserIds().uid2 を呼び出します。値が返された場合、UID2 module に有効な UID2 Token が存在していることになります。

インテグレーションに問題がある場合、以下のような手順があります:

  • ブラウザのコンソールログを確認してください。
  • Subscription ID (subscriptionId の値) と Public Key (serverPublicKey の値) を確認してください:
    • UID2 チームから受け取った値と同一であることを確認してください。
    • 使用している環境の値が正しいことを確認してください。environment ごとに Subscription IDID と Public Key の値が異なります。
  • アカウントのセットアップ中に、サイトのドメイン名を UID2 チームに提供したことを確認してください。必要に応じて、UID2 の担当者に確認してください。
  • ブラウザのデベロッパーツールを使って、UID2 Service への API コールを調べます。

その他のヘルプについては、Prebid のドキュメント Troubleshooting Prebid.js および Debugging Prebid.js を参照してください。

Prebid.js の設定を検証・デバッグするツールの例として、オープンソースの Chrome 拡張機能である Professor Prebid があります:

Optional: Specifying the API Base URL to Reduce Latency​

デフォルトでは、UID2 モジュールは米国の UID2 本番環境サーバーに対して呼び出しを行います。

ユースケースに最適な URL を選択する方法と、有効なベース URL の完全なリストについては、Environments を参照してください。

UID2 モジュールをデフォルト以外の UID2 サーバーに指定するには、UID2 モジュールを設定する際に、オプションの params.uid2ApiBase パラメータを次の例に示すように設定します:

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'uid2', 
      params: { 
        uid2ApiBase: baseUrl, 
        // ... 
      } 
    }] 
  } 
});

Optional: Prebid.js Integration with Google Secure Signals​

Prebid.js を使用しており、Google Secure Signals を使用して UID2 Token を Google に渡す場合、追加の設定手順がいくつかあります: