UID2 Java SDK

The UID 2 Project is subject to Tech Lab IPR’s Policy and is managed by the IAB Tech Lab Addressability Working Group and Privacy & Rearc Commit Group. Please review the governance rules here.

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

• Java 1.8 or later

Add this dependency to your project's POM:

        <dependency>
            <groupId>com.uid2</groupId>
            <artifactId>uid2-client</artifactId>
            <version>4.0.0</version>
        </dependency>

See com.uid2.client.test.IntegrationExamples for example usage for DSPs.

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

1. Basic usage is for those publishers that are happy to use this SDK's HTTP implementation (synchronous OkHttp).
2. Advanced usage is for those publishers that prefer to use their own HTTP library.

An example application which demonstrates both Basic and Advanced usage is at uid2-examples.

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

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

2. When a user authenticates and authorizes the creation of a UID2:

   IdentityTokens identity = publisherUid2Client.generateToken(TokenGenerateInput.fromEmail(emailAddress));

If you're using standard (client and server) integration:

1. Send this identity as a JSON string back to the client (to use in the identity field) using: identity.getJsonString()

If you're using server-only integration:

1. Store this identity as a JSON string in the user's session, using: identity.getJsonString()

2. To use the user's UID2 token, use 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, then call:

      IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);

   2. Determine if the identity is refreshable (ie, the refresh token hasn't expired):

      if (identity == null || !identity.isRefreshable()) { we must no longer use this identity (eg, 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:

   TokenRefreshResponse tokenRefreshResponse = publisherUid2Client.refreshToken(identity);

5. You should then store tokenRefreshResponse.getIdentityJsonString() in the user's session. If the user has opted out, this method will return null, indicating that the user's identity should be removed from their session. (Optout can be confirmed via tokenRefreshResponse.isOptout().)

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

   private final PublisherUid2Helper publisherUid2Helper = new PublisherUid2Helper(UID2_SECRET_KEY);

2. When a user authenticates and authorizes the creation of a UID2:

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

3. Using an HTTP client library of your choice, post this envelope to the /v2/token/generate 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: envelope.getEnvelope()

4. If the HTTP response status code is not 200, see Response Status Codes to determine next steps. Otherwise:

   IdentityTokens identity = publisherUid2Helper.createIdentityfromTokenGenerateResponse({response body}, envelope);

If you're using standard (client and server) integration:

1. Send this identity as a JSON string back to the client (to use in the identity field) using: identity.getJsonString()

If you're using server-only integration:

1. Store this identity as a JSON string in the user's session, using: identity.getJsonString()

2. To use the user's UID2 token, use 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, then call:

      IdentityTokens identity = IdentityTokens.fromJsonString(identityJsonString);

   2. Determine if the identity is refreshable (ie, the refresh token hasn't expired):

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

   3. Determine if a refresh is needed:

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

4. If a refresh is needed, post to the /v2/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. You should then store tokenRefreshResponse.getIdentityJsonString() in the user's session. If the user has opted out, this method will return null, indicating that the user's identity should be removed from their session. (Optout can be confirmed via tokenRefreshResponse.isOptout().)