SDK for JavaScript Reference Guide (v3)
このドキュメントは、SDK for JavaScript のバージョン 3 用で最新バージョンではありません。このバージョンを使用している場合は、アップグレードを勧めます。移行ガイドが含まれている SDK for JavaScript リファレンスガイド を参照してください。
この SDK を使用して、UID2 を使用したクライアント ID の生成または確立、ターゲティング広告 用の Advertising Token の取得、および UID2 Token の自動リフレッシュを容易に行うことができます。
以下のセクションでは、UID2 ID の確立のための高レベルな ワークフロー、SDK API リファレンス、および UID2 ストレージフォーマット を説明します。
UID2 Identify Module、または UID2 サポートのある他の製品と Prebid.js を使用している場合、SDK を使用する必要はありません。Prebid.js モジュールがすべてを管理します。詳細については、UID2 Client-Side Integration Guide for Prebid.js を参照してください。
このページでは、SDK のバージョン 3 について説明します。以前のバージョンを使用している場合は、移行ガイド を使用してインテグレーションをアップグレードすることを勧めます。必要に応じて、SDK の以前のバージョン のドキュメントも利用できます。
コンテンツパブリッシャー 向けのインテグレーション手順は、以下のガイドを参照してください:
Functionality
この SDK は、独自にカスタマイズした UID2 インテグレーションを行いたいパブリッシャーの開発を簡素化します。次の表は、SDK がサポートする機能を示しています。
Encrypt Raw UID2 to UID2 Token for Sharing | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s | Monitor Rotated Salt Buckets |
---|---|---|---|---|---|
— | — | ✅ | ✅ | — | — |
Sample Implementation
サンプルアプリケーションと関連するドキュメントは以下を参照してください:
- The UID2 Google Secure Signals with SDK v3 example:
- Code and docs
- Running site: Client-Side UID2 SDK Integration Example
- The example of JavaScript client-side integration: Code and running site (Client-Side Integration Example, UID2 JavaScript SDK).
UID2 Account Setup
UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントをまだ作成していない場合は、まず Account Setup ページに記載されている手順に従ってください。
API Permissions
アカウントの初期設定が完了すると、UID2 Portal にアクセスするための手順とリンクが提供されます。以下の操作を行うことができます:
- アカウントの credentials を生成します。
- オプション: Client-Side の実装では、ドメイン名などの設定値を設定します。
- オプションで、チームメンバーに関する情報の設定など、他の値を設定します。
SDK が提供する特定の機能の使用権限が付与 され、そのアクセスに必要な資格情報が提供されます。
SDK Version
このドキュメントは SDK for JavaScript version 3 用です。
GitHub Repository
この SDK のソースは、以下のオープンソースの GitHub リポジトリにあります:
SDK Distribution
この SDK は、以下のロケーションに公開されています:
-
NPM: https://www.npmjs.com/package/@uid2/uid2-sdk
これは、SDK を自分のビルドに含める最も簡単な方法です。他の JavaScript または TypeScript ファイルと一緒に SDK をバンドルしたい場合に使用します。
また、TypeScript の型情報を使用して、スクリプトを CDN 経由でロードすることもできます。この場合、インストールした NPM パッケージのバージョンが CDN URL のバージョンと一致していることを確認してください。
-
CDN:
https://cdn.prod.uidapi.com/uid2-sdk-${VERSION_ID}.js
これは、ビルドパイプラインを使用し て JavaScript をバンドルしていない場合に、サイトに SDK を含める最も簡単な方法です。
本ドキュメントの最新の更新時点で、最新のバージョンは 3.4.5 です。利用可能なバージョンの一覧は the list of available versions を参照してください。
-
CDN (Integration):
https://cdn.integ.uidapi.com/uid2-sdk-${VERSION_ID}.js
このインテグレーション URL には minified されていないコードが含まれており、テスト目的でのみ使用することができます。本番サイトにはこの URL を使用しないでください。
Terminology
このドキュメントでは、以下の用語が使われます:
- ID とは、POST /token/generate または POST /token/refresh エンドポイントによって返される、UID2 Token、Refresh Token、および Timestamp などの関連値を含む値のパッケージを指します。
- Advertising Token は UID2 Token を指します。
- Callback functionは、本 SDK の現在のバージョン用に構築され、Array Push Pattern を使用して登録されたコールバック関数を指します。
- Legacy callback function は、この SDK のバージョン 1.x または 2.x 用に構築され、
init
の呼び出しで登録されたコールバック関数を指しま す。
Include the SDK Script
UID2 をターゲティング広告に使用したいすべてのページに、以下の SDK スクリプトを含めます:
<script src="https://cdn.prod.uidapi.com/uid2-sdk-3.4.5.js" type="text/javascript"></script>
Async or Defer Loading the SDK Script
Version 3 以降の SDK は、async
または defer
スクリプトローディングとともに使用することができます。
サイトで async
または defer
スクリプトのロードを使用している場合は、次のようにしてください:
-
(必須)
SdkLoaded
イベントを受信したときに、callback function から__uid2.init
を呼び出していることを確認します。 -
(必須) Scriptタグに関連する属性を追加します。
-
(推奨) 以下の例のように、Script タグがページの
<head>
部分にあることを確認してください:<head>
<!-- ... -->
<script async src="https://cdn.prod.uidapi.com/uid2-sdk-3.4.5.js" type="text/javascript"></script>
<!-- ... -->
</head>
Workflow Overview
SDK を使用して UID2 ID を確立するための Client-Side ワークフローは、以下の Step で構成されます:
-
Array Push Pattern を使ってコールバック関数を登録します。
-
コールバックが
SdkLoaded
イベントを受信したら、init 関数を使用して SDK を初期化します。 -
イベントリスナーが
InitCompleted
イベントを受信するのを待ちます。イベントデータは ID が利用可能かどうかを示します:- ID が利用可能な場合、その ID がイベントペイロードに返されます。SDK は background token auto-refresh を設定します。
- ID が利用できない場合、ペイロードの
identity
プロパティは null になります。provide an identity to the SDK するまで、UID2 は利用できません。
-
ID の変更を示す
IdentityUpdated
コールバックイベントを処理します。イベントペイロードの
identity
プロパティには新しい ID が格納されるか、有効な ID がない場合は null が格納されます。 -
状態に基づいて ID を処理します:
- Advertising Token が利用可能な場合、それを使用してターゲティング広 告のリクエストを開始します。
- Advertising Token が利用可能でない場合は、ターゲティング広告を使用しないか、同意フォームでユーザーをデータキャプチャにリダイレクトします。
より詳細な Web インテグレーションの手順については、Client-Server Integration Guide for JavaScript を参照してください。
Background Token Auto-Refresh
SDKの initialization の一部として、ID の Token Auto-refresh が設定され、ID の Timestamp または断続的なエラーによるリフレッシュの失敗によってバックグラウンドでトリガーされます。
Token の Auto-refresh について知っておくべきことは以下のとおりです:
- 一度にアクティブにできる Token refresh call は 1 つだけです。
- POST /token/refresh レスポンスが、ユーザーがオプトアウトしたため、あるいは Refresh Token の有効期限が切れたために失敗した場合、バックグラウンドでの自動更新処理を一時停止します。UID2ベースのターゲティング広告を再び使用するには、ユーザーからメールアドレスまたは電話番号を取得する必要があります(isLoginRequired()は
true
を返します)。 - SDK の初期化時に指定された callback function は、以下の場合に呼び出されます:
- リフレッシュが成功するたびに呼び出されます。
- ユーザがオプトアウトした場合など、IDが無効になった場合。
NOTE: ID が一時的に使用できなくなり、自動リフレッシュに失敗し続けた場合、コールバックは呼び出されません。この場合、SDK は有効期限が切れていない限り、既存の Advertising Token を使用し続けます。
- disconnect() 呼び出しはアクティブなタイマーをキャンセルします。
Callback Function
Array Push Pattern を使用して、UID2 SDK からイベントを受信する関数を登録できます。現在利用可能なイベントはいくつかあります:
SdkLoaded
は SDK がパースされ、グローバルな__uid2
オブジェクトが構築された後に発生します。これはinit()
を呼び出す際に便利で、特にスクリプトのロード順序が保証されていない場合に便利です (例えば、スクリプトのロードにasync
やdefer
を使用している場合など)。init()
が終了し、SDK を使用できる状態になるとInitCompleted
が発生します。init
呼び出しで ID が提供された場合、または SDK が以前に提供された ID をロードできた場合、その ID がペイロードに含まれます。IdentityUpdated
は、新しいIDが利用可能になるか、既存の ID が利用できなくなるたびに発生します。
コールバック関数はいくつでも用意でき、どこからでも登録できます。これにより、サイトにとって意味のある方法でコードを分割することができます。
Callback Function Signature
コールバック関数は、イベントタイプとペイロードの2つのパラメータを受け取る必要があります。ペイロードのタイプはイベントのタイプにより異なります。
次の例のコールバックは SdkLoaded
イベントを処理して init を呼び出し、init
が完了した後に ID が利用できない場合は InitCompleted
イベントを使用して ID を提供します。
- JavaScript
- TypeScript
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType, payload) => {
if (eventType === 'SdkLoaded') {
__uid2.init({});
}
if (eventType === 'InitCompleted' && !payload.identity) {
const generatedIdentity = await requestIdentityFromServer(); // Call your server-side integration to generate a token for the logged-in user
__uid2.setIdentity(generatedIdentity);
}
});
import { EventType, CallbackPayload } from "./callbackManager";
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType: EventType, payload: CallbackPayload) => {
if (eventType === 'SdkLoaded') {
__uid2.init({});
}
if (eventType === 'InitCompleted' && !payload.identity) {
const generatedIdentity = await requestIdentityFromServer(); // Call your server-side integration to generate a token for the logged-in user
__uid2.setIdentity(generatedIdentity);
}
});
Event Types and Payload Details
Event | Payload | Details |
---|---|---|
SdkLoaded | {} | SDK スクリプトがロードされ、グローバルな __uid2 が構築されたときに呼び出されます。このイベントを受け取ると、安全に __uid2.init を呼び出すことができます。コールバックは常にこのイベントを一度だけ受け取ります。コールバックが登録されたときに SDK が既にロードされていた場合、コールバックは直ちにこのイベントを受け取ります。 |
InitCompleted | { identity: Identity | null } | init() が終了すると呼び出されます。コールバックは init が正常に呼び出されている限り、常にこのイベントを一度だけ受け取ります。コールバックが登録されたときに init が完了していた場合は、SdkLoaded イベントを受信した直後にこのイベントを受け取ります。 |
IdentityUpdated | { identity: Identity | null } | 現在の ID が変更されるたびに呼び出されます。コールバックが登録された後に ID が変更されなかった場合、コールバックはこのイベントを受け取りません。 |
Identity
型は init()
を呼び出す時に指定できる ID と同じ型です。
Array Push Pattern
順番にロードされることが保証されていないスクリプトタグ (例えば、async
や defer
スクリプトタグを使用している場合など) を最適にサポートするために、コールバックを登録するには以下のパターンを使用します:
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push(callbackFunction);
これにより、以下が保証されます:
- SDK がロードされる前にコードを実行した場合 (つまり、グローバルな
__uid2
オブジェクトが利用できない場合)、SDK が見つけることができるコールバックを提供することができます。 - あなたのコードより先に SDK が実行された場合、
__uid2
オブジェクトやcallbacks
配列は上書きされません。 - このパターンを使用して複数のコールバックが登録された場合、それらは互いに上書きされません。
Provide an Identity to the SDK
SDK がローカルストレージまたはクッキーから以前に保存された ID をロードできる場合を除き、SDK に ID を提供する必要があります。これにはいくつかの方法があります:
- Provide an Identity by Setting a First-Party Cookie
- Provide an Identity in the Call to
init
- Provide an Identity by Calling
setIdentity
Provide an Identity by Setting a First-Party Cookie
storage format section で説明されているように、ファーストパーティクッキーを保存していて、その値がローカルストレージで利用可能な値よりも新しい場合、SDK はその値をクッキーからロードします。もし useCookie
init オプションを true
に設定した場合、SDK は常にこの値をロードし、ローカルストレージをチェックしません。init parameters を使用して、クッキーに関することを制御できます。
Provide an Identity in the Call to init
init
を呼び出す時に、新しい ID を指定できます。