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

DSP direct integration instructions

このドキュメントは、既存の UID2 SDK でサポートされていないプログラミング言語を使用していて、UID2 とインテグレーションを行いたい DSP 向けの手順を提供します。

全ての SDK のリストについては、SDKs: Summary を参照してください。

Overview​

DSP が、ターゲティング広告や入札の目的で復号化されたトークンを使用できるようにするには、UID2 Token を raw UID2 に復号化し、トークンの有効性を検証できる必要があります。これを行うために、DSP は以下を行う必要があります:

UID2 SDK for C# / .NET での実装例は、BidstreamClient クラスです。BidstreamClient.cs を参照してください。

このドキュメントでは、例として C# / .NET SDK の追加のコードセクションを参照します。

Retrieve/refresh encryption keys​

UID2 Token を raw UID2 に復号化できるように、暗号化キーを取得またはリフレッシュするには、以下を行うコードを記述する必要があります:

  • リクエストを暗号化する。
  • エンドポイントを呼び出す。
  • レスポンスを復号化する。
  • レスポンスをパースする。

次の API エンドポイントを呼び出します:

/v2/key/bidstream

起動時に一度キーをリフレッシュし、その後定期的にリフレッシュします (推奨されるリフレッシュ間隔は 1 時間ごとです)。

UID2 SDK for C# / .NET は Refresh 関数を使用します。詳細は、BidstreamClient.cs, line 26 を参照してください。

リクエストの暗号化とレスポンスの復号化を示す実装例については、Encryption and decryption code examples を参照してください。

復号化された API レスポンスは JSON 形式で、site_data (サイトに許可されたドメインまたはアプリ名のリスト) が含まれています。

すべてのフィールドがどのようにパースされるかを確認するには、UID2 SDK for C# / .NET の parse 関数を参照してください: KeyParser.cs, lines 41-74。

トークンを raw UID2 に復号化した後、トークンが Client-Side で生成された場合は、特定のドメインまたはアプリ名が許可された名前のリストにあることを確認するために、site_data の情報を使用する必要があります。詳細は、Verify the domain or app name を参照してください。

Decrypt UID2 tokens into raw UID2s​

現在のキーがあれば、UID2 Token を raw UID2 に復号化できます。また、トークンがビッドストリームで使用可能であることを確認するために、いくつかの条件をチェックする必要があります。

以下の手順を完了する必要があります:

  1. Decrypt the token.

  2. Make sure token lifetime and expiration values are valid.

  3. Verify that the domain or app name is valid.

UID2 SDK for C# / .NET は、これらのステップを実行するために DecryptTokenIntoRawUid 関数を使用します: BidstreamClient.cs, line 15 を参照してください。

Decrypt the token​

マスターキーとサイトキーを使用してトークンを復号化します。コード例については、Decrypt 関数を参照してください: UID2Encryption.cs, line 29。この関数は UID2 SDK for C# / .NET の一部として、UID2 Token を raw UID2 に復号化します。

Make sure token lifetime and expiration are valid​

ビッドストリームで使用するためには、トークンが有効で最新である必要があります。次の 2 つのことを行う必要があります:

  • トークンの有効期限が切れていないことを確認する。
  • トークンの寿命が有効な値であることを確認する。

トークンの有効期限が切れていないことを確認するコードの例については、UID2Encryption.cs, line 196 を参照してください。

トークンの寿命が有効な値であることを確認するには、次の 2 つの条件をチェックします:

  • トークンの寿命が、/v2/key/bidstream レスポンスの max_bidstream_lifetime_seconds 値を超えていないこと。
  • トークン生成までの時間が、allow_clock_skew_seconds 値を超えていないこと。

これがどのように行われるかの例については、DoesTokenHaveValidLifetimeImpl 関数のコードを確認してください: UID2Encryption.cs, line 237 を参照してください。

Calculating token lifetime​

ビッドストリームの使用に対してトークンの寿命が有効であることを確認するための計算式は次のとおりです:

lifetime = token expiry - token generated

time until token generation = token generated - current time

トークンには Token Generated フィールドが含まれており、トークンがリフレッシュされると更新されるため、これを使用してトークンの寿命を計算します。

For tokens generated on the client side: Verify the domain or app name​

Client-Side で生成されたトークンの場合、トークンを復号化した後、ドメイン名またはアプリ名が有効であることを確認する必要があります。これを行うには、/v2/key/bidstream API エンドポイントからのレスポンスの site_data セクション内のサイト ID の domain_names リストに domainOrAppName の値が含まれていることを確認します。

これを行うコードの例については、UID2Encryption.cs, line 245 の IsDomainOrAppNameAllowedForSite 関数を参照してください。

Client-Side UID2 インテグレーションの詳細は、以下のインテグレーションガイドのいずれかを参照してください:

Honor user opt-out after token decryption​

トークンを復号化した後、結果の raw UID2 をオプトアウトレコードと照合する必要があります。オプトアウトレコードにある場合は、入札に UID2 を使用しないなど、ユーザーのオプトアウト設定を尊重する必要があります。

詳細については、DSP integration guide の Honor user opt-outs を参照してください。