Skip to content

sdk-ref-csharp-dotnet.md

Latest commit

 

History

History
213 lines (150 loc) · 11 KB

sdk-ref-csharp-dotnet.md

File metadata and controls

213 lines (150 loc) · 11 KB
title SDK for C# / .NET
description C# / .NET SDK のリファレンス情報。
hide_table_of_contents false
sidebar_position 08
displayed_sidebar docs

import Link from '@docusaurus/Link';

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 リポジトリにあります:

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

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 を復号してraw UID2 に変換したりすることができます。

:::note 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);
  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.