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

UID2 Client-Server Integration Guide for Prebid.js

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

これは Client-Server インテグレーションと呼ばれ、一部のインテグレーションステップが Client-Side で行われ、一部が Server-Side で行われます。

Prebid.js を使って UID2 とインテグレーションするには、以下が必要です:

  • サイトの HTML と JavaScript に変更を加えます。
  • トークン生成のためにサーバーサイドを変更します(オプションで Token Refresh)。

Prebid.js Version​

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

UID2 Prebid Module Page​

Prebid と UID2 のインテグレーション方法に関する情報は、以下の場所にもあります:

Integrating with Single Sign-On (SSO)​

SSO ログインを提供するために1つ以上の SSO プロバイダーとインテグレーションしている場合、SSO プロバイダーからログインユーザーのメールアドレスを取得して UID2 Token を生成できる可能性があります。

詳細は、Publisher Integration with SSO Providers を参照してください。

Preparing DII for Processing​

UID2 に変換する入力データが許容可能な形式であることは非常に重要です。そうでない場合、期待される結果は得られません。たとえば、Phone Number Normalization で説明されているように、電話番号には国コードを含めるように正規化する必要があります。

詳細は、Preparing Emails and Phone Numbers for Processing を参照してください。

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​

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

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

Client-Server インテグレーションの場合、UID2 Portal の API Keys ページで以下の値を設定する必要があります:

  • API key、Client Key とも呼ばれます。
  • Client secret、参加者と UID2 Service のみが知る値。
important

これらの値を安全に保管することが非常に重要です。詳細は、Security of API Key and Client Secret を参照してください。

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 Prebid モジュールを設定して、以下の2つのアクションを実行する必要があります:

StepActionLink to Instructions
1Server-Side API コールを送信して UID2 Token を生成します。Generating a UID2 Token on the Server
2Prebid module がトークンのリフレッシュと必要に応じてオプトアウトを管理できるように、レスポンス値を保存します。Refreshing a UID2 Token

Generating a UID2 Token on the Server​

Prebid の Client-Server インテグレーションの場合、最初のステップは、サーバー上で UID2 Token を生成することです。その後、トークンを Prebid に渡して RTB ビッドストリームに送信します。

手順や例を含む詳細は、Server-Side Token Generation を参照してください。

トークンを生成するには、いずれかの SDK または POST /token/generate エンドポイントを呼び出します。トークンを示す API レスポンスの例は、Sample Token Response Object を参照してください。Identity レスポンスを Prebid に渡す必要があります。

警告

セキュリティ上の理由から、トークン生成に使用される API キーとシークレットはサーバーサイドで呼び出す必要があります。これらの値は Prebid の実装の一部として保存しないでください。

Refreshing a UID2 Token​

UID2 Token をリフレッシュするには、次の表に示すように 2 つの方法があります。

ModeDescriptionLink to Section
Client refresh modePrebid.js は内部で自動的にトークンをリフレッシュします。
これは最もシンプルなアプローチです。		Client Refresh Mode
Server-only modePrebid.js はトークンを自動的にリフレッシュしません。トークンのリフレッシュを管理するのはパブリッシャーです。
このオプションを選択する理由の例:
  • SDK for JavaScript を使用してトークンをリフレッシュし、Prebid.js でトークンをビッドストリームに送信したい場合。
  • トークンを複数の手段(Prebid.js や Google など) でビッドストリームに送信したい場合。
Server-Only Mode

Client Refresh Mode​

該当するエンドポイントからの完全な JSON レスポンスボディを Prebid module に提供する必要があります:

例は、Sample Token Response Object を参照してください。

Refresh Token が有効である限り、UID2 Prebid module は必要に応じて UID2 Token をリフレッシュします。

このセクションには以下の情報が含まれます:

Client Refresh Mode Response Configuration Options​

Client Refresh Mode を使用するようにモジュールを構成する場合、Prebid module にトークンを提供するための以下のオプションの 1つ を選択する必要があります。

