Skip to main content

EUID Client-Server Integration Guide for Prebid.js

This guide is for publishers who have access to personal data (email address or phone number) on the server side and want to integrate with EUID and generate EUID 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 EUID 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.

EUID Prebid Module Page​

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

Integration Overview: High-Level Steps​

You'll need to complete the following steps:

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

Complete EUID Account Setup​

Complete the EUID account setup by following the steps described in the Account Setup page.

When account setup is complete, you'll receive your unique API key and client secret. These values are unique to you and it's important to keep them secure. For details, see 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 EUID module by checking the box next to the module named European Unified ID, 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 EUID module.

tip

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

Configure the EUID Module​

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

StepActionLink to Instructions
1Send a server-side API call to generate an EUID token.Generating an EUID 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 an EUID Token

Generating an EUID Token on the Server​

For a client-server EUID integration for Prebid, the first step is to generate the EUID 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 an EUID Token​

There are two ways to refresh an EUID 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 EUID Prebid module refreshes the EUID 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.euidCookie 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.euidToken to the response body as a JavaScript object.See Client Refresh Mode euidToken ExampleYou might choose to provide the response body via params.euidToken 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 euid_pub_cookie.

Cookie:

euid_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: 'euid',
      params: {
        euidCookie: 'euid_pub_cookie'
      }
    }]
  }
});

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

Client Refresh Mode euidToken Example​

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

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'euid',
      params: {
        euidToken: {
          '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 __euid_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 __euid_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 EUID module to retrieve the advertising token value from the cookie.

Cookie:

__euid_advertising_token=A4AAAABlh75XmviGJi-hkLGs96duivRhMd3a3pe7yTIwbAHudfB9wFTj2FtJTdMW5TXXd1KAb-Z3ekQ_KImZ5Mi7xP75jRNeD6Mt6opWwXCCpQxYejP0R6WnCGnWawx9rLu59LsHv6YEA_ARNIUUl9koobfA9pLmnxE3dRedDgCKm4xHXYk01Fr8rOts6iJj2AhYISR3XkyBpqzT-vqBjsHH0g

Configuration:

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

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: 'euid'
            value: {
                'euid': {
                    'id': '...advertising token...'
                }
            }
        }]
    }
});

Passing a New Token: Server-Only Mode​

In server-only mode, since the Prebid.js EUID 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.euidApiBase to "https://integ.euid.eu/". You must set this value to the same environment (production or integration) that you use for generating tokens.

  • 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=euidIdSystem --disable UID2_CSTG

Storing the EUID Token in the Browser​

By default, the EUID 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 European Unified ID Configuration in the Prebid documentation.

pbjs.setConfig({ 
  userSync: { 
    userIds: [{ 
      name: 'euid', 
      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().euid, as shown in the following example:

if (!pbjs.getUserIds().euid) {
  // There is no token that can be used or refreshed.
  // Configure the EUID module with a new token
  pbjs.setConfig({
      userSync: {
          userIds: [{
              name: 'euid',
              params: {
                  euidToken: {
                      '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 EUID module has a valid EUID token, call pbjs.getUserIds().euid. If a value is returned, a valid EUID token exists in the EUID 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 EUID 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 EUID 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 EUID module. Always "euid"."euid"
valueCR: N/A
SO: Optional		ObjectAn object containing the value for the advertising token.See Configuration Parameter Examples: Value
params.euidTokenCR: Optional
SO: N/A		ObjectThe initial EUID 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.euidCookieCR: Optional
SO: N/A		StringThe name of a cookie that holds the initial EUID token, set by the server. The cookie should contain JSON in the same format as the euidToken param. If euidToken is supplied, this parameter is ignored.See Sample Token Response Object
params.euidApiBaseCR: Optional
SO: Optional		StringOverrides the default EUID API endpoint. For valid values, see Environments."https://prod.euid.eu" (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 EUID configuration parameter.

pbjs.setConfig({
    userSync: {
        userIds: [{
            name: 'euid'
            value: {
                'euid': {
                    '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: Prebid.js Integration with Google Secure Signals​

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