メインコンテンツまでスキップ

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 SharingDecrypt UID2 Token to Raw UID2Generate UID2 Token from DIIRefresh UID2 TokenMap DII to Raw UID2sMonitor Rotated Salt Buckets
——✅✅——

Sample Implementation​

サンプルアプリケーションと関連するドキュメントは以下を参照してください:

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 で構成されます:

  1. Array Push Pattern を使ってコールバック関数を登録します。

  2. コールバックが SdkLoaded イベントを受信したら、init 関数を使用して SDK を初期化します。

  3. イベントリスナーが InitCompleted イベントを受信するのを待ちます。イベントデータは ID が利用可能かどうかを示します:

    • ID が利用可能な場合、その ID がイベントペイロードに返されます。SDK は background token auto-refresh を設定します。
    • ID が利用できない場合、ペイロードの identity プロパティは null になります。provide an identity to the SDK するまで、UID2 は利用できません。

  4. ID の変更を示す IdentityUpdated コールバックイベントを処理します。

    イベントペイロードの identity プロパティには新しい ID が格納されるか、有効な ID がない場合は null が格納されます。

  5. 状態に基づいて 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 を提供します。

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

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 を提供する必要があります。これにはいくつかの方法があります:

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()​

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 オブジェクトは、以下のプロパティをサポートしています。

PropertyData TypeAttributeDescriptionDefault Value
identityobjectオプションPOST /token/generate または POST /token/refresh 呼び出しが成功したときの body プロパティ値です。
ファーストパーティクッキー からの ID を使用するには、このプロパティを空にしておきます。		N/A
baseUrlstringオプションPOST /token/refresh エンドポイントを呼び出す際に使用する UID2 Operator のカスタム Base URLです。
たとえば: https://my.operator.com.		https://prod.uidapi.com.
refreshRetryPeriodnumberオプション断続的なエラーが発生した場合に、トークンのリフレッシュを再試行するミリ秒数です。
この値は 1000 以上でなければなりません。		5000
cookieDomainstringオプションUID2 cookie に適用するドメイン名文字列です。
たとえば、baseUrl が https://my.operator.com の場合、cookieDomain の値は operator.com となります。		undefined
cookiePathstringオプションUID2 cookie に適用する Path 文字列です。/
useCookiebooleanオプションこの値を true に設定すると、SDK はローカルストレージではなくクッキーに ID を保存します。この値がfalseであるか、提供されていない場合でも、ファーストパーティクッキーを使用して ID を提供することができます。

Multiple Init Calls​

init() 関数は何度でも呼び出すことができます。ほとんどの場合、特定の init parameter の最新の値を受け入れます。たとえば、baseUrl が 2 回呼び出され、それぞれ異なる baseUrl が渡された場合、baseUrl 変数は 2 回目の呼び出しからの値に更新されます。

この機能には 2 つの例外があります:

  1. 新しい identity が提供され、新しい identity が現在の identity よりも早く失効する場合、新しい identity は現在の identity を置き換えません。
  2. 移行、渡されたコールバック関数のすべてに対し、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() が必要な関数を使用できるようになります。

Errors​

init() 関数は、以下のエラーを throw することがあります。

ErrorDescription
TypeError次のいずれかの問題が発生しました:
  • opts の値がオブジェクトではありません。
  • レガシーコールバックが提供されているが、関数ではありません。
  • refreshRetryPeriod が提供されているが、数値ではありません。
RangeErrorリフレッシュの再試行期間が 1000 未満である。

Legacy Callback Function​

これは後方互換性のためだけに提供されています。新しいインテグレーションでは、新しい callback function を使う必要があります。レガシーコールバックは Array Push Pattern を使って登録することができません。また、新しいコールバックは init に渡すことができません。

詳細は、以前のバージョンの SDK のドキュメントのLegacy Callback Function を参照してください。

すでにレガシーコールバック関数を使用してインテグレーションを構築している場合は、現在のバージョンの SDK で変更なく使用できます。ただし、この機能は SDK の将来のバージョンで削除される予定です。新しいスタイルの callback function を使用するようにインテグレーションを更新することを強く推奨します。