OptionDetailsUse Case
params.uid2Cookie に、JSON 文字列としてレスポンスボディを含むクッキーの名前を設定します。Client Refresh Mode Cookie Example を参照してください。レスポンスボディを保存するのに十分なスペースがクッキーに残っていることが確実な場合のみ、このオプションを使用してください。確信が持てない場合や、クッキーの保存の必要性が異なる可能性がある場合は、他のオプションを選択してください。
params.uid2TokenをJavaScriptオブジェクトとしてレスポンスボディに設定します。Client Refresh Mode uid2Token Example を参照してください。params.uid2Token を介してレスポンスボディを提供することもできます:
  • すでに多くのデータをクッキーに保存していて、レスポンスボディを追加するとクッキーのサイズ制限を超える可能性がある場合。
  • Prebid module にトークン値を保存させたい場合。

Client Refresh Mode では、Prebid.js がトークンの更新を行います。そのためには、トークンを保存するように設定する必要があります。以下の例では、Cookie と、uid2_pub_cookie という Cookie にトークンを保存するための設定しています。

Cookie:

uid2_pub_cookie={"advertising_token":"...advertising token...","refresh_token":"...refresh token...","identity_expires":1684741472161,"refresh_from":1684741425653,"refresh_expires":1684784643668,"refresh_response_key":"...response key..."}

Configuration:

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

トークンの例は、Sample Token Response Object を参照してください。

Client Refresh Mode uid2Token Example​

次の例は、コンフィギュレーションのサンプルを示しています。トークンの内容は、Sample Token Response Object を参照してください。

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'uid2',
      params: {
        uid2Token: {
          'advertising_token': '...advertising token...',
          'refresh_token': '...refresh token...',
          // etc. - see the sample token for contents of this object
        }
      }
    }]
  }
});

Passing a New Token: Client Refresh Mode​

Refresh Token の有効期限が切れた場合は、新しい Advertising Token と新しい Refresh Token を将来のリフレッシュのために利用できるように、新しいトークンレスポンスを提供する必要があります。

新しいトークンを提供する必要があるかどうかを判断する方法は、Determining Whether the Module Has a Valid Token を参照してください。

Server-Only Mode​

Server-Only Mode では、Advertising Token のみがモジュールに提供されます。モジュールはトークンをリフレッシュできません。トークンをリフレッシュする方法を実装する責任があります。

Server-Only Mode を使用するようにモジュールを設定するには、以下の 1つ を実行します:

Implementation MethodLink to Example
__uid2_advertising_token という名前のクッキーを設定し、Advertising Token の値を格納します。Server-Only Mode Cookie Example
Advertising Token を含む ID ブロックに value を設定します。Server-Only Mode Value Example

このセクションには以下の情報が含まれます:

以下の例では、Advertising Token の値を格納する __uid2_advertising_token という名前のクッキーを設定しています。クッキーの値は、トークンレスポンスオブジェクトで返される値です(詳細は Sample Token Response Object を参照)。

この設定により、UID2 モジュールは Advertising Token の値をクッキーから取得できます。

Cookie:

__uid2_advertising_token=A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

Configuration:

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

Server-Only Mode Value Example​

次の例では、value フィールドをクッキーに保存せずに、Advertising Token を含む ID ブロックに設定しています。

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'uid2'
            value: {
                'uid2': {
                    'id': '...advertising token...'
                }
            }
        }]
    }
});

Passing a New Token: Server-Only Mode​

Server-Only Mode では、Prebid.js UID2 module は Advertising Token のみを受け取るため、トークンは短時間しか有効ではありません。このため、各ページのロード時に Advertising Token を提供するのが最善です。

必要であれば、新しいトークンを提供する必要があるかどうかを判断するために、Determining Whether the Module Has a Valid Token を参照してください。

Prebid Implementation Notes and Tips​

Prebid の実施を計画する際には、以下を考慮してください:

  • モジュールは提供されたオリジナルのトークンを保存し、必要に応じてリフレッシュし、リフレッシュされたトークンを使用します。期限切れの ID を提供し、モジュールが同じ ID をリフレッシュした有効な更新を持っている場合、モジュールは提供した期限切れの ID の代わりにリフレッシュされた ID を使用します。

  • リフレッシュされたトークンを生成するために使用された元のトークンと一致しない新しいトークンを提供した場合、モジュールは保存されているすべてのトークンを破棄し、代わりに新しいトークンを使用し、リフレッシュされた状態を維持します。

  • インテグレーションテストでは、params.uid2ApiBase を "https://operator-integ.uidapi.com" に設定します。トークンの生成に使用する環境(本番環境またはインテグレーション環境)と同じ値に設定する必要があります(資格情報は、Getting Your Credentials を参照)。

  • Prebid.js client-server インテグレーションの場合、クライアントサイドインテグレーション機能を無効にして、より小さな Prebid.js ビルドを作成できます。これを行うには、--disable UID2_CSTG フラグを渡します:

    $ gulp build --modules=uid2IdSystem --disable UID2_CSTG

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つのアプローチです。

