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

Client-Side Integration Guide for JavaScript

このガイドは、UID2 とインテグレーションして、ウェブサイト上で JavaScript クライアントサイドの変更のみを使用して、最小限の努力で UID2 Token (Advertising Token) を生成するすべての参加者向けです。

この方法は、次の参加者タイプで使用されます:

  • Publishers: このワークフローは、UID2 Token をビッドストリームに送信したいパブリッシャー向けです。
  • Advertisers および Data Providers: さらに、広告主やデータプロバイダは、UID2 Token をトラッキングピクセルに追加するために使用します (詳細は Tokenized Sharing in Pixels を参照)。

このガイドは、Private Operator を使いたいパブリッシャーや、Server-Side でトークンを生成したいパブリッシャーには適用されません。これらのパブリッシャーは、Client-Server Integration Guide for JavaScript に従う必要があります。

UID2 は、SDK for JavaScript を提供しています (詳細は SDK for JavaScript Reference Guide を参照)。この SDK には以下の機能があります:

  • UID2 Token の生成
  • UID2 Token の自動リフレッシュ
  • ブラウザへの UID2 Token の自動保存

実装するには、以下の手順を完了する必要があります:

  1. Complete UID2 account setup and configure account
  2. Add SDK for JavaScript to your site
  3. Configure the SDK for JavaScript
  4. Check that the token was successfully generated

SDK for JavaScript Version​

Client-Side でのトークン生成のサポートは、SDK のバージョン 3.4.5 以上で利用可能です。

SDKのURLは以下のとおり:

以下のコードサンプルでは、プレースホルダ {{ UID2_JS_SDK_URL }} は、この URL を指します。

SDK のデバッグビルドを使用したい場合は、代わりに以下の URL を使用してください:

Sample Implementation​

実装例は、次の例を参照してください:

Integrating with Single Sign-On (SSO)​

シングルサインオン(SSO)プロバイダーとのインテグレーションに関する情報は、Publisher Integration with SSO Providers を参照してください。

Complete UID2 Account Setup and Configure Account​

UID2 とインテグレーションするには、UID2 アカウントが必要です。アカウントをまだ作成していない場合は、まず Account Setup ページの手順に従ってください。

アカウントの初期設定が完了すると、UID2 Portal にアクセスするための手順とリンクが送信されます。ここで、本番環境用の credentials を作成し、提供する必要がある追加の値を設定できます。詳細は、Getting Started with the UID2 Portal を参照してください。

Client-Side インテグレーションでは、UID2 Portal の Client-Side Integration ページで以下の値を設定する必要があります:

ヒント

アカウント設定に必要なのは、ルートレベルのドメインだけです。たとえば、JavaScript 用の UID2 SDK を example.com、shop.example.com、example.org で使用する場合、ドメイン名 example.com と example.org を指定するだけです。

Add SDK for JavaScript to Your Site​

以下のコードスニペットは、ウェブサイトに追加する必要があるコードの概要です。また、SDK がトリガーできるさまざまなイベントも示しています。

より詳細なコードスニペットは、Example Integration Code and When to Pass DII to the UID2 SDK を参照してください。

UID2_JS_SDK_URL の値は、SDK for JavaScript Version を参照してください。

<script async src="{{ UID2_JS_SDK_URL }}"></script>
 
<script>
 
// When the UID2 SDK is executed, it looks for these callbacks and invokes them.
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push((eventType, payload) => {
  switch (eventType) {
    case "SdkLoaded":
      // The SdkLoaded event occurs just once.
      __uid2.init({});
      break;
 
    case "InitCompleted":
      // The InitCompleted event occurs just once.
      //
      // If there is a valid UID2 token, it is in payload.identity.
      break;
 
    case "IdentityUpdated":
      // The IdentityUpdated event happens when a UID2 token is generated or refreshed.
      // payload.identity contains the resulting latest identity.
      break;
  }
});
 
</script>

SDK の詳細は SDK for JavaScript Reference Guide を参照してください。

Using the UID2 Integration Environment​

デフォルトでは、この SDK は UID2 本番環境 https://prod.uidapi.com で動作するように設定されています。代わりに UID2 インテグレーション環境を使用する場合 (資格情報は Getting Your Credentials を参照)、init に以下の URL を指定します:

__uid2.init({
  baseUrl: "https://operator-integ.uidapi.com",
});
注記

