User ID Module

• Overview
• How It Works
• User ID, GDPR, Permissions, and Opt-Out
  • Publisher First Party Opt-Out
• Basic Configuration
• Permissions
• User ID Sub-Modules
• Bidder Adapter Implementation
  • Prebid.js Adapters
  • Prebid Server Adapters
  • Exporting User IDs
• ID Providers
• ESP Configurations
• Further Reading

Overview

The User ID module supports multiple ways of establishing pseudonymous IDs for users, which is an important way of increasing the value of header bidding. Instead of having several exchanges sync IDs with dozens of demand sources, a publisher can choose to integrate with any of a number of ID schemes.

How It Works

1. The publisher determines which user ID modules to add to their Prebid.js package and consults with their legal counsel to determine the appropriate user disclosures.
2. The publisher builds Prebid.js by specifying one or more ID sub-modules they would like to include. e.g. “gulp build –modules=____IdSystem”. You also need to add the userId module to your Prebid.js distribution.
3. The page defines User ID configuration in pbjs.setConfig()
4. When setConfig() is called, and if the user has consented to storing IDs locally, the module is invoked to call the URL if needed
   1. If the relevant local storage is present or the value of the id is specified in the configuration, the module doesn’t call the URL and instead parses the scheme-dependent format, injecting the resulting ID into bidRequest.userId.
   2. If GDPR applies, the consent signal from the CMP is hashed and stored in a cookie called _pbjs_userid_consent_data. This is required so that ID sub-modules may be called to refresh their ID if the user’s consent preferences have changed from the previous page, and ensures cached IDs are no longer used if consent is withdrawn.
5. An object containing one or more IDs (bidRequest.userId) is made available to Prebid.js adapters and Prebid Server S2S adapters.
6. In addition to bidRequest.userId, bidRequest.userIdAsEids is made available to Prebid.js adapters and Prebid Server S2S adapters. bidRequest.userIdAsEids has userIds in ORTB EIDS format.
7. The page can call pbjs.getUserIds(), pbjs.getUserIdsAsEids(), or pbjs.getUserIdsAsync().

Note that User IDs aren’t as popular in the mobile app world because device ID is available in those ad serving scenarios.

Not all bidder adapters support all forms of user ID. See the tables below for a list of which bidders support which ID schemes.

User ID, GDPR, Permissions, and Opt-Out

When paired with the Consent Management module, privacy rules are enforced:

• The module checks the GDPR consent string
• If no consent string is available OR if the user has not consented to Purpose 1 (local storage):
  • Calls to an external user ID vendor are not made.
  • Nothing is stored to cookies or HTML5 local storage.

In addition, individual users may opt-out of receiving cookies and HTML5 local storage by setting these values:

• _pbjs_id_optout cookie or HTML5 local storage. The value can be anything – if it exists, the user is considered opted out and no userId modules will fire.
• _pubcid_optout cookie or HTML5 local storage. This is for backwards compatibility with the original PubCommonID module, as of 5.0 known as the SharedId module. Likewise, the value can be anything.

Publisher First Party Opt-Out

Without third-party cookies, mechanisms like the NAI don’t work, so some publishers may want to implement a first party opt-out so their users aren’t tagged with first party cookies containing IDs.

Publishers that want to do this should design their workflow and then set _pbjs_id_optout cookie or HTML5 local storage. For instance:

• read from an in-page javascript variable and set _pbjs_id_optout to any value.
• call an in-page function and use the results to create a _pbjs_id_optout cookie with any value.

Basic Configuration

By including this module and one or more of the sub-modules, a number of new options become available in setConfig(), under the userSync object as attributes of the userIds array of sub-objects.

The value parameter can be used to indicate an identifier the publisher has obtained via a direct integration with that identity provider that the publisher wishes to make available to Prebid.js bidders.

Publishers using Google AdManager may want to sync one of the identifiers as their Google PPID for frequency capping or reporting. The PPID in GAM (which is unrelated to the PPID UserId Submodule) has strict rules; refer to Google AdManager documentation for them. Please note, Prebid uses a GPT command to sync identifiers for publisher convenience. It doesn’t currently work for instream video requests, as Prebid typically interacts with the player, which in turn may interact with IMA. IMA does has a similar method as GPT, but IMA does not gather this ID from GPT.

The table below has the options that are common across ID systems. See the sections below for specific configuration needed by each system and examples.

Permissions

Publishers can control which user ids are shared with the bid adapters they choose to work with by using the bidders array. The bidders array is part of the User id module config, publisher may choose to send an id to some bidders but not all, the default behavior is that each user id go to all bid adapters the publisher is working with.

Use the optional bidders parameter to define an array of bidder codes to which this user ID may be sent.

In this example the SharedID sub adapter is only allowed to be sent to the Rubicon adapter.

userIds: [
  {
    name: "sharedId",
    bidders: [
      'rubicon'
    ],
    params: {
      syncTime: 60,      // in seconds
      defaultis24hours
    },
    storage: {
      type: "cookie",
      name: "sharedid",
      expires: 28        // in days
    }
  }
]

The Rubicon bid adapter would then receive

