diff --git a/dev-docs/modules/userid-submodules/liveintent.md b/dev-docs/modules/userid-submodules/liveintent.md index 882209903c..934fc5dca0 100644 --- a/dev-docs/modules/userid-submodules/liveintent.md +++ b/dev-docs/modules/userid-submodules/liveintent.md @@ -82,7 +82,7 @@ pbjs.setConfig({ ### Multiple user IDs -The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. +The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` and `fpid` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module. Note: `thetradedesk` will be exposed as `tdid` because of historical reasons. For example, in case `uid2` is configured to be requested in addition to the `nonID`, the `request.userId` object would look like the following: @@ -100,9 +100,54 @@ For example, in case `uid2` is configured to be requested in addition to the `no } ``` -NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk` behave the same way. +NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (as `tdid`) and `fpid` behave the same way. -For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`, there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. +For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid` there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples. + +### FPID + +The `fpid` is a first party identifier that can be exposed through the liveconnect user ID module. In order to use this functionality tell the module which identifier you want to use as a `fpid` in the config params: + +```javascript +{ + "params": { + "fpid": { + "strategy": "cookie", // "cookie" | "html5" -- Where the identifier should be read from + "name": "foobar" // key in the chosen storage backend + } + } +} +``` + +Additionally, add it to the requested attributes: + +```javascript +{ + //... + "params": { + "fpid": { + "strategy": "cookie", + "name": "foobar" + }, + "requestedAttributesOverrides": {'fpid': true} + } + //... +} +``` + +The user id result will contain both the `fpid` directly in the `lipb` object and separately: + +```javascript +{"lipb":{"fpid":"foobar"},"fpid":{"id":"foobar"}} +``` + +The same applies for the eids: + +```javascript +[{"source":"fpid.liveintent.com","uids":[{"id":"foobar","atype":1}]}] +``` + +NOTE: If COPPA applies, LiveIntent’s user ID module will not return the `fpid`. ### Request uid2 @@ -139,7 +184,7 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.ajaxTimeout |Optional| Number |This configuration parameter defines the maximum duration of a call to the `IdentityResolution` endpoint. By default, 5000 milliseconds.|`5000`| | params.partner | Optional| String |The name of the partner whose data will be returned in the response.|`prebid`| | params.identifiersToResolve |Optional| Array[String] |Used to send additional identifiers in the request for LiveIntent to resolve against the LiveIntent ID and additional attributes.|`['my-id']`| -| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `thetradedesk`. | `{'uid2': true}` | +| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index`, `thetradedesk` (`tdid`) and `fpid`. | `{'uid2': true}` | | params.emailHash |Optional| String |The hashed email address of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha2.|`1a79a4d60de6718e8e5b326e338ae533`| | params.url | Optional| String |Use this to change the default endpoint URL if you can call the LiveIntent Identity Exchange within your own domain.|`https://idx.my-domain.com`| | params.liCollectConfig |Optional| Object |Container of all collector params.|| @@ -148,6 +193,12 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at | params.liCollectConfig.fpiExpirationDays |Optional| Number |The expiration time of an identifier created and updated by LiveConnect. By default, 730 days.|`729`| | params.liCollectConfig.collectorUrl |Optional| String |The parameter defines where the signal pixels are pointing to. The params and paths will be defined subsequently. If the parameter is not set, LiveConnect will by default emit the signal towards `https://rp.liadm.com`.| `https://rp.liadm.com`| | params.liCollectConfig.appId |Optional| String |LiveIntent's media business entity application ID.|`a-0012`| +| params.fpid.name | Optional | String | The parameter is cookie/localstorage key name | `'__super_duper_cookie'`| +| params.fpid.strategy | Optional | String | The parameter defines where to get the identifier from. Either from the cookie jar, `'cookie'`, or from the local storage, `'html5'`. | `'html5'`| +| storage | Required | Object | This object defines where and for how long the results of the call to get a user ID will be stored. | | +| storage.type | Required | String | This parameter defines where the resolved user ID will be stored (either `'cookie'` or `'html5'` localstorage).| `'cookie'` | +| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'pbjs_li_nonid'` | +| storage.expires | Recommended | Integer | How long (in days) the user ID information will be stored. The recommended value is `1` | `1` | ## LiveIntent ID examples @@ -202,6 +253,10 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at fpiExpirationDays: 730, collectorUrl: "https://rp.liadm.com", appId: "a-0012" + }, + fpid: { + strategy: "cookie" + name: "foobar" } } }]