EUID Client-Server Integration Guide for Prebid.js

This guide is for publishers who have access to personal data 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:

• On the Prebid site, on the European Unified ID page for the Prebid User ID submodule.
• In the Prebid GitHub repository, on the EUID User ID Submodule page.

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:

Step	Action	Link to Instructions
1	Send a server-side API call to generate an EUID token.	Generating an EUID Token on the Server
2	Store 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. 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.

Mode	Description	Link to Section
Client refresh mode	Prebid.js automatically refreshes the tokens internally. This is the simplest approach.	Client Refresh Mode
Server-only mode	Prebid.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 EUID 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:

• POST /token/generate for a new EUID token.
• POST /token/refresh for a refreshed EUID token.

For an example, see Sample Token.

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
• Client Refresh Mode Cookie Example
• Client Refresh Mode euidToken Example
• Passing a New Token: Client Refresh Mode

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.

Option	Details	Use Case
Set params.euidCookie to the name of the cookie that contains the response body as a JSON string.	See Client Refresh Mode Cookie Example	Use 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 Example	You 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.

Client Refresh Mode Cookie Example

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.

Client Refresh Mode euidToken Example

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

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 Method	Link 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:

• Server-Only Mode Cookie Example
• Server-Only Mode Value Example
• Passing a New Token: Server-Only Mode

Server-Only Mode Cookie Example

The following example stores the advertising token value in a cookie named __euid_advertising_token. The configuration allows the EUID module to retrieve the advertising token value from the cookie.

Cookie:

__euid_advertising_token=...advertising token...

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:

• Chrome web store download location: Professor Prebid
• Documentation on prebid.org: Professor Prebid User Guide

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/Scope	Type	Description	Example
name	CR: Required SO: Required	String	ID value for the EUID module. Always "euid".	"euid"
value	CR: N/A SO: Optional	Object	An object containing the value for the advertising token.	See Configuration Parameter Examples: Value
params.euidToken	CR: Optional SO: N/A	Object	The 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
params.euidCookie	CR: Optional SO: N/A	String	The 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
params.euidApiBase	CR: Optional SO: Optional	String	Overrides the default EUID API endpoint. For valid values, see Environments.	"https://prod.euid.eu" (the default)
params.storage	CR: Optional SO: Optional	String	Specify 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

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=="
}