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

UID2 SDK for C# / .NET Reference Guide

Server-Side で UID2 SDK for C# / .NET を使用すると、以下を簡単に行うことができます:

  • raw UID2 を暗号化して、共有用の UID2 Token を作成する。
  • raw UID2 にアクセスするための UID2 Token の復号化。

Functionality​

この SDK は、Server-Sideのコーディングに C# / .NET を使用している DSP または UID2 sharer のために、UID2 とのインテグレーションを簡素化します。次の表は、この SDK がサポートする機能を示しています。

Encrypt Raw UID2 to UID2 TokenDecrypt UID2 TokenGenerate UID2 Token from DIIRefresh UID2 Token
SupportedSupportedNot supportedNot supported

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 キー。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​

以下では、UID2 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 に複合する。入札元サイトのドメイン名を渡す:
var decrypted = client.DecryptTokenIntoRawUid(uidToken, domain);
// 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 Sharer とは、UID2 を他の参加者と共有したい参加者のことです。raw UID2 を他の参加者に送信する前に、UID2 Tokenに暗号化する必要があります。

警告

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

以下は、UID2 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 を参照してください。