getAdvertisingToken(): string​

現在の Advertising Token を取得します。この関数は、init() を呼び出さずに呼び出すことができ、ローカルストレージまたはファーストパーティクッキーに保存されている場合はトークンを返します。

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

getAdvertisingToken() 関数を使うと、初期化完了時のコールバックだけでなく、どこからでも Advertising Token にアクセスすることができます。この関数は以下の条件のいずれかに該当する場合に undefined をします:

この関数は、以下の条件のいずれかに該当する場合、undefined を返します:

  • SDK の初期化は完了していますが、使用する有効な Identity がありません。
  • SDK の初期化は完了しましたが、自動更新により Identity がクリアされました—たとえば、ユーザーがオプトアウトした場合などです。

ID が利用できない場合は、isLoginRequired() 関数を使用して最良の対処法を決定します。

getAdvertisingTokenAsync(): Promise​

現在の Advertising Token の Promise 文字列を取得します。

この関数は、init() の呼び出しの前でも後でも呼び出すことができます。返された promise は、Advertising Token が利用可能かどうかに基づいて Settle されます:

  • Advertising Token が利用可能な場合、Promise は現在の Advertising Token で実行されます。
  • Advertising Token が利用可能であれば、Promise は現在の Advertising Token で実行されます。Advertising Token が一時的にでも利用できない場合、Promise は Error のインスタンスで拒否されます。この場合に最適なアクションを決定するには、isLoginRequired() を使います。

init の完了後に利用可能な ID を受信するだけで、ID の更新の受信を継続したくない場合は、この関数を使用して Client-side JavaScript SDK の初期化の完了の通知を受け取ることができます。

備考

もし getAdvertisingTokenAsync() 関数が初期化が完了した 後 に呼ばれた場合、Promise は現在の状態に基づいて即座に Settle されます。

ヒント

callback function を使って、ID が変更されるたびに通知を受ける方が簡単かもしれません。

<script>
  __uid2.getAdvertisingTokenAsync()
    .then(advertisingToken => { /* initiate targeted advertising */ })
    .catch(err => { /* advertising token not available */ });
</script>

isLoginRequired(): boolean​

UID2 ログイン POST /token/generate 呼び出しが必要かどうかを指定します。

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

Return Values​

ValueDescription
trueID が利用できません。この値は以下のいずれかを示します:
  • Refresh token の有効期限が切れた。
  • ファーストパーティクッキーは利用できず、サーバーで生成した ID も提供されていません。
falseこの値は以下のいずれかを示します:
  • ID が存在し、有効。
  • ID の有効期限が切れており、断続的なエラーによりトークンがリフレッシュされなかった。
  • ID の有効期限が切れており、断続的なエラーによりトークンがリフレッシュされなかった。

isIdentityAvailable(): boolean​

Identity が利用可能かどうかを判断します。たとえば、ローカルストレージまたはクッキーに有効な ID があるか、またはすでに ID がリクエストされているかどうかを判断します。

もし false であれば、UID2 POST /token/generate 呼び出しが必要です。

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

Return Values​

ValueDescription
trueこの値は、以下のいずれかを示します:
  • ファーストパーティクッキーまたはローカルストレージに ID が存在し、有効です。
  • ID の有効期限が切れており、断続的なエラーによりトークンがリフレッシュされませんでした。成功した自動リフレッシュ試行の後、ID が復元される可能性があります。
falseこの値は、以下のいずれかを示します:
  • ユーザーがオプトアウトしています。
  • ID が存在しますが、リフレッシュトークンが期限切れです。
  • ID が期限切れで、リフレッシュトークンが有効でもリフレッシュされませんでした。
  • ファーストパーティクッキーが利用できず、サーバーで生成された ID も提供されていません。

disconnect(): void​

UID2 ID をファーストパーティクッキーとローカルストレージから消去します (UID2 ストレージフォーマット を参照)。これによりクライアントの ID セッションが閉じられ、クライアントのライフサイクルが切断されます。

ユーザーがパブリッシャーのサイトからログアウトしたら、次の呼び出しを行います:

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