UID2 インテグレーション環境からのトークンは、ビッドストリームに渡しても無効です。インテグレーション環境では、Subscription ID と public key の値が異なります。各環境の認証情報を取得すr方法は、Getting Your Credentials を参照してください。

Optional: Specifying the API Base URL to Reduce Latency​

デフォルトでは、この SDK は米国の UID2 本番環境サーバーにリクエストを送信します。

ユースケースに最適な URL を選択する方法と、有効なベース URL の全リストは、Environments を参照してください。

デフォルト以外の UID2 サーバーを指定するには、init 呼び出しで変更します:

__uid2.init({
  baseUrl: "https://global.prod.uidapi.com",
});

Configure the SDK for JavaScript​

UID2 は、Client-Side のトークン生成機能を使用するために必要な以下の値をパブリッシャーに提供します:

  • Subscription ID(サブスクリプション ID)
  • Public key(公開鍵)

パブリッシャーのインテグレーション環境用に 1 セット、本番環境用に別のセットを用意します。

SDK を設定するには、アカウントセットアップ時に受け取った public key と Subscription ID、およびユーザーのハッシュ化またはハッシュ化していない DII(メールアドレスまたは電話番号) を含むオブジェクトを指定して、以下のメソッドのいずれかを呼び出します:

  • __uid2.setIdentityFromEmail
  • __uid2.setIdentityFromEmailHash
  • __uid2.setIdentityFromPhone
  • __uid2.setIdentityFromPhoneHash

以下のセクションでは、各シナリオのコーディング例を示します。

設定が終わると、UID2 SDK は以下を行います:

  • ユーザーの UID2 Token を生成します。
  • トークンをユーザーのブラウザに保存します。
  • ユーザーのブラウザでサイトを開いている間、必要に応じてトークンを自動的にリフレッシュします。

UID2 SDK には、ユーザーの DII をハッシュ化して渡すことも、ハッシュ化せずに渡すこともできます。ハッシュ化せずに DII を渡すと、UID2 SDK が代わりにハッシュ化します。すでにハッシュ化された DII を SDK に渡したい場合は、ハッシュ化する前に正規化する必要があります。詳細は Normalization and Encoding を参照してください。

Format Examples for DII​

SDK は、UID2 Service に送信する前に、ハッシュ化された DII を暗号化します。

SDK は、特定のユーザーに対して、4 つの DII フォーマットのいずれかを送信するように設定できます。DII 形式はユーザーごとに異なる場合がありますが、送信できる値はユーザーごとに 1 つだけです。

以下のセクションでは、UID2 SDK を構成するさまざまな方法を示し、SDK に渡される DII の要件を示します:

  • メールアドレス, ハッシュされていない
  • メールアドレス, 正規化とハッシュ化
  • 電話番号, ハッシュされていない
  • 電話番号, 正規化とハッシュ化

SDK が複数回設定された場合、最新の設定値が使用されます。

JavaScript でメールアドレスと電話のハッシュを生成する方法の例は、Example Code: Hashing and Base-64 Encoding を参照してください。

以下の例では、メールアドレスで UID2 SDK を設定しています。

await __uid2.setIdentityFromEmail(
    "test@example.com",
    {
        subscriptionId: subscriptionId,
        serverPublicKey: publicKey,
    }
);

このシナリオでは:

  • パブリッシャーによる正規化やハッシュ化は必要ありません。
  • UID2 SDK は、暗号化されたハッシュを UID2 Service に送信する前に、メールアドレスを正規化し、ハッシュ化します。

Token Storage and Refresh​

Configure the SDK for JavaScript に記載されているメソッドのいずれかを正常に呼び出すと、identity が生成され、UID2-sdk-identity というキーでローカルストレージに保存されます。SDK は UID2 Token を定期的にリフレッシュします。

警告

ローカルストレージに保存されているオブジェクトのフォーマットは予告なく変更される可能性があります。ローカルストレージのオブジェクトを直接読み込んだり更新したりしないことでください。

Example Integration Code and When to Pass DII to the UID2 SDK​

パブリッシャーで、identity がない状態で最初のページをロードする場合、トークン生成の呼び出しを開始するには、DII で setIdentity メソッドのいずれかを呼び出す必要があります。ID が生成されると、SDK からの IdentityUpdated イベントを待つことで、ビッドストリームに送信する Advertiser Token (UID2 token) を利用できるようになります。例として、advertising_token_to_use の値がどのように設定されるかを以下のコードスニペットで示します。

