ID5 Help Center

Prebid.js User ID Module

What is the ID5 ID?

The ID5 ID is a shared, neutral identifier that publishers and ad tech platforms can use to recognise users even in environments where 3rd party cookies are not available or blocked. ID5 enables publishers to create and distribute a shared 1st party identifier to the entire ecosystem. Ad tech platforms that connect with ID5 can decrypt the ID5 ID and improve their user recognition capabilities. The ID5 ID is designed to respect users' privacy choices throughout the advertising value chain.

Registration

The ID5 ID is free to use, but requires a simple registration with us. If you don’t already have an account with ID5, please visit https://id5.io/solutions/ to sign up and request your ID5 Partner Number to get started.

How does the ID5 ID work?

By using the ID5 ID, ad tech platforms can eliminate the need to sync their platform-specific IDs with their partners - the equivalent of needing a translator to help two people speaking different languages understand each other. When all platforms are using the ID5 ID to transact against, it's like they're all speaking the same, common language. After configuring your Prebid.js setup to pull the ID5 ID, your demand partners configured in Prebid can retrieve the ID and pass it on to their server side RTB partners (typically DSPs). This allows the DSP to target the user, manage frequency and recency capping, and apply additional data, even when cookies are not supported.

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

By activating the ID5 ID, the following will take place:
  1. When a user is on your page, Prebid will make an asynchronous call to ID5 to retrieve the ID5 ID.
  2. ID5 returns the ID5 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 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 ID in any RTB bid requests as a separate field in the bid request
  6. The buyer can then use the ID5 ID to lookup the user in their database and perform any targeting or capping that their campaigns require.

Setup Instructions

Below are step by step instructions for installing and configuring the Prebid.js User ID Module with the ID5 ID. The instructions below assume a basic understanding of building Prebid.js and editing its page-level configuration; for more detailed instructions, getting started guides, and more, please visit the Prebid.org website.

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

When building Prebid.js, be sure to include both the userId and id5IdSystem  modules, in addition to the other modules you normally include.
gulp build –modules=userId,id5IdSystem
You may also use the Prebid Download page to build your version of Prebid.js by selecting the User ID: ID5 ID module.

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

Within the pbjs.setConfig() function, add the following configuration before you make a request for bids:

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: 50             // 50ms 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 will 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 Publisher 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.

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
You will also need to ensure you add the appropriate configuration to your setConfig() function to include 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
  }
});

A Note About ID5 ID Encryption

The ID5 ID that is delivered to Prebid is encrypted by ID5 with a rotating key to avoid unauthorized usage and to enforce privacy requirements. Only platforms that have the necessary rights to process user data will be able to decrypt the ID and use it for targeting, frequency capping, measurement, etc. Therefore, we strongly recommend setting storage.refreshInSeconds to 8 hours ( 8*3600 seconds) or less to ensure all demand partners receive an ID that has been encrypted with the latest key, has up-to-date privacy signals, and allows them to transact against it.

Test the implementation

