UID2 SDK for Java Reference Guide

UID2 SDK for Java を使用すると、以下のことが容易になります:

UID2 Advertising Token の生成
UID2 Advertising Token の更新
raw UID2を暗号化して UID2 Token を作成する
UID2 Advertising Token を復号化して raw UID2 にアクセスする

Overview

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

Functionality

このSDKは、Server-Sideのコーディングに Java を使用しているパブリッシャー、DSP、UID2 Sharers のために、UID2 とのインテグレーションを簡素化します。次の表に、この SDK がサポートする機能を示します。

Encrypt Raw UID2 to UID2 Token	Decrypt UID2 Token	Generate UID2 Token from DII	Refresh UID2 Token
Supported	Supported	Supported	Supported

API Permissions

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

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

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

Version

この SDK には Java version 1.8 以降が必要です。

GitHub Repository/Binary

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

UID2 SDK for Java

バイナリは Maven リポジトリで公開されています:

https://central.sonatype.com/artifact/com.uid2/uid2-client

Usage for DSPs

初期化関数は、SDKが UID2 Service で認証するために必要なパラメータを設定します。また、エラー発生時の再試行間隔を設定することもできます。

Parameter	Description	Recommended Value
`endpoint`	UID2 Service のエンドポイント。	N/A
`authKey`	クライアントに付与された認証トークン。UID2 へのアクセスについては、 Contact Info を参照してください。	N/A

Interface

このインターフェイスを使用すると、UID2 Advertising Token を復号化し、対応する raw UID2 を返すことができます。

注記

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

DSP の場合は、入札のために UID2 Advertising Token を復号化して UID2 を返すインターフェースを呼び出します。ユーザーのオプトアウトを処理する入札ロジックの詳細については、DSPインテグレーションガイドを参照してください。

以下は、Java での decrypt メソッド呼び出しです:

import com.uid2.client.IUID2Client

IUID2Client client = UID2ClientFactory.create(TEST_ENDPOINT, TEST_API_KEY, TEST_SECRET_KEY);
client.refresh(); //Note that refresh() should be called once after create(), and then once per hour
DecryptionResponse result = client.decrypt(TEST_TOKEN);

Response Content

SDK から返される利用可能な情報の概要を次の表に示します。

Function	Description
`GetStatus()`	復号結果のステータス。指定可能な値の一覧と定義については、Response Statuses を参照してください。
`GetUid()`	UID2 Advertising Token に対応する raw UID2。
`GetEstablished()`	ユーザーがパブリッシャーと最初に UID2 を確立した時を示すタイムスタンプ。

Response Statuses

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

Usage for Publishers

パブリッシャーとして、UID2 SDK for Java を使用するには 2 つの方法があります:

Basic Usage は、この SDK の HTTP 実装 (synchronous OkHttp) を使いたいパブリッシャー向けです。
Advanced Usage は、独自の HTTP ライブラリを使用したいパブリッシャー向けです。

Basic と Advanced 両方の使い方を示すサンプルアプリケーションについては、Java UID2 Integration Example を参照してください。

Basic Usage

SDK の HTTP 実装を使用している場合は、以下の手順に従ってください。

インスタンス変数として PublisherUid2Client のインスタンスを作成します:

private final PublisherUid2Client publisherUid2Client = new PublisherUid2Client(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);

ユーザーのメールアドレスまたは電話番号を入力として受け取り、TokenGenerateResponse オブジェクトを生成する関数を呼び出します。以下の例では、メールアドレスを使用しています:
```
TokenGenerateResponse tokenGenerateResponse = publisherUid2Client.generateTokenResponse(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut());
```
important
- POST /token/generate エンドポイントは、ユーザーのdirectly identifying information (DII) をターゲティング広告用の UID2 Token に変換する法的根拠を得た場合にのみ呼び出すようにしてください。
- 常に doNotGenerateTokensForOptedOut() を適用します。これは POST /token/generate エンドポイントの呼び出しで optout_check=1 を設定するのと同様のパラメータを適用します(Unencrypted JSON Body Parameters) を参照してください。

Client-Server Integration

Standard Integration (Client and Server) を使用している場合(Server-Side Integration Guide for JavaScript を参照してください)、このステップに従ってください：

この ID を JSON 文字列としてクライアントに送り返します (identity field で使用するため):
```
tokenGenerateResponse.getIdentityJsonString()
```
注記
ユーザーがオプトアウトした場合、このメソッドは null を返しますので、必ず処理してください。

Server-Only Integration

Server-Only Integration (Publisher Integration Guide, Server-Only を参照してください) を使用している場合は、以下の手順に従ってください:

tokenGenerateResponse.getIdentityJsonString() 関数を使用して、この ID をユーザーのセッションに JSON 文字列として格納します。

ユーザーがオプトアウトした場合、このメソッドは null を返します。

ユーザーの UID2 Token を取得するには、以下を使用します:

IdentityTokens identity = tokenGenerateResponse.getIdentity();
if (identity != null) { String advertisingToken = identity.getAdvertisingToken(); }

ユーザーが別のページにアクセスしたときや、タイマーで、更新が必要かどうかを判断します:
1. ユーザーのセッションから ID の JSON 文字列を取得し、ID 情報を入力として受け取って IdentityTokens オブジェクトを生成する以下の関数を呼び出します：
```
IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);
```
2. ID をリフレッシュできるかどうか (Refresh Token の有効期限が切れていないかどうか) を判断します:
```
if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) }
```
3. リフレッシュが必要かどうかを判断します:
```
if (identity.isDueForRefresh()) {..}
```

必要であれば、トークンと関連する値をリフレッシュします:

TokenRefreshResponse tokenRefreshResponse = publisherUid2Client.refreshToken(identity);

ユーザーのセッションに tokenRefreshResponse.getIdentityJsonString() を格納します。

ユーザーがオプトアウトした場合、このメソッドは null を返し、ユーザーの ID をセッションから削除する必要があることを示します。オプトアウトを確認するには、tokenRefreshResponse.isOptout() 関数を使用します。

Advanced Usage

インスタンス変数として PublisherUid2Helper のインスタンスを作成します:

private final PublisherUid2Helper publisherUid2Helper = new PublisherUid2Helper(UID2_SECRET_KEY);

ユーザーのメールアドレスまたは電話番号を入力として受け取り、安全なリクエストデータエンベロープを作成する関数を呼び出します。Encrypting requests を参照してください。以下の例ではメールアドレスを使用しています:
```
EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut());
```
選択した HTTP クライアントライブラリを使用して、ヘッダーとボディを含むこのエンベロープを POST token/generate エンドポイントにポストします:
1. Headers: HTTP ライブラリによっては、以下のようになります:
  
  .putHeader("Authorization", "Bearer " + UID2_API_KEY)
  .putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader())
2. Body: envelope.getEnvelope()
important
- POST /token/generateエンドポイントは、ユーザーのdirectly identifying information (DII) をターゲティング広告用の UID2 Token に変換する法的根拠を得た場合にのみ呼び出すようにしてください。
- 常に doNotGenerateTokensForOptedOut() を適用してください。これは POST /token/generate エンドポイントの呼び出しで optout_check=1 を設定するのと同様のパラメータを適用します (Unencrypted JSON Body Parameters を参照してください)。
HTTP レスポンスステータスコードが 200 でない場合は、Response Status Codes を参照して次のステップを決定します。そうでない場合は、UID2 ID レスポンスの内容を TokenGenerateResponse オブジェクトに変換します:
```
TokenGenerateResponse tokenGenerateResponse = publisherUid2Helper.createTokenGenerateResponse({response body}, envelope);
```

Client-Server Integration

Standard Integration (client and server) を使用している場合 (Server-Side Integration Guide for JavaScript を参照してください)、以下の手順に従ってください:

この ID を JSON 文字列としてクライアントに送り返します (identity field で使用するため):
```
tokenGenerateResponse.getIdentityJsonString()
```
注意
ユーザーがオプトアウトした場合、このメソッドは null を返しますので、必ず処理してください。

Server-Only Integration

Server-Only Integration (Publisher Integration Guide, Server-Only を参照してください) を使用している場合は、以下の手順に従ってください:

tokenGenerateResponse.getIdentityJsonString() を使用して、この ID をユーザーのセッションに JSON 文字列として保存します。

このメソッドは、ユーザーがオプトアウトした場合は null を返すので、必ず処理してください。

ユーザーの UID2 Token を取得するには、以下を使用します:

IdentityTokens identity = tokenGenerateResponse.getIdentity();
if (identity != null) { String advertisingToken = identity.getAdvertisingToken(); }

ユーザーが別のページにアクセスしたときや、タイマーで、更新が必要かどうかを判断します:
1. ユーザーのセッションから ID JSON 文字列を取得し、IDentityTokens オブジェクトを生成する以下の関数を呼び出します:
```
IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);
```
2. ID をリフレッシュできるかどうか (Refresh Token の有効期限が切れていないかどうか) を判断します:
```
if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) }
```
3. リフレッシュが必要かどうかを判断します:
```
if (identity.isDueForRefresh()) {..}
```
リフレッシュが必要な場合は、POST token/refreshエンドポイントを、以下のように呼び出します:
1. Headers: HTTPライブラリによっては、次のようになります:
  
  .putHeader("Authorization", "Bearer " + UID2_API_KEY)
  .putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader()).
2. Body: identity.getRefreshToken()

Refresh HTTP レスポンスステータスコードが 200 の場合:

TokenRefreshResponse tokenRefreshResponse = PublisherUid2Helper.createTokenRefreshResponse({response body}, identity);

ユーザーのセッションに tokenRefreshResponse.getIdentityJsonString() を格納します。

ユーザーがオプトアウトした場合、このメソッドは null を返し、ユーザーの ID をセッションから削除する必要があることを示します。オプトアウトを確認するには、tokenRefreshResponse.isOptout() 関数を使用します。

Usage for Advertisers and Data Providers

IdentityMapClient のインスタンスをインスタンス変数として作成します。

final private IdentityMapClient identityMapClient = new IdentityMapClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);

メールアドレスまたは電話番号を入力として受け取り、IdentityMapResponse オブジェクトを生成する関数を呼び出します。以下の例では、メールアドレスを使用しています:
```
IdentityMapResponse identityMapResponse = identityMapClient.generateIdentityMap(IdentityMapInput.fromEmails(Arrays.asList("email1@example.com", "email2@example.com")));
```

Note: SDK は入力値を送信する前にハッシュ化します。これにより、元のメールアドレスや電話番号がサーバーから送信されることはありません。

マップされた結果とマップされていない結果を以下のように取得します:

Map<String, IdentityMapResponse.MappedIdentity> mappedIdentities = identityMapResponse.getMappedIdentities();
Map<String, IdentityMapResponse.UnmappedIdentity> unmappedIdentities = identityMapResponse.getUnmappedIdentities();`

マップされた結果とマップされていない結果を Iterate するか、lookup を行います。以下の例では lookup を行っています:

IdentityMapResponse.MappedIdentity mappedIdentity = mappedIdentities.get("email1@example.com");
if (mappedIdentity != null) {
     String rawUid = mappedIdentity.getRawUid();
} else {
     IdentityMapResponse.UnmappedIdentity unmappedIdentity = unmappedIdentities.get("email1@example.com");
     String reason = unmappedIdentity.getReason();
}

Usage for UID2 Sharers

UID2 Sharer とは、UID2 を他の参加者と共有したい参加者のことです。raw UID2を他の参加者に送信する前に、UID2 Token に暗号化する必要があります。使用例については、com.uid2.client.test.IntegrationExamples (runSharingExample メソッド) を参照してください。

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

次の手順では、UID2 SDK for Java を送信者または受信者として使用して共有を実装する方法の例を示します。

IUID2Client のリファレンスを作成します:

IUID2Client client = UID2ClientFactory.create(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY);

起動時に一度リフレッシュし、その後定期的にリフレッシュします。推奨されるリフレッシュ間隔は1時間ごとです。詳細については、Decryption Key Refresh Cadence for Sharing を参照してください。
```
client.refresh();
```

送信者:

以下を呼び出します:

EncryptionDataResponse encrypted = client.encrypt(rawUid);

暗号化に成功した場合、UID2 Token を受信者に送信します:

if (encrypted.isSuccess()) 
{ 
   //send encrypted.getEncryptedData() to receiver
} 
else 
{
   //check encrypted.getStatus() for the failure reason
}

受信者:

以下を呼び出します:

DecryptionResponse decrypted = client.decrypt(uidToken);

復号化に成功した場合は、raw UID2を使用します:

if (decrypted.isSuccess()) 
{
   //use decrypted.getUid() 
} 
else 
{
 //check decrypted.getStatus() for the failure reason 
}

FAQs

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

UID2 SDK for Java Reference Guide

Overview​

Functionality​

API Permissions​

Version​

GitHub Repository/Binary​

Usage for DSPs​

Interface​

Response Content​

Response Statuses​

Usage for Publishers​

Basic Usage​

Client-Server Integration​

Server-Only Integration​

Advanced Usage​

Client-Server Integration​

Server-Only Integration​

Usage for Advertisers and Data Providers​

Usage for UID2 Sharers​

FAQs​

Overview

Functionality

API Permissions

Version

GitHub Repository/Binary

Usage for DSPs

Interface

Response Content

Response Statuses

Usage for Publishers

Basic Usage

Client-Server Integration

Server-Only Integration

Advanced Usage

Client-Server Integration

Server-Only Integration

Usage for Advertisers and Data Providers

Usage for UID2 Sharers

FAQs