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

UID2 Server-Side Integration Guide for Prebid.js

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

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

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

Prebid.js Version​

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

UID2 Prebid Module Page​

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

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 アカウントのセットアップを完了します。

アカウントのセットアップが完了すると、固有の API Keyと クライアントシークレットが発行されます。ここれらの値はアカウント独自のもので、安全に管理することが重要です。詳細は 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 module を追加します。

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

ヒント

UID2 module がインストールされていることを確認するには、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​

トークンを生成するには、POST /token/generate エンドポイントを呼び出します。

例については、Sample Token を参照してください。

Refreshing a UID2 Token​

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

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

Client Refresh Mode​

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

例については、Sample Token を参照してください。

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 を参照してください。

Client Refresh Mode uid2Token Example​

次の例は、コンフィギュレーションのサンプルを示しています。トークンの内容については、Sample 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
        }
      }
    }]
  }
});

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 という名前のクッキーに格納しています。この設定により、UID2 module がクッキーから Advertising Token の値を取得できるようになります。

Cookie:

__uid2_advertising_token=...advertising token...

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" に設定します。この値は、トークンを生成する環境と同じ環境 (本番環境またはテスト環境) に設定しなければなりません。

Storing the UID2 Token in the Browser​

デフォルトでは、UID2 module はローカルストレージを使ってデータを保存します。代わりにクッキーを使用するには、以下の例に示すように 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 を参照してください。
params.uid2CookieCR: オプション
SO: N/A		Stringサーバが設定した UID2 Token を保持するクッキーの名前。クッキーは uid2Token パラメータと同じ形式の JSON を含む必要があります。uid2Token を指定した場合、このパラメータは無視されます。Sample Token を参照してください。
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​

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

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

Optional: Reduce Latency by Setting the API Base URL for the Production Environment​

デフォルトでは、UID2 module はアメリカにある UID2 サーバーに API コールを行います。ユーザーの居住地によっては、レイテンシー(遅延時間) を短縮するために、ユーザーに近いサーバーを選択することを検討してください。

UID2 module を設定するときに別の UID2 サーバーを指定するには、次の例に示すように、オプションの params.uid2ApiBase パラメータを設定します:

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

Base URL のリストは、Environments を参照してください。