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

SDK for C# / .NET Reference Guide

Server-Side では、C# / .NET SDK を使用して、raw UID2 を暗号化して UID2 Token を生成し、UID2 Token を復号して raw UID2 にアクセスすることができます。

Overview​

ここで説明する機能は、ライブラリの設定に必要な情報を定義するか、取得できる情報を定義します。以下で定義されているパラメータとプロパティ名は疑似コードです。実際のパラメータとプロパティ名は言語によって異なりますが、ここで説明されている情報に類似しています。

Functionality​

この SDK は、Server-Sideのコーディングに C# / .NET を使用している DSP または UID2 sharer のために、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
✅✅————

API Permissions​

この SDK を使用するには、Account Setup ページに記載されている手順に従って、UID2 アカウントのセットアップを完了する必要があります。

SDK が提供する特定の機能の使用許可が与えられ、そのアクセス用の認証情報が与えられます。SDK には、使用する権限を持たない機能があるかもしれないことに留意してください。例えば、パブリッシャーはトークンの生成と更新のために特定の API Permissions を取得しますが、SDK は共有などの他のアクティビティをサポートするかもしれません。

詳細は API Permissions を参照してください。

Version​

このライブラリは、.NET Standard 2.1. のユニットテストを使用しています。サンプルアプリは .NET 5.0 を使用しています。

GitHub Repository/Binary​

この SDK は以下のオープンソースの GitHub リポジトリにあります:

バイナリはこちらに公開されています:

Initialization​

DSP は BidstreamClient クラスのインスタンスを作成します。Sharer は SharingClient クラスのインスタンスを作成する必要があります。

SDK が UID2 Service で認証するために必要な値を提供する必要があります。

ParameterDescription
endpointUID2 Service のエンドポイント。Environments を参照してください。
authKeyAPI Key。UID2 Credentials を参照してください
secretKeyクライアントシークレット。UID2 Credentials を参照してください。

Interface​

BidstreamClient クラスを使用すると、UID2 Token を raw UID2 に復号することができます。

ユーザーのオプトアウトを処理する入札ロジックの詳細は DDSP Integration Guide を参照してください。

SharingClient クラスを使うと、raw UID2 を暗号化して UID2 Token に変換したり、UID2 Token を復号して生の UID2 に変換したりすることができます。

注記

SDK を使用する場合、復号鍵を保存したり管理したりする必要はありません。

Encryption Response Content​

SharingClientで暗号化する場合、SDKは以下の情報を返します：

PropertyDescription
Status暗号化結果のステータス。取り得る値のリストと定義については Encryption Response Statuses を参照してください。
EncryptedData暗号化された UID2 Token。

Encryption Response Statuses​

ValueDescription
Successraw UID2 は正常に暗号化され、UID2 Token が返されました。
NotAuthorizedForKey要求者には暗号鍵を使用する権限がありません。
NotAuthorizedForMasterKey要求者はマスターキーを使用する権限がありません。
NotInitializedクライアントライブラリは初期化待ちです。
KeysNotSyncedクライアントが UID2 Service からの鍵の同期に失敗しました。
KeyInactive暗号化キー はアクティブではありません。
EncryptionFailure一般的な暗号化に失敗しました。

Decryption Response Content​

BidstreamClient、SharingClient いずれでも、SDK は以下の情報を返します:

PropertyDescription
Status復号結果のステータス。取り得る値のリストと定義については Decryption Response Statuses を参照してください。
UidUID2 Token に対応する raw UID2。
Establishedユーザーがパブリッシャーと最初に UID2 を確立した時のタイムスタンプ。

Decryption Response Statuses​

ValueDescription
SuccessUID2 Token は正常に復号化され、raw UID2 が返されました。
NotAuthorizedForKey要求者はこの UID2 Token を復号化する権限を持っていません。
NotInitializedクライアントライブラリは初期化待ちです。
InvalidPayload受信した UID2 Token は有効なペイロードではありません。
ExpiredToken受信した UID2 Token の有効期限が切れています。
KeysNotSyncedクライアントが UID2 Service からの鍵の同期に失敗しました。
VersionNotSupportedクライアントライブラリはこのバージョンの暗号化トークンをサポートしていません。

Usage for DSPs​

以下では、SDK for .NET を DSP として使用してビッドストリームトークンをデコードする方法の例を示します。

  1. BidstreamClient を作成します:
var client = new BidstreamClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);
  1. 起動時に一度リフレッシュし、その後定期的にリフレッシュします(推奨リフレッシュ間隔は1時間毎):
client.Refresh();
  1. トークンを raw UID2 に復号化します。トークンを渡し、次のいずれかを行います:
  • ビッドリクエストがパブリッシャーのウェブサイトから発信された場合、ドメイン名を渡します。ドメイン名は、すべて小文字で、スペースなし、サブドメインなしである必要があります。例えば、Subdomain.DOMAIN.com の場合、domain.com を渡します。
  • ビッドリクエストがモバイルアプリから発信された場合、app name を渡します。
  • それ以外の場合は、null を渡します。
var decrypted = client.DecryptTokenIntoRawUid(uidToken, domainOrAppName);
// If decryption succeeded, use the raw UID2.
if (decrypted.Success) 
{
    // Use decrypted.Uid.
} 
else 
{
    // Check decrypted.Status for the failure reason.
}

完全な例については、SampleApp/Program.cs の ExampleBidStreamClient メソッドを参照してください。

Usage for UID2 Sharers​

UID2 Sharing Participant は、送信者または受信者として共有に参加し、他の参加者と UID2 を共有する企業です。

広告主やデータプロバイダは、この SDK を使用して他の認証された UID2 共有参加者と UID2 を共有できます (Tokenized Sharing)。彼らは raw UID2s を UID2 tokens に暗号化し、それを他の参加者に送信して共有できます (詳細は Tokenized Sharing in Pixels を参照してください)。データをピクセルで送信していない場合でも、Security Requirements for UID2 Sharing で示されている要件に従えば、UID2 共有に参加できます。

important

このプロセスで生成される UID2 Token は共有専用です—ビッドストリームでは使用できません。ビッドストリーム用のトークン生成には別のワークフローがあります: Tokenized Sharing in the Bidstream を参照してください。

以下は、SDK for C# / .NET を使用して、送信側または受信側として共有を実装する方法の例です。

  1. SharingClient を作成します:
var client = new SharingClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);
  1. 起動時に一度リフレッシュし、その後定期的にリフレッシュします(推奨リフレッシュ間隔は1時間毎):
client.Refresh();
  1. 送信者の場合、EncryptRawUidIntoToken を呼び出します:
var encrypted = client.EncryptRawUidIntoToken(rawUid);
// If encryption succeeded, send the UID2 token to the receiver.
if (encrypted.Success) 
{ 
    // Send encrypted.EncryptedData to receiver.
} 
else 
{
    // Check encrypted.Status for the failure reason.
}

受信者の場合は、DecryptTokenIntoRawUid を呼び出します。:

var decrypted = client.DecryptTokenIntoRawUid(uidToken);
// If decryption succeeded, use the raw UID2.
if (decrypted.Success) 
{
    // Use decrypted.Uid.
} 
else 
{
    // Check decrypted.Status for the failure reason.
}

For a full example, see the ExampleSharingClient method in SampleApp/Program.cs.

FAQs​

DSP に関するよくある質問については FAQs for DSPs を参照してください。