この関数が実行されると、getAdvertisingToken() 関数は undefined を返し、isLoginRequired() 関数は true を返します。

警告

SDK が正しいクッキーにアクセスするために cookieDomain または cookiePath を指定する必要があり、かつ init が完了していない場合、SDK はクッキーをクリアできません。この場合、エラーは発生しません。

callbacks​

これは、登録されたコールバックをすべて格納する配列です。Array Push Pattern を使ってのみ、この配列とやりとりする必要があります。

setIdentity(identity: Identity): void​

UID2 SDK に新しい ID を提供するには、この関数を使用します。既存のリフレッシュ試行はすべてキャンセルされ、新しい ID が今後のすべての操作に使用されます。新しいリフレッシュタイマーが開始されます。ID が検証されると、登録されているすべてのイベントハンドラが新しい ID を含む IdentityUpdated イベントと共に呼び出されます。

setIdentity は init が完了する前に呼び出されるとエラーを throw します。

ヒント

setIdentity() は、ページがシングルページのアプリで、最初に読み込んだときに ID が利用できない場合に便利です。これにより、ページロード時に init (および保存されている ID を読み込む) を呼び出しし、保存されている ID がない場合は後で ID を指定することができます。

getIdentity(): Identity | null​

有効な ID がある場合は、現在格納されている ID を返します。この関数を使用するためにinit()を呼び出す必要はありません。

利用可能な有効な ID がある場合、返り値は保存されている完全な ID を表すオブジェクトです。オブジェクトのプロパティは、contents structure セクションで説明した、格納されている値と同じです。

現在有効な ID がない場合 (ID が一時的に使用できないだけであっても)、戻り値は null です。ID が一時的に使用できないだけなのかどうかを知る必要がある場合は isLoginRequired() を呼び出します。

isInitComplete(): boolean​

init() 関数が少なくとも一度呼び出された場合、true を返します。

init() が一度も呼び出されたことがない場合、false を返します。

UID2 Storage Format​

SDK はユーザーの ID を保存するのに、ローカルストレージかファーストパーティクッキーのどちらかを使用します。デフォルトではローカルストレージを使用しますが、init parameter を使用して変更できます。

ローカルストレージを使用する場合でも、SDK はファーストパーティクッキーに利用可能な新しい ID があるかどうかを確認します。これにより、SDK はローカルストレージを利用しながら、ファーストパーティクッキーを設定することでIDを提供することができます。

クッキーが使用されている場合、クッキーは次の表のプロパティを使用します。

PropertiesDefault ValueComments
Name__uid_2N/A
ExpiryN/A値は、POST /token/generate または POST /token/refresh レスポンスで指定された Refresh Token の有効期限タイムスタンプです。
Path/別の値を使用したい場合は、SDK の初期化時に cookiePath init() parameter を使用して設定することができます。
Domainundefined別の値を使用したい場合は、SDK の初期化時に cookieDomain init() parameter を使用して設定することができます。

Contents Structure​

UID2 Cookie の内容は、POST /token/generate または POST /token/refresh レスポンスの body プロパティと同じ構造を持つ JSON オブジェクトを、private オブジェクトを除いてURI エンコードした文字列表現です。

以下は UID2 cookie 構造の例です:

