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

Server-Side Integration Guide for JavaScript

このガイドは、UID2 対応のシングルサインオンや ID プロバイダーではなく、UID2 と直接統インテグレーションしながら、RTB ビッドストリーム用に UID2 を使用して ID トークンを生成したいウェブアセットを持つパブリッシャーを対象としています。

SDK の技術的な詳細については、UID2 SDK for JavaScript Reference Guide を参照してください。

Sample Implementation Website​

アプリケーションの例については、SDK v3 を使用した UID2 Google Secure Signals の例を参照してください:

Introduction​

このガイドでは、SDK を使用せずにインテグレーションを行う場合に考慮すべき基本的な手順を説明します。例えば、ユーザーログインとログアウトの実装方法、UID2 ID 情報の管理方法とターゲティング広告への使用方法、トークンのリフレッシュ方法、紛失した ID の処理方法、ユーザーのオプトアウトの処理方法などを決定する必要があります。

ワークフロー図は、Integration Steps を参照してください。また、FAQ も参照してください。

UID2 を使用してクライアントの ID を確立し、Advertising Token を取得するプロセスを容易にするために、このガイドで提供する Web インテグレーション手順は、JavaScript 用の UID2 SDK に依存しています。このガイドに記載されているインテグレーションステップと SDK の使用方法(現在はメールアドレスのみ) を示す example application を以下に示します。アプリケーションのドキュメントについては、UID2 SDK Integration Example を参照してください。

ヒント

ファーストパーティ Cookie とローカルストレージの実装の詳細は、将来変更される可能性があります。潜在的な問題を回避するため、ID 管理には UID2 SDK for JavaScript API Reference に記載されている機能を使用してください。

UID2 SDK for JavaScript を使用しないパブリッシャーのインテグレーションシナリオについては、Publisher Integration Guide, Server-Only を参照してください。

注記

Google Ad Managerを使用していて、セキュアシグナル機能を使用したい場合は、まずこのガイドの手順に従った後、Google Ad Manager Secure Signals Integration Guide の追加手順に従ってください。

Integration Steps​

以下の図は、ユーザーの UID2 Token をパブリッシャーと確立するために必要なステップと、UID2 Token が RTB ビッドストリームとどのようにインテグレーションされるかを説明しています。

Publisher Flow

以下のセクションでは、図中の各ステップについての詳細を説明します:

  1. Establish identity: capture user data
  2. Bid Using UID2 Tokens
  3. Refresh Tokens
  4. Clear Identity: User Logout

Establish Identity: Capture User Data​

Step 1-c で認証を行い、ユーザーに利用規約を受け入れさせ、パブリッシャーがユーザーのメールアドレスまたは電話番号を検証した後、Server-Side で UID2 Token を生成する必要があります。次の表は、トークン生成ステップの詳細です。

StepEndpoint/SDKDescription
1-dPOST /token/generateユーザーが認証され、UID2 の作成が許可されたら、POST /token/generate エンドポイントを使用して、ユーザーの正規化したメールアドレスまたは電話番号を使って UID2 Token を生成します。
1-ePOST /token/generateユーザーのメールアドレス、電話番号、またはそれぞれのハッシュから生成された UID2 Token を返します。
1-fUID2 SDK for JavaScriptStep 1-e で返された UID2 Token を、SDK の init()関数 の identity プロパティで SDK に送信し、以下に示すように コールバック関数 を指定します。このメカニズムにより、ユーザーがログアウトするまで、UID2 Token がターゲティング広告に利用できるようになります。
1-gUID2 SDK for JavaScriptSDK から ID 更新を受け取り、ターゲティング広告を開始するために使用するコールバック関数を SDK に提供します。
  window.__uid2 = window.__uid2 || {};
  window.__uid2.callbacks = window.__uid2.callbacks || [];

  // Step 1-f
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType === 'SdkLoaded') {
      __uid2.init({
        identity : {
          "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
          "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
          "identity_expires": 1633643601000,
          "refresh_from": 1633643001000,
          "refresh_expires": 1636322000000,
          "refresh_response_key":"dYNTB20edyHJU9mZv11e3OBDlLTlS5Vb97iQVumc7b/8QY/DDxr6FrRfEB/D",
        }
      });
    }
  });

  // Step 1-g
  window.__uid2.callbacks.push((eventType, payload) => {
    if (eventType !== 'SdkLoaded') {
      if (payload.identity) {
        const advertisingToken = payload.identity.advertising_token;
        // Pass advertising_token to your advertising system to use
      } else {
        // No identity is available. Trigger a workflow for obtaining email address or phone number if you want to use UID2 for targeted advertising.
      }
    }
  });

SDKは、指定された callback function (ID の可用性を示します) を呼び出し、確立された ID をClient-Side で入札可能な状態にします。

ヒント

コードの構造によっては、Step 1-f と 1-g のコールバックを 1 つのコールバック関数にまとめると便利かもしれません。

Bid Using UID2 Tokens​

有効な ID のステータスと利用可能性に基づいて、SDK は以下を実行します:

  1. バックグラウンドの token auto-refresh を設定します。
  2. ID 情報を ローカルストレージまたはファーストパーティクッキー に保存します。
  3. ID 情報を使用して、ターゲティング広告のリクエストを始めます。

ビッドステップを以下の表に示します。

StepEndpoint/SDKDescription
2-aUID2 SDK for JavaScript以下に示すように、getAdvertisingToken() 関数 を使用して、現在のユーザーの Advertising Token を取得します。

NOTE: UID2 Token が SSP から DSP に送信されるとき、ビッドストリーム内でどのように見えるかの例については、ビッドストリームで UID2 Token はどのように見えますか？ を参照してください。

<script>
  let advertisingToken = __uid2.getAdvertisingToken();
</script>
備考

返された Advertising Token をどのように SSP に渡すかを検討する必要があります。Prebid.js(UID2 Integration Overview for Prebid.js を参照) や Google Ad Manager Secure Signals(Google Ad Manager Secure Signals Integration Guide を参照) を使用するなど、Client-Side で UID2 を実装する他のいくつかのアプローチでは、実装に、返された Advertising Token の受け渡しを管理する関数が含まれています。UID2 SDK for JavaScriptを使用している場合は、これを自分で管理する必要があります。

ヒント

__uid2.getAdvertisingToken() を呼び出す代わりに、Step 1-g で設定したコールバックに渡された ID の advertising_token プロパティを使用することができます。このコールバックは ID が変更されるたびに呼び出されます。

Refresh Tokens​

初期化の一環として、SDK は ID の token auto-refresh を設定します。これは、ID 上のタイムスタンプ、または断続的なエラーによるリフレッシュの失敗によってバックグラウンドでトリガーされます。

StepEndpoint/SDKDescription
3-aUID2 SDK for JavaScriptSDK はバックグラウンドで自動的に UID2 Token をリフレッシュします。手動で操作する必要はありません。
3-bUID2 SDK for JavaScriptユーザーがオプトアウトしていない場合、POST /token/refresh エンドポイントは、自動的に新しい ID トークンを返します。

Clear Identity: User Logout​

クライアントのライフサイクルは、ユーザーがパブリッシャーのサイト (UID2 ではなく) からログアウトすることを決定したときに完了します。これにより、クライアントの ID セッションが終了し、ファーストパーティ Cookie 情報がクリアされます。

StepEndpoint/SDKDescription
4-aN/Aユーザーはパブリッシャーのアセットからログアウトします。
4-bUID2 SDK for JavaScriptSDKは、以下に示すように、disconnect() function を使用して、ファーストパーティ Cookie から UID2 ID をクリアし、クライアントのライフサイクルを切断します。
<script>
  __uid2.disconnect();
</script>

FAQs​

パブリッシャー向けのよくある質問については、FAQs for Publishers を参照してください。