Publisher Integration Guide, Server-Side
このガイドは、UID2 Token (Advertising Token) を RTB ビッドストリーム 用に生成するために、UID2 と直接インテグレーションを行いながら、UID2 対応シングルサインオンや ID プロバイダーではなく、すべてのインテグレーションをサーバーサイドで行うパブリッシャー向けのガイドです。
パブリッシャーが UID2 と Server-Side でインテグレーションするには、以下のオプションが利用可能です:
- SDK for Java (see Usage for Publishers section).
- SDK for Python (see Usage for Publishers section).
- Custom server code to generate and refresh the UID2 token by calling the POST /token/generate and POST /token/refresh endpoints.
ワークフローをデモするサンプルアプリケーションもあります。Sample Implementation を参照してください。
パブリッシャーインテグレーションオプションの完全な概要については、Publisher Integrations を参照してください。
UID2 と UID2 Token を使用してクライアントのアイデンティティを確立し、UID2 Token を取得するプロセスを容易にするために、SDK for JavaScript を使用することを検討してください。詳細は Client-Server Integration Guide for JavaScript を参照してください。
Introduction
このガイドでは、Client-Side または Server-Side SDK を使用せずインテグレーションを行う場合に考慮する必要がある basic steps について説明します。たとえば、以下のようなことを決定する必要があります:
- メールアドレスまたは電話番号を取得する機会を実装する: たとえば、プロモーションの交換、サインアップとサブスクリプション、またはマーケティングフォームの記入。
- UID2 ID 情報を管理し、ターゲティング広告に使用する
- UID2 Token をリフレッシュする
- ID が欠落している場合の処理
- ユーザーオプトアウトを管理する
FAQs も参照してください。
Integrating with Single Sign-On (SSO)
シングルサインオン(SSO)プロバイダーとのインテグレーションに関する情報は、Publisher Integration with SSO Providers を参照してください。
Complete UID2 Account Setup and Configure Account
UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントをまだ作成していない場合は、まず Account Setup ページの手順に従ってください。
アカウントの初期設定が完了すると、UID2 ポータルにアクセスするための手順とリンクが送信されます。UID2 ポータルでは、本番環境のための credentials を作成し、提供する必要がある追加の値を設定できます。詳細については、Getting Started with the UID2 Portal を参照してください。
Server-Side インテグレーションの場合、UID2 ポータルの API Keys ページで以下の値を設定する必要があります:
- API key、Client Key とも呼ばれます、
- Client secret、参加者と UID2 Service のみが知る値。
これらの値を安全に保管することが非常に重要です。詳細については、Security of API Key and Client Secret を参照してください。
Integration Steps
以下の図は、ユーザーがパブリッシャーと UID2 Token を確立するために必要なステップと、UID2 Token が RTB ビッドストリームとどのようにインテグレーションされるかを概説したものです。
Server-Side SDK を使用している場合、SDK はエンドポイントに関連するすべてのステップを処理します。たとえば、Step 1-d では、発行者はユーザーの DII をトークン生成サービスに送信します。
次のセクションでは、図中の各ステップについて詳細を説明します:
- Establish identity: capture user data
- Bid using a UID2 token
- Refresh a UID2 token
- Clear Identity: user logout
Establish Identity: Capture User Data
Step 1-c で認証が行われい、パブリッシャーがユーザーのメールアドレスや電話番号を検証した後、パブリッシャーは Server-Side で UID2 Token を生成するリクエストを送信することができます。次の表は、トークン生成ステップの詳細です。
このエンドポイントを直接呼び出す代わりに、SDK のいずれかを使用して管理することもできます。オプションの概要については、SDKs: Summary を参照してください。
| Step | Endpoint | Description |
|---|---|---|
| 1-d | POST /token/generate | パブリッシャーが UID2 を使用してアイデンティティを確立するには、2 つの方法があります: - UID2 対応のシングルサインオンプロバイダーとインテグレーションします。 - POST /token/generate エンドポイントを使って、ユーザーの正規化したメールアドレスまたは電話番号から UID2 Token を生成します。 |
| 1-e | POST /token/generate | ユーザーのメールアドレス、電話番号、またはそれぞれのハッシュからと、Refresh Token などの関連値から生成された UID2 Token を返します。 |
| 1-f | N/A | 返された advertising_token と refresh_token は、ユーザーに紐づくストレージに保存します。ファーストパーティクッキーのようなClient-Side のストレージや、Server-Sideのストレージを検討するとよいでしょう。 |
Bid Using a UID2 Token
UID2 ID 情報をどのように管理し、ターゲティング広告に使用したいかを検討す る必要があります。たとえば、返された UID2 token を SSP に渡す等。
| Step | Endpoint | Description |
|---|---|---|
| 2-a | N/A | Step 1-e の advertising_token を入札のために SSP に送信します。そのままの値を送信します。 |
UID2 Token が SSP から DSP に送信されるとき、ビッドストリーム内でどのように見えるかの例については、ビッドストリームで UID2 Token はどのように見えますか？ を参照してください。
Refresh a UID2 Token
POST /token/refresh エンドポイントを 使用して、常に有効で最新の UID2 Token を持つようにします。UID2 ローテーションと同期させるには、UID2 Token をリフレッシュする必要があります。さらに、トークンリフレッシュプロセスではユーザーのオプトアウトステータスをチェックし、ユーザーがオプトアウトしている場合は新しいトークンを送信しません。これによりトークンリフレッシュチェーンが終了します。その UID2 Token を二度と使用してはなりません。
UID2 の Opt-out ワークフローとユーザーが Opt-out する方法の詳細は、User Opt-Out を参照してください。
| Step | Endpoint | Description |
|---|---|---|
| 3-a | N/A | ユーザーがアセットに戻り、再びアクティブになったとき、UID2 Token をリフレッシュしてから、SSP に送信します。 |
| 3-b | POST /token/refresh | Step 1-e で取得した refresh_token をクエリパラメータとして送信します。 |
| 3-c | POST /token/refresh | UID2 Service は、オプトアウトしていないユーザーに対して新しい ID トークンを発行します。 |
| 3-d | N/A | POST /token/refresh エンドポイントから返される値、advertising_token と refresh_token を、ユーザーにリンクされるように配置します。ファーストパーティのクッキーのようなClient-Side のストレージか、サーバサイドのストレージを検討するとよいでしょう。 |
POST /token/generate または POST /token/refresh エンドポイントによって返された ID の refresh_from タイムスタンプからトークンのリフレッシュを始めてください。
Clear Identity: User Logout
ユーザーがログアウトした場合は、UID2 Token を使用しないでください。
| Step | Endpoint | Description |
|---|---|---|
| 4-a | N/A | ユーザーが パブリッシャーアセットからログアウトしました。 |
| 4-b | N/A | そのユーザー用に保存してある UID2 Token を削除します。UID2 Service とのやりとりは必要ありません。 |
Sample Implementation
Server-only のインテグレーションのためのサンプルアプリケーションをがあります。以下を参照してください:
- Server-Side UID2 Integration Example (sample implementation)
- Server-Side UID2 Integration Example (readme)
FAQs
パブリッシャー向けのよくある質問は、FAQs for Publishers を参照してください。