This API only handles user data, or user signals, which are different from other first party data like site signals in nature. When many users visit a site, each of them may get different user data. Therefore we cannot predefine user data (i.e. put them on UI), but rely on the publishers to call this method for each visit. In contrast, site signals are the same for all the users visiting the site, so they can be well configured from UI, but we do not have that right now.

• handles Prebid User ID modules, ignores setBidderConfig for now
• handles Amazon too
• ignores Secure Signals and Taxonomy for now (maybe later)

A - By default user data will be passed to all modules

• Each module is responsible for inspecting the parameters and extracting the ones that it can use (ex: connectId module needs to know that it can use the “hem256” parameter for its “he” value)

// calling this (assuming UI Modules = connectId, liveIntentId, publinkId)
htlbid.setUserData({
  'hemmd5': '772ac1a55fab1122f3b369ee9cd31549',
  'hem256': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9'
})

// would result in calling (automatically/internally)
pbjs.setConfig({
  userSync: [{
    name: 'connectId',
    params: { // always sha256
      'he': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9',
    }
  }, {
    name: 'liveIntentId',
    params: { // md5, sha1, sha2, default to md5
      'emailHash': '772ac1a55fab1122f3b369ee9cd31549',
    }
  }, {
    name: 'publinkId',
    params: { // either md5 or sha256, default to sha256
      'e': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9',
    }
  }
});

B - Users can specify an individual module(s)

• Pass the list of modules as an array in the 2nd parameter
• @CraigeT (I think “userIds” can be an array, since the “default case” is to iterate over all installed modules 🤷 )

// calling this
htlbid.setUserData({
    'hemmd5': '772ac1a55fab1122f3b369ee9cd31549',
    'hem256': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9'
  }, {
    'userIds': ['connectId']
  }
})

// results in calling (automatic/internal)
pbjs.setConfig({
  userSync: [{
    name: 'connectId',
    params: { // always sha256
      'he': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9',
    }
  }
});

C - “hemmd5” and “hem256” are special, all other modules are passed through without being modified

// calling this
htlbid.setUserData({
    'p': '1-07c31e9b319214936481504bdc74dd81',
    'hem256': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9'
  }, {
    'userIds': ['connectId', 'id5']
  }
})

// results in calling (automatic/internal)
pbjs.setConfig({
  userSync: [{
    name: 'connectId',
    params: { // use the hem256 value for "he"
      'he': '5e913e218e1f3fcac8487d7fbb954bd9669f72a7ef6e9d9f519d94b6a8cc88b9',
    }
  }, {
    name: 'id5',
    params: { // pass through "p" unmodified
      'p': '1-07c31e9b319214936481504bdc74dd81',
    }
  }
});

D - The function can be called twice

• This handles possible edge cases where there are two modules that need to pass different values for the same parameter (should be rare, but Prebid is a moving target, so this COULD happen)