場合によっては、ユーザーの DII はページロード時に利用できず、DII の取得には何らかの関連コストがかかります。たとえば、DII を取得するために API コールが必要な場合や、DII 情報を提供するためにユーザーにプロンプトが表示される場合があります。

既存のトークンをチェックし、使用またはリフレッシュすることで、このコストを回避できる可能性があります。これを行うには __uid2.isLoginRequired を呼び出し、ブール値を受け取ります。これが true の場合、UID2 SDK は既存のリソースで新しい Advertising Token を作成できず、DII はまったく新しい UID2 Token を生成する必要があることを意味します。

DII を提供すると、__uid2.isLoginRequired が false の値を返す可能性があります。これは、ユーザーが UID2 からオプトアウトしている場合に発生します。UID2 SDK for JavaScript は、ユーザーのオプトアウトを受け入れ、UID2 Token を生成しないため、同じ DII を使用していても、setIdentity メソッドのいずれかを呼び出しても UID2 Token を生成しません。オプションとして、このような呼び出し実行しないようにすることもできます。

以下のコードスニペットは、UID2 SDK for JavaScript とインテグレーションして、上記の 2 つのシナリオを実現する方法を示しています。—トークンがない状態から開始し、既存の UID2 Token が見つかった場合はそれを再利用/リフレッシュします。

<script async src="{{ UID2_JS_SDK_URL }}"></script>
 
<script>
 
// UID2 provides these configuration values to the publisher.
const clientSideConfig = {
  subscriptionId: "...",
  serverPublicKey: "...",
};
  
// Example of a base-64 encoded SHA-256 hash of an email address.
const emailHash = "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=";

// When the UID2 SDK is executed, it looks for these callbacks and invokes them.
window.__uid2 = window.__uid2 || {};
window.__uid2.callbacks = window.__uid2.callbacks || [];
window.__uid2.callbacks.push(async (eventType, payload) => {
  switch (eventType) {
    case "SdkLoaded":
      // The SdkLoaded event occurs just once.
      __uid2.init({});
      break;
 
    case "InitCompleted":
      // The InitCompleted event occurs just once.
      //
      // If there is a valid UID2 token, it is in payload.identity.
      if (payload?.identity) {
        //
        // payload looks like this:
        // {
        //   "identity": {
        //     "advertising_token": "A4A...MqA",
        //     "refresh_token": "A3A...pdg==",
        //     "identity_expires": 1692257038260,
        //     "refresh_expires": 1692339838260,
        //     "refresh_from": 1692254338260
        //     "refresh_response_key": "z0v...zL0="
        //   }
        // }
        var advertising_token_to_use = payload.identity.advertising_token;
      } else {
         if (__uid2.isLoginRequired()) {
            // Call one of the setIdentityFrom functions to generate a new UID2 token.
            // Add any retry logic around this call as required.
            await __uid2.setIdentityFromEmailHash(
                emailHash,
                clientSideConfig);
          }  
          else {
            // there is a token generation API call in flight which triggers a IdentityUpdated event 
            // or no token would be generated because one of previous `setIdentity` calls determines the DII has opted out.
          }
      }
      break;
 
    case "IdentityUpdated":
      // The IdentityUpdated event happens when a UID2 token is generated or refreshed.
      // See previous comment for an example of how the payload looks.
      // It's possible that payload/identity objects could be null for reasons such as the token
      // expired and cannot be refreshed, or the user opted out of UID2. 
      // Check that the advertising token exists before using it.
      if (payload?.identity?.advertising_token) {
          var advertising_token_to_use = payload.identity.advertising_token;
      }
      break;
  }
});
 
</script>

Check that the Token Was Successfully Generated​

トークンが正常に生成されたことを確認するには、ブラウザの開発者ツールを使ってローカルストレージからトークンを探します。

Publisher Workflow

トークンの生成に問題があった場合は、Network タブでリクエストを見つけてください。client-generate という文字列でフィルタリングすることで、リクエストを見つけることができます。リクエストに失敗した理由についての情報は、レスポンスの中にあるはずです。

Publisher Workflow

Example Code: Hashing and Base-64 Encoding​

次のコードサンプルは、JavaScript でメールアドレスと電話のハッシュを生成する方法を示しています。

async function hash(value) {
  const hash = await window.crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(value)
  );
  return bytesToBase64(new Uint8Array(hash));
}
 
function bytesToBase64(bytes) {
  const binString = Array.from(bytes, (x) => String.fromCodePoint(x)).join("");
  return btoa(binString);
}