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

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 インテグレーション例は、以下のリンクから入手できます:

Integration Overview: High-Level Steps​

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

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

Complete UID2 Account Setup​

Account Setup ページに記載されている手順に従って、UID2 アカウントのセットアップを完了します。Client-Side 実装のアカウント設定プロセスの一環として、Prebid.js で使用するサイトのドメイン名のリストを提供する必要があります。

ヒント

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

アカウントのセットアップが完了すると、UID2 サーバーがユーザーを識別するために使用する 2 つの値であるクライアントキーペアが発行されます: Subscription ID と Public key。これらの値はあなたに固有で、UID2 モジュールの設定に使用します。詳細は Subscription ID and Public Key を参照してください。

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 インテグレーション環境を使用します。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 と Public Key の値を確認してください:
    • 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 に渡す場合、追加の設定手順がいくつかあります: