Client-Server Integration Guide for JavaScript

このガイドは、Web アセットを持つパブリッシャー向けに、RTB bidstream で UID2 を使用して ID トークンを生成し、サーバーサイドで UID2 トークンを生成してパブリッシャーの Web ページに渡し、JavaScript の UID2 SDK を使用してクライアントサイドでトークンをリフレッシュする方法を説明します。

これは、JavaScript インテグレーションステップが Client-Side であり、その他のステップが Server-Side であるため、Client-Server インテグレーションと呼ばれます。

Client-Side の JavaScript の変更だけで UID2 とインテグレーションする場合は、Client-Side Integration Guide for JavaScript を参照してください。

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

Sample Implementation

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

コードとドキュメント: UID2 SDK Secure Signals Integration Example
ランニングサイト: Client-Server UID2 SDK Integration Example

Introduction

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

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

UID2 の Opt-out ワークフローとユーザーが Opt-out する方法の詳細については、User Opt-Out を参照してください。

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

ヒント

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

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

注記

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

Integration Steps

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

Publisher Flow

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

Establish identity: capture user data
Bid Using UID2 Tokens
Refresh Tokens
Clear Identity: User Logout

Establish Identity: Capture User Data

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

Step	Endpoint/SDK	Description
1-d	POST /token/generate	POST /token/generate エンドポイントを使用して、ユーザーから提供されたメールアドレスまたは電話番号を使用して UID2 Token を生成します。正規化されていることを確認してください。
1-e	POST /token/generate	ユーザーのメールアドレス、電話番号、またはそれぞれのハッシュから生成された UID2 Token を返します。
1-f	SDK for JavaScript	Step 1-e で返された UID2 Token を、SDK の init()関数の `identity` プロパティで SDK に送信し、以下に示すようにコールバック関数を指定します。このメカニズムにより、ユーザーがログアウトするまで、UID2 Token がターゲティング広告に利用できるようになります。
1-g	SDK for JavaScript	SDK から ID 更新を受け取り、ターゲティング広告を開始するために使用するコールバック関数を SDK に提供します。

Generating a UID2 Token on the Server

最初のステップは、サーバーで UID2 Token を生成することです。

手順や例については、Server-Side Token Generation を参照してください。

Identity レスポンスを SDK に渡す必要があります。Sending the UID2 Token to the SDK を参照してください。

警告

セキュリティ上の理由から、トークン生成に使用される API キーとシークレットはサーバーサイドで呼び出す必要があります。これらの値をクライアントサイドに保存しないでください。詳細は Security of API Key and Client Secret を参照してください。

Sending the UID2 Token to the SDK

以下のコード例は、JavaScript と TypeScript でのステップ 1-f と 1-g の説明です。

JavaScript
TypeScript

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": "A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g",
        "identity_expires": 1724899014352,
        "refresh_expires": 1724981814352,
        "refresh_from": 1724896314352,
        "refresh_response_key": "TS0H0szacv/F3U8bQjZwjSaZJjxZbMvxqHn1l3TL/iY=",
        "refresh_token": "AAAAAGYzgUszke2sV9CxXnxyFfUU+KDCJUCXNbj1/FVcCjvR7K07jYaWe44wxM6SOTwG7WQB4XfIcquMqH57iHUnAu1zacYf9g58BtbhKCYWTwrdpB0fSqTANBXOYy+yBnl6tLRwVv32LqRCj76D8meO4tw+MKlUAc2EoFzFNPSfZLpA3Jk4q68vH6VJH/WIuu1tulrVm5J8RZAZnmTlEcsPdjoOC6X4w3aAwiwtbeGw7yOO0immpVoC5KaXnT9olRPTlrt8F9SvebLIcqkYhvRMPpl1S89yeneyGo++RnD9qSHIrfu9To3VwYW018QuvyA15uv4No4BoAzyPuHqzQ8gAs6csWwZ7VwfYD7DSJXlQiIpwzjA2Hl8mgg/5fcXwKEJ"
      }
    });
  }
});

// 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.
    }
  }
});

import { EventType, CallbackPayload } from "./callbackManager";

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];

// Step 1-f
window.__uid2.callbacks.push((eventType: EventType, payload: CallbackPayload) => {
  if (eventType === 'SdkLoaded') {
    __uid2.init({
      identity : {
        "advertising_token": "A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g",
        "identity_expires": 1724899014352,
        "refresh_expires": 1724981814352,
        "refresh_from": 1724896314352,
        "refresh_response_key": "TS0H0szacv/F3U8bQjZwjSaZJjxZbMvxqHn1l3TL/iY=",
        "refresh_token": "AAAAAGYzgUszke2sV9CxXnxyFfUU+KDCJUCXNbj1/FVcCjvR7K07jYaWe44wxM6SOTwG7WQB4XfIcquMqH57iHUnAu1zacYf9g58BtbhKCYWTwrdpB0fSqTANBXOYy+yBnl6tLRwVv32LqRCj76D8meO4tw+MKlUAc2EoFzFNPSfZLpA3Jk4q68vH6VJH/WIuu1tulrVm5J8RZAZnmTlEcsPdjoOC6X4w3aAwiwtbeGw7yOO0immpVoC5KaXnT9olRPTlrt8F9SvebLIcqkYhvRMPpl1S89yeneyGo++RnD9qSHIrfu9To3VwYW018QuvyA15uv4No4BoAzyPuHqzQ8gAs6csWwZ7VwfYD7DSJXlQiIpwzjA2Hl8mgg/5fcXwKEJ"
      }
    });
  }
});

// Step 1-g
window.__uid2.callbacks.push((eventType: EventType, payload: CallbackPayload) => {
  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 は以下を実行します:

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

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

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

注記

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

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

備考

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

ヒント

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

Refresh Tokens

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

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

Clear Identity: User Logout

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

Step	Endpoint/SDK	Description
4-a	N/A	ユーザーはパブリッシャーのアセットからログアウトします。
4-b	SDK for JavaScript	SDKは、以下に示すように、disconnect() function を使用して、ファーストパーティ Cookie から UID2 ID をクリアし、クライアントのライフサイクルを切断します。

<script>
  __uid2.disconnect();
</script>

FAQs

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

Sample Implementation​

Introduction​

Integration Steps​

Establish Identity: Capture User Data​

Generating a UID2 Token on the Server​

Sending the UID2 Token to the SDK​

Bid Using UID2 Tokens​

Refresh Tokens​

Clear Identity: User Logout​

FAQs​