1. Open a fresh Incognito Chrome window and block 3rd party cookies
2. Open the Developer Tools (Right Click ->Inspect)
3. On the “Network” tab filter the calls on type XHR and/or “id5-sync” word.
4. Load the page with the implementation
5. You should see a call named “{your_partner_id}.json”
6. Checking this call’s “Header” you should see the following parameters with similar arguments in the Request Payload:
gdpr: 1
gdpr_consent: "CPIQREsPIQREsAKAfAENBfCsAP_AAH_AAAq(..)AAAAAAAAAAA"
nbPage: 1
o: "pbjs"
partner: 569
rf: "https://samples.id5.io/prebid/basic"
top: 1
u: "https://samples.id5.io/prebid/basic"
us_privacy: "1---"
v: "4.41.0-pre"
7. In the “Preview” section you should be able to see the response with the following parameters and similar arguments:
cascade_needed: true
created_at: "2021-06-23T15:07:17.393691Z"
id5_consent: true
link_type: 1
original_uid: "ID5-ZHMOPFnlEuZUiTZm66NlvRSGUtOjDOvMuq32pi5faQ!ID5*sgkvlNQYh8kOFevtjqrBvlVV5Ik74m4wJPvPLU5vPbIAAHeYGN1U0RxRQ0UyWqzW"
privacy: {jurisdiction: "gdpr", id5_consent: true}
id5_consent: true
jurisdiction: "gdpr"
signature: "ID5_ARU4SbAU3bWbwAkBSlFiA8FkoKEPuqazy4Uq9TTBouhP9Ust7cO3PQuY5R4JTK8CDtIF8DndSNZaQpUq63zsRrM"
universal_uid: "ID5-ZHMOU-ezE4XV_npnkJJFmV9pzH_gNy4iKPxMMid9OQ!ID5*jcnGHYRmOEFSVHUosBEZF07e4p6oYbx89al3HuWm9msAAHhFXe9BOdg75rHZKJZ2"
8. Confirm the Local Storage was written on your domain by going to the “Application” tab. Under the "Application" tab, the place where you can confirm this could differ depending on a couple of different factors (custom implementation, the version of Prebid you're using, etc.). On the latest Prebid version you can check by clicking on the “id5id” key where you should be able to see the encoded response parameters and arguments from step 7.

Prebid Analytics Module

This product is currently in Closed Alpha. If you'd like to participate, please reach out to your Account Manager or email us at support@id5.io
The ID5 Prebid Analytics module is available in version 4.43.0 of Prebid.js and later
To help publishers better understand the value of working with ID5, we have launched an Analytics Module for Prebid. With just a few additional lines of configuration, publishers can use ID5's analytics platform to dig into the data without having to build their own reporting tools. 

The analytics module is currently free for publishers to use during the Alpha and Beta periods. If you are interested in signing up, please let us know by reaching out to your Account Manager or emailing us at support@id5.io.

Enabling the Analytics Module

To enable the ID5 Analytics Module within Prebid, you will need to include the module when you build Prebid:
gulp build –modules=userId,id5IdSystem,id5AnalyticsAdapter
You will also need to ensure you enable analytics (this is in addition to the configuration described above to enable the ID5 User ID module):
pbjs.enableAnalytics({
  provider: 'id5Analytics',
  options: {
    partnerId: 173    // change to the Partner Number you received from ID5
  }
});
In order to better analyze the results of the ID5 ID, we recommend that you use the A/B Testing feature described above when enabling Analytics.

Checking prebid analytics implementation

How to check if the prebid modules are installed correctly

  1. Open a fresh incognito Chrome page, block 3rd party cookies and open the Developer Tools (Right Click ->Inspect)

  2. Load a web page where prebid with the ID5 module setup;

  3. Move to the “Console” and type: “pbjs.installedModules”. This will return all the modules from your prebid configuration;

  4. Among all modules returned you should be able to see "id5AnalyticsAdapter". Seeing the id5AnalyticsAdapter will mean that it was correctly installed:



How to check if the id5AnalyticsAdapter is configured correctly
  1. Open a fresh incognito Chrome page, block 3rd party cookies and open the Developer Tools (Right Click ->Inspect);

  2. Load a web page where prebid with the ID5 module setup;

  3. On the “Network” tab filter the calls on type XHR and/or “id5-sync” word.

  4. You should now see a call named “{your_partner_id}.json” and another one named “pbjs”. The call named “{your_partner_id}.json” is made to retrieve the ID5 ID. The call named “pbjs” is made by the analytics module; 

  5. Clicking on the call and after clicking on “Preview” will allow you to see the response from ID5:
    {ingestUrl: "https://api.id5-sync.com/analytics/event", sampling: 10}

  6. Seeing the “pbjs” call and the response from point 6 will mean that the implementation is correct.