publisher-client-side.md

UID2 API Documentation > v1 > Integration Guides > Publisher Integration Guide

UID2 SDK Integration Guide

NOTE: This guide is intended for the UID2 SDK version 1. For the Integration Guide using the previous version of the UID2 SDK, see Publisher Integration Guide (Standard).

This guide is intended for publishers with web assets who would like to generate identity tokens utilizing UID2 for the RTB bid stream, while integrating directly with UID2 rather than UID2-enabled single-sign-on or identity providers.

The guide outlines the basic steps that you need to consider for your integration. For example, you need to decide how to implement user login and logout, how to manage UID2 identity information and use it for targeted advertising, how to refresh tokens, deal with missing identities, and handle user opt-outs. See also FAQs.

To facilitate the process of establishing client identity using UID2 and retrieving advertising tokens, the web integration steps provided in this guide rely on the Client-Side Identity JavaScript SDK, also known as the UID2 SDK. Here's an example application that illustrates the integration steps described in this guide and the usage of the SDK. For the application documentation, see UID2 SDK Integration Example.

IMPORTANT: The UID2 SDK currently stores tokens in first-party cookies. Since implementation details like this may change in the future, to avoid potential issues, be sure to rely on the UID2 SDK APIs for your identity management.

For custom integration scenarios for app developers and CTV broadcasters without utilizing the UID2 SDK, see Server-Only Integration Guide.

Integration Steps

The following diagram outlines the steps required for a user to establish a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream.

The following sections provide additional details for each step in the diagram:

1. Establish identity: user login
2. Bid using UID2 tokens
3. Refresh tokens
4. Clear Identity: user logout

Establish Identity: User Login

After authentication in step 1-c, which forces the user to accept the rules of engagement and allows the publisher to validate their email address, a UID2 token must be generated on the server side. The following table details the token generation steps.

Step	Endpoint/SDK	Description
1-d	GET /token/generate	After the user authenticates and authorizes the creation of a UID2, use the GET /token/generate endpoint to generate a UID2 token using the provided normalized email address of the user.
1-e	GET /token/generate	Return a UID2 token generated from the user's email address or hashed email address.
1-f	UID2 SDK	Send the returned UID2 token from step 1-e to the SDK in the identity property of its init() function and specify a callback function as shown below. The mechanism ensures that UID2 tokens are available for the user for targeting advertising until they log out.

<script>
 __uid2.init({
   callback : function (state) {...}, // Check advertising token and its status within the passed state and initiate targeted advertising. 
   identity : {...} // The `body` property value from the token/generate API response.
 });
</script>

For example:

<script>
 __uid2.init({
   callback : onUid2IdentityUpdated,
   identity : {
        "advertising_token": "AgmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
        "refresh_token": "Mr2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==",
        "identity_expires": 1633643601000,
        "refresh_from": 1633643001000,
        "refresh_expires": 1636322000000
    }
 });
</script>

The SDK invokes the specified callback function (which indicates the identity availability) and makes the established identity available client-side for bidding.

Bid Using UID2 Tokens

Based on the status and availability of a valid identity, the SDK sets up the background token auto-refresh, stores identity information in a first-party cookie, and uses it to initiate requests for targeted advertising.

Step	Endpoint/SDK	Description
2-a	UID2 SDK	Get the current user's advertising token by using the getAdvertisingToken() function as shown below.

<script>
  let advertisingToken = __uid2.getAdvertisingToken();
</script>

TIP: You need to consider how you pass the returned advertising token to SSPs.

Refresh Tokens

As part of its initialization, the SDK sets up a token auto-refresh for the identity, which is triggered in the background by the timestamps on the identity or failed refresh attempts due intermittent errors.

Step	Endpoint/SDK	Description
3-a	UID2 SDK	The SDK automatically refreshes UID2 tokens in the background. No manual action is required.
3-b	UID2 SDK	If the user hasn't opted out, the GET /token/refresh automatically returns new identity tokens.

Clear Identity: User Logout

The client lifecycle is complete when the user decides to log out from the publisher's site (not UID2). This closes the client's identity session and clears the first-party cookie information.

Step	Endpoint/SDK	Description
4-a	N/A	The user logs out from the publisher's asset.
4-b	UID2 SDK	Clear the UID2 identity from the first-party cookie and disconnect the client lifecycle by using the disconnect() function as shown below.

<script>
  __uid2.disconnect();
</script>

FAQs

How will I be notified of user opt-out?

The UID2 SDK background token auto-refresh process handles user opt-outs. If user opts out, when the UID2 SDK attempts token refresh, it will learn about the optout and will clear the session (including the cookie) and invoke the callback with the OPTOUT status.

How can I test that the PII sent and returned tokens match?

You can use the GET /token/validate endpoint to check whether the PII you are sending through GET /token/generate is valid.

1. Do either of the following:
   • Send a GET /token/generate request using [email protected] as email.
   • Create a base64-encoded SHA256 hash of [email protected] and send it as an email hash.
2. Store the returned advertising_token for use in the following step.
3. Send a GET /token/validate request using the email or email_hash you sent in step 1 and the advertising_token (saved in step 2) as the token property value.
   • If the response returns true, the email or email_hash you sent as a request in step 1 match the token you received in the response of step 1.
   • If it returns false, there may be an issue with the way you are sending email addresses or email hashes.

How can I test the refresh token logout workflow?

You can use the email address [email protected] to test your token refresh workflow. Using this email for the request always generates an identity response with a refresh_token that results in a logout response.

1. Do either of the following:
   • Send a GET /token/generate request using [email protected] as email.
   • Create a base64-encoded SHA256 hash of [email protected] and send it as an email hash.
2. Wait until the SDK's background auto-refresh attempts to refresh the advertising token (this can take several hours) and observe the refresh attempt fail with the OPTOUT status. At this point the SDK also clears the first-party cookie.