{
  "advertising_token": "A4AAAABlxUNurwXyIrJ1fc4VIWke6xLqFt7tXdWIJlMIuXHdPOZ4wswrBqiJWeUmduy1pA2c8xePmosknC_6hmr5YFoZ6zKF4K-YwVRib_6uyXZTWLDwS5uz1t-HXi3U84fAqAsGifw4ei7cBvvHLcZksv3Cmm2ejXMrArdwNr7sXPg80mP00xRXK46NmjdY83l5azMa6F-CyFR8cbABOHJCug",
  "refresh_token": "AAAAAGZAGDZ+JF/HriTQOEclFWWx27NlLn7x7Xd/079QtQbPYcSHO2ie0SkyGNGvNdglmw1r0A2NIjd2/4mPYlxMAwGYw3s97LWQwZdJtI+M31k0kg0zB/Ob45w+0HK/zWQVJAxx4gp1LmKO6xhIWyLUoXGMcLWFZDcpSB1rKLvTIx1eo7QAtTQieJPoxJTmP4kTX3jX2ClQuwM5sF6TsHoGaBMuYC8OQdOpRlDquEAU3eUikIPPiIYu/dBu2bdqObnxsxBqk00Kanot2oocY9vHcMo0jMEfjb3h6KVqFdkDQMpKDVhlpbw/ROKszsgQ42PXdeCNPa6iMtMdwxcawaLjHbqBbiovZHgdm5GnnQDM1P/mv1L1AqELrC78x8GnADSn",
  "identity_expires": 1724907586353,
  "refresh_expires": 1724990386353,
  "refresh_from": 1724904886353,
  "refresh_response_key": "imm/IBMVaoRFVQiCudjwyvGuqEnBC+brxWkCiJQpWgE=",
  "private": {
  }
}
警告

private オブジェクトの内容は明示的に指定されておらず、SDK が解釈するようになっています。このオブジェクトの構造、セマンティクス、互換性について、いかなる仮定もしないでください。クッキーの更新はその構造を保持しなければなりません。

Migration Guide​

このセクションには、以前のバージョンの SDK for JavaScript から現在のバージョンである v3 にアップグレードするために必要な情報がすべて含まれています:

Benefits of Migrating​

Version 4 に移行することで、以下の Version 3 および 4 で導入された利点を得ることができます:

important

SDK Version 3 は、以前のバージョンと完全に互換性がありますが、Version 4 で削除された非推奨の要素が含まれています。Version 4 に移行するには、スクリプトタグを新しい URL に変更する必要があります。さらに、Changes in Version 4 にリストされている項目のいずれかを参照している場合、更新されていない場合は、Version 4 にアップグレードする際にこれらの更新を行う必要があります。たとえば、Version 4 で削除された abort() 関数を使用しないようにコードを更新してください。

Benefits in Version 3​

Version 3 では:

  • スクリプトは UID2 CDN を使用して配布されているため、以前のバージョンよりも高速に読み込まれるはずです。

  • SDK は、ID を保存するためにクッキーではなくローカルストレージを使用しようとします。ローカルストレージに保存されているトークンよりも新しいトークンをクッキーが保存されている場合、SDK はクッキーから ID をロードします。

    このアプローチに関する注意事項:

    • 多くのパブリッシャーが、クッキーの最大サイズ制限に近いため、ローカルストレージのデフォルトが要求されました。
    • 新しい ID を提供するために first-party cookie の設定を依存している場合、この変更による利点はありません。
    • init に ID を渡すだけで ID を提供する場合、SDK はもはやクッキーに書き込みません。

Version 2 以前の機能の一部は Version 3 で非推奨とされ、Version 3 にアップグレードする際にいくつかのコードの更新を行うことを推奨しました。この機能は Version 4 で削除されました。Changes in Version 4 にリストされている項目のいずれかを参照している場合、更新されていない場合は、Version 4 にアップグレードする際にこれらの更新を行う必要があります。

Version 3 では、レガシーコールバックシステムが非推奨とされ、将来のバージョンで削除される予定です。

インテグレーションを更新することで、Version 3 および 4 で追加されたこれらの機能を活用できます:

  • async または defer を使用したスクリプトの読み込みが完全にサポートされています。

  • コールバックシステムが簡素化され、管理するステートが少なくなりました。

  • 複数のコールバックを指定でき、init が呼び出される前でも後でも登録できます。

  • TypeScript の完全なサポート。

  • init() が呼び出された後に ID を提供するための関数。

    これにより、SDK はシングルページアプリケーションのシナリオでの使用がはるかに簡単になります。

Benefits in Version 4​

Version 4 は、以前のバージョンよりも堅牢です。利点の概要は、Changes in Version 4 を参照してください。

Required Changes​

