What is the ID5 Universal ID?

Registration

Stay up-to-date

How does the ID5 Universal ID work?

What will happen if I turn on the ID5 Universal ID on my page?

1. When a user is on your page, Prebid will make an asynchronous call to ID5 to retrieve the ID5 Universal ID.
   
2. ID5 returns the ID5 Universal ID to Prebid, which will then store the result in 1st party local storage with an expiration set by your config.
   
3. On subsequent page loads, if the ID is already present in the browser, there will be no need to call ID5 to retrieve the ID again, so there is minimal latency impact on your page
   
4. Bid adapters that you have configured can choose to listen to the ID5 Universal ID within their adapter. If they do, they can pass the ID to their server.
   
5. The bid adapter’s server can then include the ID5 Universal ID in any RTB bid requests as a separate field in the bid request
   
6. The buyer can then use the ID5 Universal ID to lookup the user in their database and perform any targeting or capping that their campaigns require.
   

Setup Instructions

Step 1: Build Prebid.js with the User ID Module

gulp build –modules=userId,id5IdSystem

Step 2: Configure the User ID Module in the page configuration

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'id5Id',
      params: {
        partner: 173,            // change to the Partner Number you received from ID5
        pd: 'MT1iNTBjY...'       // optional, see below for a link to how to generate the pd string
        abTesting: {             // optional
          enabled: true,         // false by default
          controlGroupPct: 0.1   // valid values are 0.0 - 1.0 (inclusive)
        }
      },
      storage: {
        type: 'html5',           // 'html5' is the required storage type
        name: 'id5id',           // 'id5id' is the required storage name
        expires: 90,             // storage lasts for 90 days
        refreshInSeconds: 8*3600 // refresh ID every 8 hours to ensure it's fresh
      }
    }],
    auctionDelay: 250            // 250ms maximum auction delay, applies to all userId modules
  }
});

ATTENTION

As of Prebid.js v4.13.0, ID5 requires storage.type to be "html5" and storage.name to be "id5id". Using other values will display a warning today, but in an upcoming release, it may prevent the ID5 module from loading. This change is to ensure the ID5 module in Prebid.js interoperates properly with the ID5 API and to reduce the size of publishers' first-party cookies that are sent to their web servers. If you have any questions, please reach out to us at prebid@id5.io.

Configuration Parameters

Name	Required	Type	Description	Example
partner	Required	Number	This is the ID5 Partner Number obtained from registering with ID5.	173
pd	Optional	String	Publisher-supplied data, such as hashed email address or publisher user id, used for linking ID5 IDs across domains. Omit the parameter or leave as an empty string if no data to supply. Learn how to populate this field.	"MT1iNTBjY..."
abTesting	Optional	Object	Allows publishers to easily run an A/B Test. If enabled and the user is in the Control Group, the ID5 ID will NOT be exposed to bid adapters for that user. See below for more details.	Disabled by default
abTesting.enabled	Optional	Boolean	Set this to true to turn on this feature	true
abTesting.controlGroupPct	Optional	Number	Must be a number between 0.0 and 1.0 (inclusive) and is used to determine the percentage of users that fall into the control group (and thus not exposing the ID5 ID). For example, a value of 0.20 will result in 20% of user without an ID5 ID and 80% with an ID.	0.10

PD Example

Taking the example from Passing Partner Data to ID5, here's how your configuration could look in Prebid: 

...
params: {
    partner: 173,   // change to the Partner Number you received from ID5
    pd: 'MT1iNTBjYTA4MjcxNzk1YThlN2U0MDEyODEzZjIzZDUwNTE5M2Q3NWMwZjJlMmJiOTliYWE2M2FhODIyZjY2ZWQzJjU9bSVDMyVCNmxsZXIlMjZmcmFuJUMzJUE3b2lz'
},
...

A/B Testing

The abTesting feature is available in version 4.20.0 of Prebid.js and later

Publishers may want to test the value of the ID5 ID with their downstream partners. While there are various ways to do this, A/B testing is a standard approach. Instead of publishers manually enabling or disabling the ID5 User ID Module based on their control group settings (which leads to fewer calls to ID5, reducing our ability to recognize the user), we have baked this in to our module directly.

To turn on A/B Testing, simply edit the configuration (see details above) to enable it and set what percentage of users you would like to set for the control group. The control group is the set of users where an ID5 ID will not be exposed to bid adapters or in the various user id functions available on the pbjs global. An additional value of ext.abTestingControlGroup will be set to true or false and can be used to inform reporting systems that the user was in the control group or not. It's important to note that the control group is user based, and not request based. In other words, from one page view to another, a user will always be in or out of the control group without changing.

GDPR Support

The ID5 ID is a privacy-by-design implementation of a shared ID and fully supports the GDPR. When the ID5 ID is requested by Prebid in a GDPR-relevant country, ID5 will ensure the user has consented to processing by ID5 for the “Information storage and access” purpose (Purpose 1). If not, ID5 will not attempt to read or write our 3P cookie and we will not deliver an ID.

To enable GDPR support within Prebid, you will need to include the GDPR Consent Management module when you build Prebid:

gulp build –modules=userId,id5IdSystem,consentManagement

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'id5Id',
      params: {
        partner: 173,            // change to the Partner Number you received from ID5
        pd: 'MT1iNTBjY...'       // optional
        abTesting: {             // optional
          enabled: true,         // false by default
          controlGroupPct: 0.1   // valid values are 0.0 - 1.0 (inclusive)
        }
      },
      storage: {
        type: 'html5',           // 'html5' is the required storage type
        name: 'id5id',           // 'id5id' is the required storage name
        expires: 90,             // storage lasts for 90 days
        refreshInSeconds: 8*3600 // refresh ID every 8 hours to ensure it's fresh
      }
    }],
    auctionDelay: 50             // 50ms maximum auction delay, applies to all userId modules
  },
   
  consentManagement: {
    cmpApi: 'iab',
    timeout: 8000
  }
});