SDK for JavaScript Reference Guide
この 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 Version
このページは、最新の UID2 SDK for JavaScript バージョン 4 を説明しています。以前のバージョンを使用している場合は、Migration Guide を使用してインテグレーションをアップグレードすることを勧めます。必要に応じて、以下の以前のバージョンのドキュメントも利用できます:
Changes in Version 4
Version 4 には、Version 3 からの主な変更が含まれています:
-
New:
isIdentityAvailable()
関数は Version 3.10.0 でリリースされました。詳細については、isIdentityAvailable を参照してください。 -
Removed elements:
abort()
関数は v3 で非推奨となり、v4 には含まれていません。代わりに、abort()
と同じ機能を持つ disconnect() を使用してください。また、より徹底的な切断ロジックも含まれています。hasIdentity()
関数は削除されました。この関数は公開されていなかったため、使用されていない可能性がありますが、他の関数で使用されていたため、公開されていました。この関数を使用している場合は、isIdentityAvailable を使用してください。
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 の実装の場合、ドメイン名やモバイルアプリ ID などの設定値を設定します。
- オプションとして、チームメンバーに関する情報を設定するなど、他の値を設定します。
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 を含める最も簡単な方法です。
本ドキュメントの最新の更新時点で、最新のバージョンは 4.0.1 です。利用可能なバージョンの一覧は 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-4.0.1.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-4.0.1.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);
}
});
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 を指定できます。
Provide an Identity by Calling setIdentity
init
が完了したら、いつでも setIdentity
を呼び出して、SDK に新しい ID を渡すことができあす。
API Reference
SDK for JavaScript とのすべてのインストラクションは、グローバルな __uid2
オブジェクトを介して行われます。このオブジェクトは UID2
クラスのインスタンスであり、以下の JavaScript 関数はすべて UID2
クラスのメンバーです:
- constructor()
- init()
- getAdvertisingToken()
- getAdvertisingTokenAsync()
- isLoginRequired()
- isIdentityAvailable()
- disconnect()
- callbacks
- setIdentity()
- getIdentity()
- isInitComplete()
constructor()
UID2 オブジェク トを構築します。SDK がロードされると、自動的に UID2 クラスのインスタンスが初期化され、グローバルな __uid2 オブジェクトとして保存されます。高度なインテグレーションでは、このコンストラクタを直接使用することができますが、SDK の複数のアクティブなインスタンスが実行されないように注意する必要があります。これはサポートされていない使用例です。
この関数を呼び出す代わりに、グローバルの __uid2
オブジェクトを使用することができます。
init(opts: object): void
SDK を初期化し、ターゲティング広告用のユーザー ID を確立します。
この関数について知っておくべきことは以下のとおりです:
init()
は SDK がロードされた後であれば、いつでも呼び出すことができます。これを行うには、Array Push Pattern を使用してSdkLoaded
イベントを処理するコールバック関数を登録することを推奨します。このパターンを使うことで、スクリプトのロード順序に関係なくコードが動作し、スクリプトタグでasync
やdefer
を使っても UID2 SDK のエラーが発生しないようにすることができます。init()
呼び出しのidentity
プロパティは、POST /token/generate または POST /token/refresh 呼び出しが成功したときに返されるレスポンス JSON オブジェクトのbody
プロパティを参照します。Server-side のインテグレーションで常に現在のトークンを使用できるようにしていて、JavaScript を使用して ID を提供するほうが便利な場合は、この方法を使用するとよいでしょう。init()
呼び出しのidentity
プロパティが不正な場合、SDK はローカルストレージまたはクッキーから ID をロードしようとします。init()
が完了すると、すべてのコールバックはInitCompleted
イベントを受信します。このイベントのペイロードのidentity
プロパティが null の場合、ID をロードできなかったことになるので、provide an identity to the SDK する必要があります。これは、Server-side のインテグレーションによって常に現在の ID が利用可能であることが保証されておらず、必要な場合にのみサーバーから ID を要求する必要がある場合に推奨される ID の提供方法です。- 渡された UID2 情報をセッションに保存するためにファーストパーティクッキ ー (UID2 Storage Format を参照) を使用している場合、異なるドメインのページから
init()
を呼び出すと、そのクッキーにアクセスできないことがあります。cookieDomain
オプションとcookiePath
オプションで、クッキーに使用する設定を調整することができます。
- 特定の動作を調整するために、初期化呼び出しにはオプションの設定 init prarmeters を含めることができます。
以下は、Server-side で生成された ID を含むコールバックを使った init()
呼び出しの例です。
<script>
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType, payload) => {
if (eventType === "SdkLoaded") {
__uid2.init({
identity : { // The `body` property value from the token/generate or token/refresh API response.
"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"
}
});
}
});
</script>
以下は、以前に提供された ID があれば、それをローカルストレージからロードする init()
呼び出しの例です。このようなスクリプトは、ID が確立された後にユーザーが訪れる可能性のある任意のページに配置することができます。
<script>
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType, payload) => {
if (eventType === "SdkLoaded") {
__uid2.init({}); // Note that you must provide a configuration object, even if you're not providing any options.
}
});
</script>
Init Parameters
opts
オブジェクトは、以下のプロパティをサポートしています。
Property | Data Type | Attribute | Description | Default Value |
---|---|---|---|---|
identity | object | オプション | POST /token/generate または POST /token/refresh 呼び出しが成功したときの body プロパティ値です。ファーストパーティクッキー からの ID を使用するには、このプロパティを空にしておきます。 | N/A |
baseUrl | string | オプション | POST /token/refresh エンドポイントを呼び出す際に使用する UID2 Operator のカスタム Base URLです。 たとえば: https://my.operator.com . | https://prod.uidapi.com . |
refreshRetryPeriod | number | オプション | 断続的なエラーが発生した場合に、トークンのリフレッシュを再試行するミリ秒数です。 この値は 1000 以上でなければなりません。 | 5000 |
cookieDomain | string | オプション | UID2 cookie に適用するドメイン名文字列です。 たとえば、 baseUrl が https://my.operator.com の場合、cookieDomain の値は operator.com となります。 | undefined |
cookiePath | string | オプション | UID2 cookie に適用する Path 文字列です。 | / |
useCookie | boolean | オプション | この値を true に設定すると、SDK はローカルストレージではなくクッキーに ID を保存します。この値がfalseであるか、提供されていない場合でも、ファーストパーティクッキーを使 用して ID を提供することができます。 |
Multiple Init Calls
init()
関数は何度でも呼び出すことができます。ほとんどの場合、特定の init parameter の最新の値を受け入れます。たとえば、baseUrl
が 2 回呼び出され、それぞれ異なる baseUrl
が渡された場合、baseUrl
変数は 2 回目の呼び出しからの値に更新されます。
この機能には 2 つの例外があります:
- 新しい identity が提供され、新しい identity が現在の identity よりも早く失効する場合、新しい identity は現在の identity を置き換えません。
- 移行、渡されたコールバック関数のすべてに対し、Array Push Pattern を使用して既存のコールバック配列に関数が追加されます。
useCookie
が更新されると、identity の場所が変わります。たとえば、値が true
から false
に更新されると、ファーストパーティクッキーが削除され、identity がローカルストレージに追加されます。
Init Config
init()
を呼び出すと、初期設定がファーストパーティクッキーまたはローカルストレージに保存されます。この設定には、baseUrl
、useCookie
、refreshRetryPeriod
、cookiePath
、cookieDomain
が含まれる場合があります。この設定は bootstrap init に使用され、その後のページロードでの読み込み時間を短縮します。init()
に対する後続の呼び出しは、最新のパラメータで設定を更新します。
Self Bootstrap
コンストラクタが完了し、SDK が window オブジェクトに配置されると、コードはローカルストレージとクッキーストレージをチェックして、保存された init config を取得します。Condig が存在する場合、init()
は自動的にその config のパラメータで呼び出され、その結果、init()
が必要な関数を使用できるようになります。