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 Sharing	Decrypt UID2 Token to Raw UID2	Generate UID2 Token from DII	Refresh UID2 Token	Map DII to Raw UID2s	Monitor Rotated Salt Buckets
✅	✅	—	—	—	—

UID2 Account Setup

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

API Permissions

アカウントの初期設定が完了すると、パブリッシャー、広告主、またはデータプロバイダーの場合、UID2 Portal にアクセスするための手順とリンクが送信されます。以下の操作が可能です:

• アカウント用の credentials を生成します。
• オプションとして、チームメンバーに関する情報を設定するなど、他の値を設定します。

SDK が提供する特定の機能を使用する権限が与えられ、そのアクセスのための資格情報が提供されます。SDK には使用権限がない機能がある可能性があることに注意してください。詳細については、API Permissions を参照してください。

DSP の場合は、資格情報を送信します。

Version

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

GitHub Repository/Binary

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

• SDK for .NET

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

• https://www.nuget.org/packages/UID2.Client

Initialization

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

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

Parameter	Description
endpoint	UID2 Service のエンドポイント。Environments を参照してください。
authKey	API 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は以下の情報を返します：

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

Encryption Response Statuses

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

Decryption Response Content

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

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

Decryption Response Statuses

Value	Description
Success	UID2 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);

2. 起動時に一度リフレッシュし、その後定期的にリフレッシュします(推奨リフレッシュ間隔は1時間毎):

client.Refresh();

3. トークンを 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);

2. 起動時に一度リフレッシュし、その後定期的にリフレッシュします(推奨リフレッシュ間隔は1時間毎):

client.Refresh();

3. 送信者の場合、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 を参照してください。