Skip to main content

UID2 Client-Server Integration Guide for Prebid.js

This guide is for publishers who have access to DII (email address or phone number) on the server side and want to integrate with UID2 and generate UID2 tokens (advertising tokens) to be passed by Prebid.js in the RTB bidstream.

This is called client-server integration because some integration steps are client-side and some are server-side.

To integrate with UID2 using Prebid.js, you'll need to:

  • Make changes to the HTML and JavaScript on your site.
  • Make server-side changes for token generation (and, optionally, token refresh).

Prebid.js Version​

This implementation requires Prebid.js version 7.53.0 or later. For version information, see https://github.com/prebid/Prebid.js/releases.

UID2 Prebid Module Page​

Information about how to integrate Prebid with UID2 is also in the following locations:

Integrating with Single Sign-On (SSO)​

If you integrate with one or more SSO providers to offer SSO login, you might be able to retrieve the logged-in user's email address from the SSO provider to generate UID2 tokens.

For details, see Publisher Integration with SSO Providers.

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.

Integration Overview: High-Level Steps​

You'll need to complete the following steps:

  1. Complete UID2 account setup and configure account.
  2. Add Prebid.js to your site.
  3. Configure the UID2 module.

Complete UID2 Account Setup and Configure Account​

To integrate with UID2 using Prebid.js, you'll need to have a UID2 account. If you haven't yet created an account, first follow the steps described on the Account Setup page.

When initial account setup is complete, you'll receive instructions and a link to access the UID2 Portal, where you can create your credentials for the production environment and configure additional values, if needed. For details, see Getting Started with the UID2 Portal.

For a client-server integration you'll need to set up these values, in the UID2 Portal on the API Keys page:

  • API key, also called a client key
  • Client secret, a value known only to the participant and the UID2 service
important

It's very important that you keep these values secure. For details, see Security of API Key and Client Secret.

Add Prebid.js to Your Site​

To add Prebid.js to your site, follow the instructions in Getting Started for Developers in the Prebid.js documentation.

When you download the Prebid.js package, add the UID2 module by checking the box next to the module named Unified ID 2.0, listed under the section User ID Modules.

When you've added Prebid.js to your site and confirmed that it's working properly, you're ready to configure the UID2 module.

tip

To make sure that the UID2 module is installed, find the string uid2IdSystem in the pbjs.installedModules array.

Configure the UID2 Module​

You'll need to configure the UID2 Prebid module to complete the following two actions:

StepActionLink to Instructions
1Send a server-side API call to generate a UID2 token.Generating a UID2 Token on the Server
2Store the response value, so that the Prebid module can manage token refresh as well as opt-out if needed.Refreshing a UID2 Token

Generating a UID2 Token on the Server​

For a client-server UID2 integration for Prebid, the first step is to generate the UID2 token on your server. Then, you can pass the token to Prebid for sending to the RTB bidstream.

For details, including instructions and examples, see Server-Side Token Generation.

To generate a token, call one of the SDKs or the POST /token/generate endpoint. For an example of the API response, showing the token, see Sample Token Response Object. You will need to pass the Identity response to Prebid.

warning

For security reasons, the API key and secret used in token generation must be called server-side. Do not store these values as part of your Prebid implementation.

Refreshing a UID2 Token​

There are two ways to refresh a UID2 token, as shown in the following table.

ModeDescriptionLink to Section
Client refresh modePrebid.js automatically refreshes the tokens internally.
This is the simplest approach.		Client Refresh Mode
Server-only modePrebid.js doesn't automatically refresh the token. It is up to the publisher to manage token refresh.
Examples of why you might want to choose this option:
  • If you want to use the SDK for JavaScript to refresh the token, and Prebid.js to send the token to the bidstream.
  • If you want to send the token to the bidstream via multiple avenues (such as Prebid.js and also Google).
Server-Only Mode

Client Refresh Mode​

You must provide the Prebid module with the full JSON response body from the applicable endpoint:

For an example, see Sample Token Response Object.

As long as the refresh token remains valid, the UID2 Prebid module refreshes the UID2 token as needed.

This section includes the following information:

Client Refresh Mode Response Configuration Options​

When you configure the module to use Client Refresh mode, you must choose one of the following options for providing the token to the Prebid module.

