Publisher web integration overview
As a publisher, there are many ways that you can integrate with UID2 to generate identity tokens to be passed into the RTB bidstream in the context of your web pages.
On this page, you'll find a high-level overview of integration steps and integration options, with links to additional information for each option.
Key integration steps
At a high level, to integrate with UID2, you'll implement these three key activities:
There are many ways you can accomplish these key steps. The simplest and fastest implementation is a full client-side implementation using Prebid.js 8.21.0 or later.
Integration options summary
The following table summarizes the solutions available for each integration step.
To accomplish all steps, you can combine solutions. For example, you could use the SDK for JavaScript, client-side, to generate and refresh the token, and Google Ad Manager Secure Signals to pass the token to the bidstream.
| Integration Solution | Generate Token | Refresh Token | Pass Token to the Bidstream |
|---|---|---|---|
| Prebid.js client-side (8.21.0 or later) | ✅ | ✅ | ✅ |
| Prebid.js client-server (7.53.0 or later) | — | ✅ | ✅ |
| SDK for JavaScript, client-side | ✅ | ✅ | — |
| SDK for JavaScript, client-server | ✅ | ✅ | — |
| SDK for Java | ✅ | ✅ | — |
| SDK for Python | ✅ | ✅ | — |
| Direct integration (API endpoints) | ✅ | ✅ | — |
| Google Ad Manager Secure Signals | — | — | ✅ |
Preparing DII for processing
It's critical that the input data, which you are converting to UID2, is in an acceptable format. If it isn't, you won't get the expected results. For example, you must normalize phone numbers to include the country code, as explained in Phone number normalization.
For details, see Preparing emails and phone numbers for processing.
To validate the full token generation pipeline end to end, confirming that tokens generated from your normalized, hashed, and encoded values are correct, use the UID2 Token Validator.
Publisher web options workflow
To choose your implementation and get started, follow these steps:
- Review the summary of options to generate a UID2 token:
- Review the options to refresh the UID2 token.
- Review the options to pass the token into the bidstream.
- Choose the option that's best for you, and then click through to the implementation documentation.
Generate the UID2 token
There are two main paths that you can choose to generate a UID2 token—you can choose to initiate the UID2 token generate request:
- On the client side (in the user's browser): see Client-side integration options.
- On the server side: see Server-side integration options.
Each option has different advantages. We recommend client-side integration using Prebid.js 8.21.0 or later as the easiest and fastest integration option.
For all integration options, you can choose to store the UID2 token in local storage or cookie storage.
Client-side integration options
Generating the UID2 token on the client side has the following advantages:
- The code runs on the client side, on the consumer's web page, and no server-side coding is required.
- There is a Prebid.js integration that handles all functions for you—token generation, token refresh, and passing the token into the bidstream. If you use Prebid.js 8.21.0 or later, this is the simplest and fastest implementation option.
If you choose a client-side integration, you'll need to provide a list of your root-level domains, for security purposes, as part of account setup. For details, see Client-side web integrations.
The following table summarizes the options for publishers who want to generate the UID2 token on the client side, via the web page, with corresponding documentation resources.
| Option | Documentation |
|---|---|
| Prebid.js client-side implementation (8.21.0 or later) | Client-side integration guide for Prebid.js |
| SDK for JavaScript, client-side implementation | Client-side integration guide for JavaScript |
Server-side integration options
Generating the UID2 token on the server side has the following advantages:
- You can keep your directly identifying information (DII) entirely on the server side.
- If your development resources are back-end developers, you might prefer a server-side integration.
- For server-side Prebid.js integration, there is no requirement to update to the latest Prebid.js version, as long as your version is 7.53.0 or later.
The following table summarizes the options for publishers who want to generate the UID2 token on the server side.
| Option | Documentation |
|---|---|
| SDK for JavaScript, client-server implementation | Client-server integration guide for JavaScript |
| SDK for Java | - Publisher integration guide, server-side - SDK for Java |
| SDK for Python | - Publisher integration guide, server-side - SDK for Python |
| Direct integration (API endpoints) | Publisher integration guide, server-side |
Refresh the UID2 token
For security reasons, the UID2 token has a limited life, but there is a built-in mechanism to refresh the token so that you can still use it.
When you get the token, it comes with a refresh token and a timestamp indicating how long the token is valid for. As long as you use the refresh token to generate a new UID2 token before the current UID2 token expires, you'll get a new UID2 token and an updated refresh token each time. You can continue to refresh to keep the information valid.
The following table shows the integration options that support refreshing the UID2 token.
| Option | Documentation |
|---|---|
| Prebid.js client-side implementation (8.21.0 or later) | Client-side integration guide for Prebid.js |
| Prebid.js client-server implementation (7.53.0 or later) | Client-server integration guide for Prebid.js |
| SDK for JavaScript, client-side implementation | Client-side integration guide for JavaScript |
| SDK for JavaScript, client-server implementation | Client-server integration guide for JavaScript |
| SDK for Java | - Publisher integration guide, server-side - SDK for Java |
| SDK for Python | - Publisher integration guide, server-side - SDK for Python |
| Direct integration (API endpoints) | Publisher integration guide, server-side |
Pass the UID2 token into the bidstream
Publishers use UID2s by encrypting DII (email addresses or phone numbers) into UID2 tokens and then sending the UID2 tokens into the bidstream.
The following table shows integration options that support passing UID2 token into the bidstream.
| Option | Documentation |
|---|---|
| Prebid.js client-side implementation (8.21.0 or later) | Client-side integration guide for Prebid.js |
| Prebid.js client-server implementation (7.53.0 or later) | Client-server integration guide for Prebid.js |
| Google Ad Manager Secure Signals | Google Ad Manager Secure Signals integration guide |
As long as you generate the token and keep it refreshed, you can also use other options for passing the UID2 token into the bidstream.