Skip to main content

Prebid.js Advanced Integration Guide

This guide is for publishers who want to integrate with UID2 and generate UID2 tokens (advertising tokens) to be passed by Prebid in the RTB bid stream. It covers advanced use cases for publishers who want to generate and optionally refresh UID2 tokens by making server-side API calls to the UID2 operator.

For integration instructions that do not require server-side changes, see Prebid.js Express Integration Guide.

This guide outlines the basic steps to consider if you're building a direct integration with UID2 and you use Prebid for header bidding.

Introduction​

If you're a publisher using Prebid for header bidding, there are a few extra steps to take so that your Prebid header bidding implementation also supports UID2.

In addition, if you don't already have one, you must set up a UID2 account: see Account Setup.

UID2 Prebid Module Page​

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

Integration Steps​

At a high level, to integrate with UID2 using Prebid, you'll need to complete the following steps.

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

Generate UID2 Token​

You can generate tokens by calling the POST /token/generate endpoint.

UID2 User ID Submodule​

The UID2 module handles storing, providing, and optionally refreshing UID2 tokens.

Important: UID2 is not designed to be used where GDPR applies. The module checks the passed-in consent data, and does not operate if the gdprApplies flag is set to true.

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.

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

Response Storage Options​

When you configure the module to use Client Refresh mode, you must choose one of the following options for storing the API response information.

OptionDetailsUse Case
Set params.uid2Cookie to the name of the cookie that contains the response body as a JSON string.See Client Refresh Cookie Example.Do not choose this option unless you are sure there's enough space left in your cookie to store the response body.
Set params.uid2Token to the response body as a JavaScript object.See Client Refresh uid2Token Example.You might choose to provide the response body via params.uid2Token in either of these cases:
- If storing the response body on the cookie will exceed the cookie size limit.
- If you prefer to have the flexibility to manage the storage of the response body yourself.

In this example, the cookie is called uid2_pub_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'
      }
    }]
  }
});

Client Refresh uid2Token Example​

The following example shows a sample configuration. For the contents of the token, see Sample 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
        }
      }
    }]
  }
});

Storage of Internal Values​

The UID2 Prebid module stores some internal values. By default, all values are stored in HTML5 local storage. If needed, you can switch to cookie storage by setting params.storage to cookie. The cookie size can be significant, so we don't recommend this solution, but it is a possible solution if local storage is not an option.

Sample Token​

The following sample is fictitious, but shows what the token response object looks like:

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

Prebid Implementation Notes and Tips​

In planning your Prebid implementation, consider the following:

  • If you're trying to limit the size of cookies, provide the token in configuration and use the default option of local storage.

  • If you provide an expired identity, and the module has a valid identity which was refreshed from the identity you provide, the module uses the refreshed identity. The module stores the original token that it used for refreshing the token, and uses the refreshed tokens as long as the original token matches the token that you provided.

  • If you provide a new token that does not match the original token used to generate any refreshed tokens, all stored tokens are discarded and the new token used instead (refreshed if necessary).

  • During integration testing, you can set params.uid2ApiBase to "https://operator-integ.uidapi.com". Be aware that you must use the same environment (production or integration) that you use for generating tokens.

  • For an example of what a UID2 token might look like in the bid stream, when it's sent from an SSP to a DSP, see What does a UID2 token look like in the bid stream?

Configuration Parameters for usersync​

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

Param under userSync.userIds[]ScopeTypeDescriptionExample
nameRequiredStringID value for the UID2 module - "uid2""uid2"
valueOptional, server onlyObjectAn object containing the value for the advertising token.See Sample Token.
params.uid2TokenOptional, client refreshObjectThe 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.
params.uid2CookieOptional, client refreshStringThe 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 param is ignored.See Sample Token.
params.uid2ApiBaseOptional, client refreshStringOverrides the default UID2 API endpoint."https://prod.uidapi.com" (the default)
params.storageOptional, client refreshStringSpecify 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)