ID5 Prebid Integration Workflow

Here’s a step-by-step overview of integrating ID5 into your Prebid configuration for any webpage. Once your Prebid.js setup is configured to fetch the ID5 ID, your demand partners in Prebid can access this ID and pass it to their server-side RTB partners (typically DSPs) as a means to communicate user identity. This enables DSPs to recognize and target users, manage frequency and recency caps, and apply additional data, even in environments where cookies are unsupported. This in turn, helps publishers futureproof user addressability and generate sustainable advertising revenue.

1. Register with ID5

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 our website to sign up and request your ID5 Partner Number.

2. Build Prebid.js with the User ID Module

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.

When building Prebid.js,  include both the userId, id5IdSystem , id5Id5AnalyticsAdaptermodules, in addition to the other modules you normally include.

gulp build –modules=userId,id5IdSystem,id5AnalyticsAdapter

You may also use the Prebid Download page to build your version of Prebid.js by selecting the User ID Module: ID5 ID, Analytics Adapter: ID5.

3. Configure the User ID Module

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

pbjs.setConfig({
  userSync: {
    userIds: [{
      name: 'id5Id',
      params: {
        partner: 173,            // change to the Partner Number you received from ID5
        externalModuleUrl: 'https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js',
        pd: 'MT1iNTBjY...'       // 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: 7200   // refresh ID every 2 hours to ensure it's fresh
      }
    }],
    auctionDelay: 250            // 250ms maximum auction delay, applies to all userId modules
  }
});

Configuration Parameters

Configuring the externalmoduleurl

To ensure you are using the latest version of ID5's identity reconciliation algorithms, we recommend you install at least Prebid.js v8.33.0 and provide the externalModuleUrl parameter. It should be set to the latest available module version at https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js. If you have any questions, please reach out to us at [email protected].

Configuring the pd parameter

To maximise addressability and produce the highest quality ID5 ID, publishers and advertisers must send additional signals such as Hashed Email, First Party user IDs in the Partner Data (pd) parameter when available. To ensure this information is shared in a secure way, please review the guidance here.  

Here is an example from Passing Partner Data to ID5 demonstrating how your configuration could look in Prebid:

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

Configuring the User ID module for A/B Testing (Optional)

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. A common control group percentage used is 5%. 

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,id5AnalyticsAdapter,consentManagement

You will also need to ensure you add the appropriate configuration to your setConfig() function to include consentManagement:

        // JavaScript
        pbjs.setConfig({
        userSync: {
          userIds: [{
            name: 'id5Id',
            params: {
              partner: 173,            // change to the Partner Number you received from ID5
              externalModuleUrl: 'https://cdn.id5-sync.com/api/1.0/id5PrebidModule.js',
              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: 7200   // refresh ID every 2 hours to ensure it's fresh
            }
          }],
          auctionDelay: 250            // 250ms maximum auction delay, applies to all userId modules
        }
      });
        

ID5 User ID Module Response

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 using the ID5 ID.

The ID5 User ID module provides following eids:

{
          source: 'id5-sync.com',
          uids: [
            {
              id: 'some-random-id-value',
              atype: 1,
              ext: {
                linkType: 2,
                abTestingControlGroup: false
              }
            }
          ]
        },
        {
          source: 'true-link-id5-sync.com',
          uids: [
            {
              id: 'some-publisher-true-link-id',
              atype: 1
            }
          ]
        },
        {
          source: 'uidapi.com',
          uids: [
            {
              id: 'some-uid2',
              atype: 3,
              ext: {
                provider: 'id5-sync.com'
              }
            }
          ]
        }
        

The ID from id5-sync.com should be always present (though the id provided will be '0' in case of no consent or optout).

The ID from uidapi.com will be available if the partner that is used in ID5 user module has the EUID2 integration enabled (it has to be enabled on the ID5 side).

The ID from true-link-id5-sync.com will be available if the page is integrated with TrueLink (if you are an ID5 partner you can learn more at here).

ID5 ID Encryption

The ID5 ID 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 2 hours ( 7200 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.

4. Configure the ID5 Prebid Analytics Module for Identity Insights

To help publishers better understand the value of working with ID5, we have launched Identity Insights - an ID5 analytics adapter for Prebid. With just a few additional lines of configuration, ID5 is able to capture prebid event data to provide publishers with additional insights about the value of the ID5 ID to their business. For now, insights will be provided in the form of an adhoc report shared by the ID5 publisher support team. Identity Insights is currently free for publishers to use. 

To enable ID5 Identity Insights within Prebid, you will need to include the ID5 analytics adapter when you build Prebid:

gulp build –modules=userId,id5IdSystem,id5AnalyticsAdapter

In addition to including the ID5 Analytics Adapter in your prebid build, 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
  }
});

To better analyze the results of the ID5 ID, we recommend that you use the A/B Testing feature described in the Prebid.js User ID Module. This will allow us to analyze key KPIs such as average bid CPM, average winning bid CPM, bid response rate and bid density when the ID5 ID is present versus when it is not present (control group). 

How to Check if the ID5 Analytics Module is installed correctly

The following steps describe how to check your ID5 prebid integration:

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 is 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 the ID5 Identity Insights were correctly installed:

How to Check if the ID5 Analytics Adapter 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 is configured 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 should 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.

5. Integrate TrueLink (Recommended)

TrueLink is an additional client-side integration method that can complement a standard ID5 JS API or Prebid (version 9.2.0 and above) implementation. With a TrueLink integration, ID5 can create a cross-domain signal called the TrueLink ID for a single user within a specific browser. The TrueLink ID is produced independently of third party cookies by redirecting the user through an ID5 operated domain and setting the ID as a first party cookie. 

This TrueLink signal is utilized by ID5 for cross domain user reconciliation and the generation of a high-quality ID5 ID. Publishers can optionally access a publisher first-party user identifier called the ID5 Guarded Publisher ID (GPID). The GPID is a publisher specific version of the ID5 ID which remains unique for a user across their owned and operated properties within a given browser environment. It's quality is implicitly linked to the provision of signals such as hashed emails and TrueLink signals. The GPID can be used to facilitate use cases such as cross-domain audience building and activation, all without relying on third-party cookies. It may also be used as a PPID within Google Ad Manager.

To integrate TrueLink, follow the instructions here. 

6. Add the ID5 tag to your Webpage (Recommended)

While third-party cookies are still in use, ID5 can synchronize with ad tech vendors to enhance user recognition, improving audience addressability and monetization.

Follow the steps outlined here. 

7. Use ID5's GPID as a first party identifier or PPID (Optional)

ID5 can optionally provide publisher and advertisers with access to a partner-specific version of the ID5 ID, known as the Guarded Publisher ID (GPID). The GPID can be used for various publisher or advertiser purposes, including cross-domain audience building, audience activation, measurement, and attribution. The GPID can also be used as a Publisher Provided Identifier (PPID) in ad servers like Google Ad Manager or AppNexus. Google’s PPID, for example, enables publishers to:

• Apply audience-based ad delivery controls, such as frequency capping and sequential ad rotation.
• Enhance audience segmentation and targeting across devices.
• Potentially increase CPMs from Google’s buying stack.

You can find out more about the GPID and how to get it enabled here.