OptionDetailsUse Case
Set params.uid2Cookie to the name of the cookie that contains the response body as a JSON string.See Client Refresh Mode Cookie ExampleUse this option only if you're sure that there is enough space left in your cookie to store the response body. If you're not sure, or the cookie storage needs might vary, choose the other option.
Set params.uid2Token to the response body as a JavaScript object.See Client Refresh Mode uid2Token ExampleYou might choose to provide the response body via params.uid2Token in either of these cases:
  • If you are already storing a lot of data in the cookie and adding the response body might exceed the cookie size limit.
  • If you prefer to have the Prebid module store the token value for you.

In Client Refresh mode, Prebid.js takes care of refreshing the token. To do this, you must configure it to store the token. The following example shows the cookie and also the configuration for storing the token in a cookie called uid2_pub_cookie.

Cookie:

uid2_pub_cookie={"advertising_token":"...advertising token...","refresh_token":"...refresh token...","identity_expires":1684741472161,"refresh_from":1684741425653,"refresh_expires":1684784643668,"refresh_response_key":"...response key..."}

Configuration:

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'uid2',
      params: {
        uid2Cookie: 'uid2_pub_cookie'
      }
    }]
  }
});

For an example of the token, see Sample Token Response Object.

Client Refresh Mode uid2Token Example​

The following example shows a sample configuration. For the contents of the token, see Sample Token Response Object.

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'uid2',
      params: {
        uid2Token: {
          'advertising_token': '...advertising token...',
          'refresh_token': '...refresh token...',
          // etc. - see the sample token for contents of this object
        }
      }
    }]
  }
});

Passing a New Token: Client Refresh Mode​

If the refresh token expires, you'll need to supply a new token response so that a new advertising token and a new refresh token are available for future refreshes.

For information on how to determine if you need to provide a new token, see Determining Whether the Module Has a Valid Token.

Server-Only Mode​

In server-only mode, only the advertising token is provided to the module. The module cannot refresh the token. You are responsible for implementing a way to refresh the token.

To configure the module to use server-only mode, do one of the following:

Implementation MethodLink to Example
Set a cookie named __uid2_advertising_token and store the advertising token value in it.Server-Only Mode Cookie Example
Set value to an ID block containing the advertising token.Server-Only Mode Value Example

This section includes the following information:

The following example stores the advertising token value in a cookie named __uid2_advertising_token. The value of the cookie is the value returned in the token response object (see Sample Token Response Object).

The configuration allows the UID2 module to retrieve the advertising token value from the cookie.

Cookie:

__uid2_advertising_token=A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

Configuration:

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'uid2'
        }]
    }
});

Server-Only Mode Value Example​

The following example sets the value field to an ID block containing the advertising token without storing it in a cookie.

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'uid2'
            value: {
                'uid2': {
                    'id': '...advertising token...'
                }
            }
        }]
    }
});

Passing a New Token: Server-Only Mode​

In server-only mode, since the Prebid.js UID2 module receives only the advertising token, the token is only valid for a short period of time. For this reason, it's best to provide an advertising token on each page load.

If needed, to determine if you need to provide a new token, see Determining Whether the Module Has a Valid Token.

Prebid Implementation Notes and Tips​

In planning your Prebid implementation, consider the following:

  • The module stores the original token provided to it, refreshes it as needed, and uses the refreshed token. If you provide an expired identity, and the module has a valid update from refreshing the same identity, the module uses the refreshed identity in place of the expired one you provided.

  • If you provide a new token that doesn't match the original token used to generate any refreshed tokens, the module discards all stored tokens and uses the new token instead, and keeps it refreshed.

  • During integration testing, set params.uid2ApiBase to "https://operator-integ.uidapi.com". You must set this value to the same environment (production or integration) that you use for generating tokens (for credentials, see Getting Your Credentials).

  • For a Prebid.js client-server integration, you can create a smaller Prebid.js build by disabling client-side integration functionality. To do this, pass the --disable UID2_CSTG flag:

    $ gulp build --modules=uid2IdSystem --disable UID2_CSTG

Storing the UID2 Token in the Browser​

By default, the UID2 module stores data using local storage. To use a cookie instead, set params.storage to cookie, as shown in the following example.