Version 4 に移行するためには、現在の実装がどのように構成されているかによって手順が異なります:

  • Migration from version 3, with no elements from earlier versions: 必要な作業は、スクリプトタグを更新して、バージョン 4.0.1 CDN URL から SDK をロードすることだけです。Include the SDK Script を参照してください。

  • Migration from version 3, and you previously migrated from version 2 without completing the steps to update your implementation: スクリプトタグを更新し、また、Version 4 で削除された要素を参照しないようにコードを更新してください。詳細は、Changes in Version 4 を参照してください。

  • Migration from version 2 or earlier: スクリプトタグを更新し、また、Version 4 で削除された要素を参照しないようにコードを更新してください。詳細は、Changes in Version 4 を参照してください。

Additional Changes: Migration from v2 or Earlier​

v3 より前のバージョンから移行する場合、または以前のバージョンから Version 3 に移行したが、コードを更新していない場合は、UID2 JavaScript SDK の実装を改善するための以下の推奨およびオプションの変更を検討してください:

SDK の version 3 の利点を得るために、以下の変更を実施することを強く推奨します:

Migrate to the Newer Callback System Introduced in Version 3​

以前のバージョンでは、コールバックは advertisingToken、status、statusText プロパティを持つ単一のオブジェクトをパラメータとして受け取っていました。Version 3 では、この関数を新しい Callback Function Signature を使用するように変更してください。

元のコールバックには、おそらく status の異なる値を処理するためのロジックがあると思われます。以前のシステムでは、EXPIRED、REFRESHED、NO_IDENTITY などのさまざまなステータス値を扱うことができました。その代わり、新しいシステムには 3 つのイベントタイプしかありません: SdkLoaded、InitCompleted、IdentityUpdated です。

Callback Function のセクションを確認し、新しいシステムを使用してあなたの要求を実装するための最良の方法を検討する必要があります。しかし、参考になる一般的なガイドラインがいくつかあります:

  • event パラメータをチェックしてください。値が SdkLoaded の場合は、すぐにリターンします。
  • そうでなければ、payload パラメータに identity プロパティがあるかどうかを確認します。
    • identity プロパティにオブジェクトがない場合、UID2 ID は利用できません。同じような状況では、前のコールバックが行った処理を呼び出す必要があります。
    • そうでない場合、identity プロパティは advertising_token という名前の string プロパティを持つオブジェクトとなります。これは、以前のコールバックと同じように使用する必要があります。

古いコールバックを init 呼び出しから削除し、更新したコールバック関数を Array Push Pattern を使用して SDK に提供します:

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push(callbackFunction);
Take advantage of setIdentity and other features introduced in version 3​

以前のバージョンの SDK では新しい ID を提供する方法は一つしかありませんでした: init の呼び出しです。このため、パブリッシャーによっては、ページのライフサイクルの後半で新しい ID を提供するために、さまざまな回避策を利用しなければなりませんでした。これらの回避策を取り除き、init が呼ばれた後に SDK に新しい ID を渡したい場合は setIdentity を呼び出すだけで、インテグレーションを簡素化できるかもしれません。

Change how you call init​

init を呼び出すには、Array Push Pattern を使用することを推奨します。既存の init 呼び出しは、次の例に示すように、SdkLoaded イベントのみを処理するコールバックハンドラ内に移動する必要があります:

window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType) => {
  // Each callback function you register with the SDK is invoked once with the `SdkLoaded` event type after the SDK has been loaded by the browser and is ready to use.
  if (eventType === 'SdkLoaded' {    
    __uid2.init({
      /* Provide the same options as in your previous code. If you're no longer using the legacy callback, remove it from here. */
    });
  })
});

Optional Changes​

v3 以前のバージョンからアップグレードする場合は、次のオプションの変更を検討してください。

Add async or defer to your script tag​

async または defer スクリプトローディングを使用する場合は、SDK をロードするスクリプトタグをドキュメントヘッダに移動し、適切なキーワードを追加してください。

async または defer スクリプトローディングを使用するかどうかは、個々のウェブサイトに依存するため、UID2 チームがアドバイスを提供できるものではありません。よくわからない場合は、この変更を無視して script タグを変更しないままにしておくのが安全です。