| title | Client-Server Integration Guide for JavaScript |
|---|---|
| sidebar_label | Client-Server Integration for JavaScript |
| pagination_label | Client-Server Integration Guide for JavaScript |
| description | SDK for JavaScript を使用し、Server-Side でトークンを生成してパブリッシャーの Web ページに渡す必要がある標準的な Web インテグレーションシナリオをカバーするパブリッシャー向けの情報。 |
| hide_table_of_contents | false |
| sidebar_position | 2 |
| displayed_sidebar | docs |
import Link from '@docusaurus/Link'; import ExampleClientServerSendUid2ToSdk from '../snippets/_example-client-server-send-uid2-to-sdk.mdx'; import IntegratingWithSSO from '../snippets/_integrating-with-sso.mdx';
このガイドは、Web アセットを持つパブリッシャー向けに、RTB bidstream で UID2 を使用して ID トークンを生成し、サーバーサイドで UID2 Tokenを生成してパブリッシャーの 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 を参照してください。
実装例は、次の UID2 SDK インテグレーション例を参照してください。
このガイドでは、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 を参照してください。
:::tip ファーストパーティ Cookie とローカルストレージの実装の詳細は 将来変更される可能性があります。潜在的な問題を回避するため、ID 管理には SDK for JavaScript API Reference に記載されている機能を使用してください。 :::
SDK for JavaScript を使用しないパブリッシャーのインテグレーションシナリオは、Publisher Integration Guide, Server-Side を参照してください。
:::note Google Ad Managerを使用していて、セキュアシグナル機能を使用したい場合は、まずこのガイドの手順に従った後、Google Ad Manager Secure Signals Integration Guide の追加手順に従ってください。 :::
UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントを作成していない場合は、まず Account Setup ページの手順に従ってください。
アカウントの初期設定が完了すると、本番環境用の credentials を作成し、必要に応じて追加の値を設定できる UID2 Portal にアクセスするための手順とリンクが送信されます。詳細は、Getting Started with the UID2 Portal を参照してください。
Client-Server インテグレーションを行う場合は、UID2 Portal の API Keys ページで以下の値を設定する必要があります:
- API key、Client Key とも呼ばれます。
- Client secret、参加者と UID2 Servivce のみが知る値です。
:::important これらの値を安全に保管することは非常に重要です。詳細は、Security of API Key and Client Secret を参照してください。 :::
以下の図は、ユーザーの UID2 Token をパブリッシャーと確立するために必要なステップと、UID2 Token が RTB ビッドストリームとどのようにインテグレーションされるかを説明しています。
以下のセクションでは、図中の各ステップについての詳細を説明します:
- Establish identity: capture user data
- Bid Using UID2 Tokens
- Refresh Tokens
- Clear Identity: User Logout
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 に提供します。 |
最初のステップは、サーバーで UID2 Token を生成することです。
手順や例は、Server-Side Token Generation を参照してください。
Identity レスポンスを SDK に渡す必要があります。Sending the UID2 Token to the SDK を参照してください。
:::warning セキュリティ上の理由から、トークン生成に使用される API キーとシークレットはサーバーサイドで呼び出す必要があります。これらの値をクライアントサイドに保存しないでください。詳細は Security of API Key and Client Secret を参照してください。 :::
以下のコード例は、JavaScript と TypeScript でのステップ 1-f と 1-g の説明です。
SDKは、指定された callback function (ID の可用性を示します) を呼び出し、確立された ID をClient-Side で入札可能な状態にします。
:::tip コードの構造によっては、Step 1-f と 1-g のコールバックを 1 つのコールバック関数にまとめると便利かもしれません。 :::
有効な ID のステータスと利用可能性に基づいて、SDK は以下を実行します:
- バックグラウンドの token auto-refresh を設定します。
- ID 情報を ローカルストレージまたはファーストパーティクッキー に保存します。
- ID 情報を使用して、ターゲティング広告のリクエストを始めます。
ビッドステップを次の表に示します。
| Step | Endpoint/SDK | Description |
|---|---|---|
| 2-a | SDK for JavaScript | 以下に示すように、getAdvertisingToken() 関数 を使用して、現在のユーザーの Advertising Token を取得します。 |
:::note UID2 Token が SSP から DSP に送信されるとき、ビッドストリーム内でどのように見えるかの例は、ビッドストリームで UID2 Token はどのように見えますか？ を参照してください。 :::
<script>
let advertisingToken = __uid2.getAdvertisingToken();
</script>:::info
返された 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を使用している場合は、これを自分で管理する必要があります。
:::
:::tip
__uid2.getAdvertisingToken() を呼び出す代わりに、Step 1-g で設定したコールバックに渡された ID の advertising_token プロパティを使用することができます。このコールバックは ID が変更されるたびに呼び出されます。
:::
初期化の一環として、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 トークンを返します。 |
クライアントのライフサイクルは、ユーザーがパブリッシャーのサイト (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 for Publishers を参照してください。