{
  "bidder": "rubicon",
  ...
  "userId": {
    "sharedid": {
      "id": "01*******",
      "third": "01E*******"
    }
  },
  "userIdAsEids": [
    {
      "source": "sharedid.org",
      "uids": [
        {
          "id": "01**********",
          "atype": 1,
          "ext": {
            "third": "01***********"
          }
        }
      ]
    }
  ],
  ...
}

User ID Sub-Modules

Bidder Adapter Implementation

If your ID structure is complicated, it is helpful to add tests for pbjs.getUserIds(), pbjs.getUserIdsAsEids() and pbjs.getUserIdsAsync().

To add a custom data type for the response of pbjs.getUserIdsAsEids(), see other examples within the createEidsArray method in /modules/userId/eid.js.

Prebid.js Adapters

Bidders that want to support the User ID module in Prebid.js need to update their bidder adapter to read the indicated bidRequest attributes and pass them to their endpoint.

For example, the adapter code might do something like:

   if (bidRequest.userId && bidRequest.userId.sharedid) {
    url+="&pubcid="+bidRequest.userId.sharedid;
   }

Prebid Server Adapters

Bidders that want to support the User ID module in Prebid Server need to update their server-side bid adapter to read the desired OpenRTB ‘user.ext.eids.source’ object and forward the relevant values to their endpoint.

See the Prebid.js EIDs javascript source for the definitive list of user EID sources.

Exporting User IDs

If you need to export the user IDs stored by Prebid User ID module, the getUserIds() function will return an object formatted the same as bidRequest.userId.

pbjs.getUserIds() // returns object like bidRequest.userId. e.g. {"pubcid":"1111", "tdid":"2222"}

You can use getUserIdsAsEids() to get the user IDs stored by Prebid User ID module in ORTB Eids format. Refer eids.md for output format.

pbjs.getUserIdsAsEids() // returns userIds in ORTB Eids format. e.g.
[
  {
      source: 'pubcid.org',
      uids: [{
          id: 'some-random-id-value',
          atype: 1
      }]
  },

  {
      source: 'adserver.org',
      uids: [{
          id: 'some-random-id-value',
          atype: 1,
          ext: {
              rtiPartner: 'TDID'
          }
      }]
  },

  {
      source: 'id5-sync.com',
      uids: [{
          id: 'ID5-12345',
          atype: 1,
          ext: {
              linkType: 2,
              abTestingControlGroup: false
          }
      }]
  }
]

pbjs.getUserIds() and pbjs.getUserIdsAsEids() may return only some IDs, or none at all, if they are called before all ID providers have had a chance to initialize - depending on auctionDelay and/or syncDelay, that may need to wait until an auction has completed. To access the complete set of IDs, you may use getUserIdsAsync, which returns a promise that is guaranteed to resolve only once all IDs are available:

pbjs.getUserIdsAsync().then(function (userIds) {
   // all IDs are available here:
   pbjs.getUserIds()       // same as the `userIds` argument
   pbjs.getUserIdsAsEids()
});

ID Providers

If you’re an ID provider that wants to get on this page:

• Fork Prebid.js and write a sub-module similar to one of the *IdSystem modules already in the modules folder.
• Add your *IdSystem name into the modules/.submodules.json file
• Follow all the guidelines in the contribution page.
• Submit a Pull Request against the Prebid.js repository.
• Fork the prebid.org documentation repository, modify /dev-docs/modules/userId.md, /download.md, and submit a documentation Pull Request.

ESP Configurations

Google now supports Encrypted Signals for Publishers(ESP), a program that allows publishers can explicitly share encrypted signals on bid requests with third-party bidders. User ID modules now support code which will register the signal sources and encrypted signal are created and is sent to GAM request in a3p parameter. ‘encryptedSignal’ configuration under userSync Module will help to configure signal sources.

Please find more details Share encrypted signals with bidders (Beta)

NOTE: For eids encryption (encryptedSignalSources.encrypt) set to true is not recommended unless downstream is informed of the changes.

NOTE: Publishers enabling passing eids/signal through ESP should reach out to SSPs integrated through OB to make sure to take any additional steps needed to ensure impact on 3p cookie based transaction is handled and impact is minimal.

ESP Configuration Example:

pbjs.setConfig({
    userSync: {
        ...,
        encryptedSignalSources: {
            "sources": [{
                source: ['sharedid.org', 'criteo.com', 'id5-sync.com', 'pubcid.org', 'audigent.com'],
                encrypt: false
            }, {
                source: ['pubmatic.com'],
                customFunc: () => {
                    return '{"keywords":["tech","auto"]}';
                },
                encrypt: true
            }, {
                source: ['segment.com'],
                customFunc: () => {
                    return '[{ "id": "1", "value": "seg1" },{ "id": "2", "value": "seg2" }]';
                },
                encrypt: true
            }],
            "registerDelay": 3000
        },
        ....
    }
})

This will have no effect until you call the registerSignalSources API. This method must be called after the pbjs.setConfig and gpt.js has loaded. See API reference for registerSignalSources

Further Reading

• Prebid.js Usersync
• GDPR ConsentManagement Module