For details, see Unified ID 2.0 Configuration in the Prebid documentation.

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'uid2', 
      params: { 
        // default value is 'localStorage' 
        storage: 'cookie'   
      } 
    }] 
  } 
});

The cookie size can be significant, which could be a problem. However, if local storage is not an option, this is one possible approach.

Determining Whether the Module Has a Valid Token​

You can do a check to determine whether the Prebid.js module has a valid token or you need to provide a new one.

To do this, check the value returned by pbjs.getUserIds().uid2, as shown in the following example:

if (!pbjs.getUserIds().uid2) {
  // There is no token that can be used or refreshed.
  // Configure the UID2 module with a new token
  pbjs.setConfig({
      userSync: {
          userIds: [{
              name: 'uid2',
              params: {
                  uid2Token: {
                      'advertising_token': '...advertising token...',
                      'refresh_token': '...refresh token...',
                      // etc. - see the sample token for contents of this object
                  }
              }
          }]
      }
  });  
}
caution

If you configure a user ID by calling setConfig (or any similar function) twice, you will need to call refreshUserIds for the user ID submodules, to reinitialize their ID values.

Checking the Integration​

To check that the UID2 module has a valid UID2 token, call pbjs.getUserIds().uid2. If a value is returned, a valid UID2 token exists in the UID2 module.

If there are problems with the integration, here are some steps you can take:

  • Check the browser console logs.
  • Use the browser developer tools to inspect the API calls to the UID2 service.

For additional help, refer to Prebid's documentation on Troubleshooting Prebid.js and Debugging Prebid.js.

An example of a tool for validating and debugging Prebid.js configuration is Professor Prebid, an open-source Chrome extension:

Configuration Parameters for userSync​

The following parameters apply only to the UID2 Prebid User ID Module integration.

In this table, CR = client refresh mode, SO = server-only mode, and N/A = not applicable.

Param under userSync.userIds[]Mode/ScopeTypeDescriptionExample
nameCR: Required
SO: Required		StringID value for the UID2 module. Always "uid2"."uid2"
valueCR: N/A
SO: Optional		ObjectAn object containing the value for the advertising token.See Configuration Parameter Examples: Value
params.uid2TokenCR: Optional
SO: N/A		ObjectThe initial UID2 token. This should be the body element of the decrypted response from a call to the /token/generate or /token/refresh endpoint.See Sample Token Response Object
params.uid2CookieCR: Optional
SO: N/A		StringThe name of a cookie that holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the uid2Token param. If uid2Token is supplied, this parameter is ignored.See Sample Token Response Object
params.uid2ApiBaseCR: Optional
SO: Optional		StringOverrides the default UID2 API endpoint. For details, and an example, see Optional: Specifying the API Base URL to Reduce Latency."https://prod.uidapi.com" (the default)
params.storageCR: Optional
SO: Optional		StringSpecify the module internal storage method: cookie or localStorage. We recommend that you do not provide this parameter. Instead, allow the module to use the default."localStorage" (the default)

Configuration Parameter Examples: Value​

The following code snippet shows an example of the value UID2 configuration parameter.

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'uid2'
            value: {
                'uid2': {
                    'id': '...advertising token...'
                }
            }
        }]
    }
});

Sample Token Response Object​

The following sample is fictitious, but shows what the token response object, returned from either the POST /token/generate or POST /token/refresh endpoint, looks like:

{
  "advertising_token": "...",
  "refresh_token": "...",
  "identity_expires": 1633643601000,
  "refresh_from": 1633643001000,
  "refresh_expires": 1636322000000,
  "refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
}

Optional: Specifying the API Base URL to Reduce Latency​

By default, the UID2 module makes calls to a UID2 production environment server in the USA.

For information about how to choose the best URL for your use case, and a full list of valid base URLs, see Environments.

To specify a UID2 server that is not the default, when you're configuring the UID2 module, set the optional params.uid2ApiBase parameter, as shown in the following example:

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'uid2', 
      params: { 
        uid2ApiBase: baseUrl, 
        // ... 
      } 
    }] 
  } 
});

Optional: Prebid.js Integration with Google Secure Signals​

if you're using Prebid.js, and you're planning to pass UID2 tokens to Google using Google Secure Signals, there are a couple of additional configuration steps:

Sample Implementation​

The following sample implementation is available to illustrate how to integrate UID2 with Prebid.js using client-server integration: