UID2 SDK for Java

The UID 2 Project is subject to the IAB Tech Lab Intellectual Property Rights (IPR) Policy, and is managed by the IAB Tech Lab Addressability Working Group and Privacy & Rearc Commit Group. Please review the governance rules.

This document includes:

• Who Is this SDK for?
• Requirements
• Install
• Usage for DSPs
• Usage for Publishers
  • Basic Usage
  • Advanced Usage
• Usage for UID2 Sharers

Who Is this SDK for?

This SDK simplifies integration with UID2 for Publishers, DSPs, and UID Sharers, as described in UID2 Integration Guides.

Requirements

This SDK requires Java version 1.8 or later.

Install

To install the SDK, add the uid2-client dependency to your project's pom.xml file as shown here.

Usage for DSPs

For an example of usage for DSPs, see com.uid2.client.test.IntegrationExamples.

Usage for Publishers

As a publisher, there are two ways to use this SDK:

1. Basic Usage is for publishers who want to use this SDK's HTTP implementation (synchronous OkHttp).
2. Advanced Usage is for publishers who prefer to use their own HTTP library.

For an example application that demonstrates both Basic and Advanced usage, see Java UID2 Integration Example.

Basic Usage

If you're using the SDK's HTTP implementation, follow these steps.

1. Create an instance of PublisherUid2Client as an instance variable.

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

2. Call a function that takes the user's email address or phone number as input and generates a TokenGenerateResponse object. The following example uses an email address:

   TokenGenerateResponse tokenGenerateResponse = publisherUid2Client.generateTokenResponse(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut());

   IMPORTANT: Be sure to call this function only when you have obtained legal basis to convert the user’s directly identifying information (DII) to UID2 tokens for targeted advertising.

   IMPORTANT: Always apply doNotGenerateTokensForOptedOut(). This applies policy=1 in the /token/generate call. Support for policy=0 will be removed soon.

Standard Integration

If you're using standard integration (client and server) (see UID2 SDK for JavaScript Integration Guide), follow this step:

• Send this identity as a JSON string back to the client (to use in the identity field) using the following:

  tokenGenerateResponse.getIdentityJsonString() //Note: this method returns null if the user has opted out, so be sure to handle that case.

Server-Only Integration

If you're using server-only integration (see Publisher Integration Guide, Server-Only):

1. Store this identity as a JSON string in the user's session, using the tokenGenerateResponse.getIdentityJsonString() function. This method returns null if the user has opted out, so be sure to handle that case.

2. To retrieve the user's UID2 token, use:

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

3. When the user accesses another page, or on a timer, determine whether a refresh is needed:

   1. Retrieve the identity JSON string from the user's session, and then call the following function that takes the identity information as input and generates an IdentityTokens object:

      IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);

   2. Determine if the identity can be refreshed (that is, the refresh token hasn't expired):

      if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) }

   3. Determine if a refresh is needed:

      if (identity.isDueForRefresh()) {..}

4. If needed, refresh the token and associated values:

   TokenRefreshResponse tokenRefreshResponse = publisherUid2Client.refreshToken(identity);

5. Store tokenRefreshResponse.getIdentityJsonString() in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from the session. To confirm optout, you can use the tokenRefreshResponse.isOptout() function.

Advanced Usage

1. Create an instance of PublisherUid2Helper as an instance variable:

   private final PublisherUid2Helper publisherUid2Helper = new PublisherUid2Helper(UID2_SECRET_KEY);

2. Call a function that takes the user's email address or phone number as input and creates a secure request data envelope. See Encrypting requests. The following example uses an email address:

   EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail(emailAddress).doNotGenerateTokensForOptedOut());

3. Using an HTTP client library of your choice, post this envelope to the POST token/generate endpoint, including headers and body:

   1. Headers: Depending on your HTTP library, this might look something like the following:

      .putHeader("Authorization", "Bearer " + UID2_API_KEY)
.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader())

   2. Body: envelope.getEnvelope()

   IMPORTANT: Be sure to call this endpoint only when you have obtained legal basis to convert the user’s directly identifying information (DII) to UID2 tokens for targeted advertising.

   IMPORTANT: Always apply doNotGenerateTokensForOptedOut(). This applies policy=1 in the /token/generate call. Support for policy=0 will be removed soon.

4. If the HTTP response status code is not 200, see Response Status Codes to determine next steps. Otherwise, convert the UID2 identity response content into a TokenGenerateResponse object:

   TokenGenerateResponse tokenGenerateResponse = publisherUid2Helper.createTokenGenerateResponse({response body}, envelope);

Standard Integration

If you're using standard integration (client and server) (see UID2 SDK for JavaScript Integration Guide):

• Send this identity as a JSON string back to the client (to use in the identity field) using the following:

  tokenGenerateResponse.getIdentityJsonString() //Note: this method returns null if the user has opted out, so be sure to handle that case.

Server-Only Integration

If you're using server-only integration (see Publisher Integration Guide, Server-Only):

1. Store this identity as a JSON string in the user's session, using: tokenGenerateResponse.getIdentityJsonString(). This method returns null if the user has opted out, so be sure to handle that case.

2. To retrieve the user's UID2 token, use:

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

3. When the user accesses another page, or on a timer, determine whether a refresh is needed:

   1. Retrieve the identity JSON string from the user's session, and then call the following function that generates an IdentityTokens object:

      IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);

   2. Determine if the identity can be refreshed (that is, the refresh token hasn't expired):

      if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (for example, remove this identity from the user's session) }

   3. Determine if a refresh is needed:

      if (identity.isDueForRefresh()) {..}

4. If a refresh is needed, call the POST token/refresh endpoint, with:

   1. Headers (depending on your HTTP library, this might look something like):

      .putHeader("Authorization", "Bearer " + UID2_API_KEY)
.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader()).

   2. Body: identity.getRefreshToken()

5. If the refresh HTTP response status code is 200:

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

6. Store tokenRefreshResponse.getIdentityJsonString() in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from the session. To confirm optout, you can use the tokenRefreshResponse.isOptout() function.

Usage for UID2 Sharers

A UID2 sharer is a participant that wants to share UID2s or EUIDs with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant. For an example of usage, see com.uid2.client.test.IntegrationExamples (runSharingExample method).

1. Use UID2ClientFactory.create() to create an IUID2Client reference:

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

2. Call IUID2Client.refresh once at startup, and then periodically (for example, every hour):

   client.refresh();

3. Senders:

   1. Call the following:

      EncryptionDataResponse encrypted = client.encrypt(rawUid);

   2. If encryption succeeded, send the UID2 token to the receiver:

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

4. Receivers:

   1. Call the following:

      DecryptionResponse decrypted = client.decrypt(uidToken);

   2. If decryption succeeded, use the raw UID2:

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