diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 3f2030041d..9ba1869cdf 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -25,6 +25,7 @@ The User ID module supports multiple ways of establishing pseudonymous IDs for u * **ID5 Universal ID** - a neutral identifier for digital advertising that can be used by publishers, brands and ad tech platforms (SSPs, DSPs, DMPs, Data Providers, etc.) to eliminate the need for cookie matching. * **Criteo RTUS ID** – fetches a user id by reaching out to Criteo rtus endpoint for each bidder configured. The result is stored in the user's browser for 1 hour and is passed to bidder adapters to pass it through to SSPs and DSPs that support the ID scheme. * **Identity Link** – provided by LiveRamp, this module calls out to the ATS (Authenticated Traffic Solution) library or a URL to obtain the user’s IdentityLink envelope. +* **LiveIntent ID** – fetches a user ID based on identifiers that are present on the page. It calls the LiveIntent Identity Exchange endpoint which resolves the inbound identifiers to a stable ID. ## How It Works @@ -61,7 +62,7 @@ of sub-objects. The table below has the options that are common across ID system {: .table .table-bordered .table-striped } | Param under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| name | Required | String | May be: `"unifiedId"`, `"pubCommonId"`, `"digitrust"`, `"id5id"` or `identityLink` | `"unifiedId"` | +| name | Required | String | May be: `"criteortus"`, `"digitrust"`, `"id5id"`, `identityLink`, `liveIntentId`, `"pubCommonId"`, or `"unifiedId"` | `"unifiedId"` | | params | Based on User ID sub-module | Object | | | | storage | Optional | Object | The publisher can specify some kind of local storage in which to store the results of the call to get the user ID. This can be either cookie or HTML5 storage. This is not needed when `value` is specified or the ID system is managing its own storage | | | storage.type | Required | String | Must be either `"cookie"` or `"html5"`. This is where the results of the user ID will be stored. | `"cookie"` | @@ -473,6 +474,90 @@ pbjs.setConfig({ }); {% endhighlight %} +## LiveIntent ID + +LiveIntent ID solution provides a user identifier based on our graph which is driven by publisher email business (e.g. updates, newsletters, and subscriptions). + +It is possible, that depending on the `partner` & `publisherId` combination, the response contains segment ids which have been mapped against partner systems and their segments. For example, if LiveIntent has created a segmentId `999` which can be mapped to (`partner: test-partner`) `test-partner`'s segment, the response from LiveIntent's ID solution could look like: +``` +{ + "unifiedId": "T7JiRRvsRAmh88", + "segments": ["999"] +} +``` + +The `request.userId.lipb` object would then look like +``` +{ + "lipbid": "T7JiRRvsRAmh88", + "segments": ["999"] +} +``` + +Therefore, the adapters can then be implemented to use the `lipibid` as the identifier, and `segments` to which that identifier is associated with. + +### Registering your own first party cookie space + +In order for you to take advantage of the user id resolution in cookie-challenged environments, you need to sync your first party cookie universe with us. For further information please reach out to peoplebased@liveintent.com. + +### LiveIntent ID configuration + +|Param under usersync.userIds[]|Scope|Type|Description|Example| +|---|:---:|:---:|---:|---:| +|`name`|Required | `String`|The name of this module|`'liveIntentId'`| +|`params`| Required|`Object`|Container of all module params|| +|`params.publisherId`| Required|`String`|The unique identifier of the publisher in question|`'12432415'`| +|`params.partner`| Optional|`String`|The name of the partner whose data will be returned in the response |`'prebid'`| +|`params.identifiersToResolve`|Optional|`Array[String]`|Additional identifiers that can be sent along with the id resolution request|`['my-id']`| +|`params.url`| Optional|`String`|In case a publisher is running Prebid.js and can call LiveIntent's Identity Exchange endpoint withing it's own domain, this parameter can be used to change the default endpoint URL|`'//idx.my-domain.com'`| + +### LiveIntent ID example + +The minimal setup would be as follows: +``` +pbjs.setConfig({ + usersync: { + userIds: [{ + name: "liveIntentId", + params: { + publisherId: "9896876" + } + }] + } +}) +``` + +If there are additional identifiers that LiveIntent could resolve, those can be added under the `identifiersToResolve` array in config params. +``` +pbjs.setConfig({ + usersync: { + userIds: [{ + name: "liveIntentId", + params: { + publisherId: "9896876", + identifiersToResolve: ["my-own-cookie"] + } + }] + } +}) +``` + +If there's a partner integration with LiveIntent, and partner specific data is to be returned and passed along in bid requests, the partner name can be set as `partner` in config params. +``` +pbjs.setConfig({ + usersync: { + userIds: [{ + name: "liveIntentId", + params: { + partner: "rubicon", + publisherId: "9896876", + identifiersToResolve: ["my-own-cookie"] + } + }] + } +}) +``` + ## Adapters Supporting the User ID Sub-Modules {% assign bidder_pages = site.pages | where: "layout", "bidder" %} @@ -495,10 +580,13 @@ Bidders that want to support the User ID module in Prebid.js, need to update the {: .table .table-bordered .table-striped } | ID System Name | ID System Host | Prebid.js Attr | Example Value | | --- | --- | --- | --- | --- | --- | -| PubCommon ID | n/a | bidRequest.userId.pubcid | `"1111"` | -| Unified ID | Trade Desk | bidRequest.userId.tdid | `"2222"` | +| CriteoRTUS | Criteo | bidRequest.userId.criteortus | `"1111"` | | DigiTrust | IAB | bidRequest.userId.digitrustid | `{data: {id: "DTID", keyv: 4, privacy: {optout: false}, producer: "ABC", version: 2}` | -| ID5 ID | ID5 | bidRequest.userId.id5id | `"ID5-12345"` | +| ID5 ID | ID5 | bidRequest.userId.id5id | `"1111"` | +| IdentityLink | Trade Desk | bidRequest.userId.idl_env | `"1111"` | +| LiveIntent ID | Live Intent | bidRequest.userId.lipb.lipbid | `"1111"` | +| PubCommon ID | n/a | bidRequest.userId.pubcid | `"1111"` | +| Unified ID | Trade Desk | bidRequest.userId.tdid | `"1111"` | For example, the adapter code might do something like: @@ -524,21 +612,34 @@ Bidders that want to support the User ID module in Prebid Server, need to update "rtiPartner": "TDID" } }] - }, - { - "source": "pubcommon", // PubCommon ID + },{ + "source": "pubcommon", "uids": [{ "id":"11111111" }] }, { - "source": "id5-sync.com", // ID5 ID + "source": "id5-sync.com", "uids": [{ "id": "ID5-12345" }] - } - ], - "digitrust": { // DigiTrust + },{ + "source": "identityLink", + "uids": [{ + "id": "11111111" + }] + },{ + "source": "criteo", + "uids": [{ + "id": "11111111" + }] + },{ + "source": "liveintent.com", + "uids": [{ + "id": "11111111" + }] + }], + "digitrust": { // DigiTrust is not in the eids section "id": "11111111111", "keyv": 4 }