Determining Whether the Module Has a Valid Token​

Prebid.js module が有効なトークンを持っているか、新しいトークンを提供する必要があるかを判断するためにチェックを行うことができます。

これを行うには、次の例に示すように、pbjs.getUserIds().uid2 が返す値をチェックします:

if (!pbjs.getUserIds().uid2) {
  // There is no token that can be used or refreshed.
  // Configure the UID2 module with a new token
  pbjs.setConfig({
      userSync: {
          userIds: [{
              name: 'uid2',
              params: {
                  uid2Token: {
                      'advertising_token': '...advertising token...',
                      'refresh_token': '...refresh token...',
                      // etc. - see the sample token for contents of this object
                  }
              }
          }]
      }
  });  
}
注意

setConfig(または同様の関数) を 2 回呼び出してユーザー ID を設定した場合、User ID Submodule の ID 値を再初期化するために、refreshUserIds を呼び出す必要があります。

Checking the Integration​

UID2 Module に有効な UID2 Token があるかどうかを確認するには pbjs.getUserIds().uid2 を呼び出します。値が返された場合、UID2 Module に有効な UID2 Token が存在します。

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

  • ブラウザのコンソールログを確認してください。
  • ブラウザのデベロッパーツールを使って、UID2 Service への API コールを調べます。

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

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

Configuration Parameters for userSync​

以下のパラメータは、UID2 Prebid User ID Module のインテグレーションにのみ適用されます。

この表では、CR = client refresh mode, SO = server-only mode, and N/A = 該当なし。

Param under userSync.userIds[]Mode/ScopeTypeDescriptionExample
nameCR: 必須
SO: 必須		StringUID2 module の ID 値。常に "uid2"。"uid2"
valueCR: N/A
SO: オプション		ObjectAdvertising Token の値を含むオブジェクト。Configuration Parameter Examples: Value を参照してください。
params.uid2TokenCR: Optional
SO: N/A		Object最初の UID2 Token。これは /token/generate または /token/refresh エンドポイントをコールした際に復号されたレスポンスの body 要素でなければなりません。Sample Token Response Object を参照してください。
params.uid2CookieCR: オプション
SO: N/A		Stringサーバが設定した UID2 Token を保持するクッキーの名前。クッキーは uid2Token パラメータと同じ形式の JSON を含む必要があります。uid2Token を指定した場合、このパラメータは無視されます。Sample Token Response Object を参照してください。
params.uid2ApiBaseCR: オプション
SO: オプション		Stringデフォルトの UID2 API エンドポイントを上書きします。有効な値は、Environments を参照してください。"https://prod.uidapi.com" (デフォルト)
params.storageCR: オプション
SO: オプション		Stringモジュール内部の保存方法を指定します: cookie または localStorage。このパラメータは指定しないことを推奨します。代わりに、モジュールがデフォルトを使用するようにします。"localStorage" (デフォルト)

Configuration Parameter Examples: Value​

以下のコードスニペットは、value UID2 設定パラメータの例を示しています。

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'uid2'
            value: {
                'uid2': {
                    'id': '...advertising token...'
                }
            }
        }]
    }
});

Sample Token Response Object​

以下のサンプルは架空のものですが、POST /token/generate または POST /token/refresh エンドポイントから返されるトークンレスポンスオブジェクトがどのように見えるかを示しています:

{
  "advertising_token": "...",
  "refresh_token": "...",
  "identity_expires": 1633643601000,
  "refresh_from": 1633643001000,
  "refresh_expires": 1636322000000,
  "refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
}

Optional: Specifying the API Base URL to Reduce Latency​

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

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

デフォルト以外の 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 に渡す場合、追加の設定手順がいくつかあります:

Sample Implementation​

以下のサンプル実装は、Client-Server インテグレーションを使用して UID2 を Prebid.js にインテグレーションする方法を示すために利用可能です。