From a3c1b8d73f28866b77a40596712b39211ffdcdaa Mon Sep 17 00:00:00 2001 From: Rick Berman Date: Tue, 30 Jul 2019 13:21:33 -0700 Subject: [PATCH 01/10] PBID-2 Initial draft adding Parrable to the UserId module documentation Several places are incomplete and are marked with @TODO --- dev-docs/modules/userId.md | 47 +++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index e0b5e6f7bc..1dfe61bc1b 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 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. +* **Parrable ID** - A ... @TODO finish this section ## 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: `"unifiedId"`, `"pubCommonId"`, `"digitrust"`, `"id5id"`, `identityLink`, or `"parrableId"` | `"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"` | @@ -432,6 +433,49 @@ pbjs.setConfig({ }); {% endhighlight %} +## Parrable ID + +The Parrable ID is @TODO finish this section + +### Parrable ID Registration + +Each Parrable Partner has a Client ID assigned by Parrable. Please obtain the Parrable Partner Client ID from the vendor for each Parrable-aware bid adapter you will be using. + +### Parrable ID Configuration + +In addition to the parameters documented above in the Basic Configuration section: + +{: .table .table-bordered .table-striped } +| Param under usersync.userIds[] | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| params | Required | Object | Details for the Parrable ID. | | +| params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them. | `[30182847-e426-4ff9-b2b5-9ca1324ea09b]` | + +{: .alert.alert-info :} +NOTE: The Parrable ID that is delivered to Prebid will be encrypted by Parrable with a time-based key and updated frequently in the browser to enforce privacy requirements. +We recommend setting `storage.expires` to `365` days to ... @TODO finish this statement (Rick: I like having the note about privacy requirements. I'm less sure that we need to explain why we are picking a year for the cookie expiration. Leaving out a mention of avoiding unathorized use of our ID aka. distinermediation is intentional as that doesn't have clear value to the publisher.) + +### Parrable ID Examples + +{% highlight javascript %} +pbjs.setConfig({ + usersync: { + userIds: [{ + name: "parrableId", + params: { + partners: `['30182847-e426-4ff9-b2b5-9ca1324ea09b']` // change to the Parrable Partner Client ID(s) you received from the Parrable Partners you are using + }, + storage: { + type: "cookie", + name: "_parrable_eid", // create a cookie with this name + expires: 365 // cookie can last for a year + } + }], + syncDelay: 1000 + } +}); +{% endhighlight %} + ## Adapters Supporting the User ID Sub-Modules {% assign bidder_pages = site.pages | where: "layout", "bidder" %} @@ -458,6 +502,7 @@ Bidders that want to support the User ID module in Prebid.js, need to update the | Unified ID | Trade Desk | bidRequest.userId.tdid | `"2222"` | | 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"` | +| Parrable ID | Parrable | bidRequest.userId.parrableid | `"01.1563917337.c4768012dbede44e96fa1b1c639faa18bf142dfa0e6e4298b1d0d93e11118a9c4c06f0cedce4d285cd754fc4d445d9bad30986fe9203d57eda26c0445d910b4275d8e4d84bd50ae4ebc3"` | For example, the adapter code might do something like: From d693f6f5a62f142984b224df25351a623f1d74a6 Mon Sep 17 00:00:00 2001 From: Rick Berman Date: Tue, 30 Jul 2019 13:33:07 -0700 Subject: [PATCH 02/10] PBID-2 Needed quotes on a Parrable Partner Client ID example --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 1dfe61bc1b..e94d503c7e 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -449,7 +449,7 @@ In addition to the parameters documented above in the Basic Configuration sectio | Param under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params | Required | Object | Details for the Parrable ID. | | -| params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them. | `[30182847-e426-4ff9-b2b5-9ca1324ea09b]` | +[ params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them. | `["30182847-e426-4ff9-b2b5-9ca1324ea09b"]` | {: .alert.alert-info :} NOTE: The Parrable ID that is delivered to Prebid will be encrypted by Parrable with a time-based key and updated frequently in the browser to enforce privacy requirements. From c4eefc08f622764ae17be358ca165a4a4539ba0c Mon Sep 17 00:00:00 2001 From: Rick Berman Date: Tue, 30 Jul 2019 22:27:34 -0700 Subject: [PATCH 03/10] PBID-2 Changing example EID It's tempting to use a valid EID but if anyone were to play with it then we could get the device id it contains mixed up with others. With this commit, I've gone to a placeholder value that is syntatically valid/representative but will not decrypt. --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index e94d503c7e..cc90b0dae4 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -502,7 +502,7 @@ Bidders that want to support the User ID module in Prebid.js, need to update the | Unified ID | Trade Desk | bidRequest.userId.tdid | `"2222"` | | 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"` | -| Parrable ID | Parrable | bidRequest.userId.parrableid | `"01.1563917337.c4768012dbede44e96fa1b1c639faa18bf142dfa0e6e4298b1d0d93e11118a9c4c06f0cedce4d285cd754fc4d445d9bad30986fe9203d57eda26c0445d910b4275d8e4d84bd50ae4ebc3"` | +| Parrable ID | Parrable | bidRequest.userId.parrableid | `"01.1563917337.encrypted-value"` | For example, the adapter code might do something like: From 0aa3ea7466ac3b2c26907ba67416fe6b5c7be9c6 Mon Sep 17 00:00:00 2001 From: Justin Greene Date: Thu, 12 Sep 2019 18:08:53 -0400 Subject: [PATCH 04/10] PBID-2: updated userID with Parrable specific information --- dev-docs/modules/userId.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index cc90b0dae4..63aca441da 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -25,7 +25,7 @@ The User ID module supports multiple ways of establishing pseudonymous IDs for u * **ID5 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. -* **Parrable ID** - A ... @TODO finish this section +* **Parrable ID** - an encrypted psudonymous id that is consistent across all browsers and webviews on a device for every publisher the device visits. This module contacts Parrable to obtain the Parrable EID belonging to the specific device which can then be used by the bidder. ## How It Works @@ -435,25 +435,26 @@ pbjs.setConfig({ ## Parrable ID -The Parrable ID is @TODO finish this section +The Parrable ID is a Full Device Identifier that can be used to identify a device across different browsers and and webviews on a single device including browsers that have third party cookie restrictions. ### Parrable ID Registration -Each Parrable Partner has a Client ID assigned by Parrable. Please obtain the Parrable Partner Client ID from the vendor for each Parrable-aware bid adapter you will be using. +Please contact Parrable to obtain a Parrable Partner Client ID and/or use the Parrable Partner Client ID provided by the vendor for each Parrable-aware bid adapter you will be using. Note that if you are working with multiple Parrable-aware bid adapters you may use multiple Parrable Parter Client IDs. ### Parrable ID Configuration -In addition to the parameters documented above in the Basic Configuration section: +In addition to the parameters documented above in the Basic Configuration section the following Parrable specific configuration is required: {: .table .table-bordered .table-striped } | Param under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params | Required | Object | Details for the Parrable ID. | | -[ params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them. | `["30182847-e426-4ff9-b2b5-9ca1324ea09b"]` | +[ params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them and/or obtain your own. | `["30182847-e426-4ff9-b2b5-9ca1324ea09b"]` | {: .alert.alert-info :} -NOTE: The Parrable ID that is delivered to Prebid will be encrypted by Parrable with a time-based key and updated frequently in the browser to enforce privacy requirements. -We recommend setting `storage.expires` to `365` days to ... @TODO finish this statement (Rick: I like having the note about privacy requirements. I'm less sure that we need to explain why we are picking a year for the cookie expiration. Leaving out a mention of avoiding unathorized use of our ID aka. distinermediation is intentional as that doesn't have clear value to the publisher.) +NOTE: The Parrable ID that is delivered to Prebid is encrypted by Parrable with a time-based key and updated frequently in the browser to enforce consumer privacy requirements and thus will be different on every page view, even for the same user. + +We recommend setting `storage.expires` to no more than`364` days, which is the default cookie expiration that Parrable uses in the standalone parrable integration. ### Parrable ID Examples @@ -468,7 +469,7 @@ pbjs.setConfig({ storage: { type: "cookie", name: "_parrable_eid", // create a cookie with this name - expires: 365 // cookie can last for a year + expires: 364 // cookie can last for up to 1 year } }], syncDelay: 1000 @@ -502,7 +503,7 @@ Bidders that want to support the User ID module in Prebid.js, need to update the | Unified ID | Trade Desk | bidRequest.userId.tdid | `"2222"` | | 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"` | -| Parrable ID | Parrable | bidRequest.userId.parrableid | `"01.1563917337.encrypted-value"` | +| Parrable ID | Parrable | bidRequest.userId.parrableid | `"eidVersion.encryptionKeyReference.encryptedValue"` | For example, the adapter code might do something like: From 4574d2b53d2b321b9823536ec37f1f96010d8fcf Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 12:15:52 -0500 Subject: [PATCH 05/10] PBID-2 remove typo --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 63aca441da..cc922e54d8 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -435,7 +435,7 @@ pbjs.setConfig({ ## Parrable ID -The Parrable ID is a Full Device Identifier that can be used to identify a device across different browsers and and webviews on a single device including browsers that have third party cookie restrictions. +The Parrable ID is a Full Device Identifier that can be used to identify a device across different browsers and webviews on a single device including browsers that have third party cookie restrictions. ### Parrable ID Registration From ef0d3c7e6a7e401daa3564a7f1c8d4a78ef08842 Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 12:22:24 -0500 Subject: [PATCH 06/10] PBID-2 fix params.partner explanation --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index cc922e54d8..17a7906de1 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -449,7 +449,7 @@ In addition to the parameters documented above in the Basic Configuration sectio | Param under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params | Required | Object | Details for the Parrable ID. | | -[ params.partners | Required | Number | A list of Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them and/or obtain your own. | `["30182847-e426-4ff9-b2b5-9ca1324ea09b"]` | +[ params.partner | Required | Number | A list of one or more comma-separated Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them and/or obtain your own. | `"30182847-e426-4ff9-b2b5-9ca1324ea09b"` | {: .alert.alert-info :} NOTE: The Parrable ID that is delivered to Prebid is encrypted by Parrable with a time-based key and updated frequently in the browser to enforce consumer privacy requirements and thus will be different on every page view, even for the same user. From 993b55dbe41c9ef6c31fedbb066f7bef66f6f0dc Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 12:26:15 -0500 Subject: [PATCH 07/10] PBID-2 fix example partner key --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 17a7906de1..bb3c3340eb 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -464,7 +464,7 @@ pbjs.setConfig({ userIds: [{ name: "parrableId", params: { - partners: `['30182847-e426-4ff9-b2b5-9ca1324ea09b']` // change to the Parrable Partner Client ID(s) you received from the Parrable Partners you are using + partner: `'30182847-e426-4ff9-b2b5-9ca1324ea09b'` // change to the Parrable Partner Client ID(s) you received from the Parrable Partners you are using }, storage: { type: "cookie", From 578c96c2054b65478c2c690c88c8ee71601e49c4 Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 12:28:03 -0500 Subject: [PATCH 08/10] PBID-2 consistent quotes --- dev-docs/modules/userId.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index bb3c3340eb..75c5446de7 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -462,13 +462,13 @@ We recommend setting `storage.expires` to no more than`364` days, which is the d pbjs.setConfig({ usersync: { userIds: [{ - name: "parrableId", + name: `'parrableId'`, params: { partner: `'30182847-e426-4ff9-b2b5-9ca1324ea09b'` // change to the Parrable Partner Client ID(s) you received from the Parrable Partners you are using }, storage: { - type: "cookie", - name: "_parrable_eid", // create a cookie with this name + type: `'cookie'`, + name: `'_parrable_eid'`, // create a cookie with this name expires: 364 // cookie can last for up to 1 year } }], From e96d72b84b1d48611ca5b752e3bafbb67ec32750 Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 12:30:29 -0500 Subject: [PATCH 09/10] PBID-2 use single quotes for strings --- dev-docs/modules/userId.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 75c5446de7..53d518a779 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -449,7 +449,7 @@ In addition to the parameters documented above in the Basic Configuration sectio | Param under usersync.userIds[] | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | | params | Required | Object | Details for the Parrable ID. | | -[ params.partner | Required | Number | A list of one or more comma-separated Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them and/or obtain your own. | `"30182847-e426-4ff9-b2b5-9ca1324ea09b"` | +[ params.partner | Required | Number | A list of one or more comma-separated Parrable Partner Client IDs for the Parrable-aware bid adapters you are using. Please obtain Parrable Partner Client IDs from them and/or obtain your own. | `'30182847-e426-4ff9-b2b5-9ca1324ea09b'` | {: .alert.alert-info :} NOTE: The Parrable ID that is delivered to Prebid is encrypted by Parrable with a time-based key and updated frequently in the browser to enforce consumer privacy requirements and thus will be different on every page view, even for the same user. From 91c944cee5cf1aac2897dbbaba15f51e66d370e0 Mon Sep 17 00:00:00 2001 From: Eyas Ranjous Date: Mon, 7 Oct 2019 13:43:18 -0500 Subject: [PATCH 10/10] PBID-2 fix spelling --- dev-docs/modules/userId.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md index 53d518a779..f491786b5a 100644 --- a/dev-docs/modules/userId.md +++ b/dev-docs/modules/userId.md @@ -25,7 +25,7 @@ The User ID module supports multiple ways of establishing pseudonymous IDs for u * **ID5 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. -* **Parrable ID** - an encrypted psudonymous id that is consistent across all browsers and webviews on a device for every publisher the device visits. This module contacts Parrable to obtain the Parrable EID belonging to the specific device which can then be used by the bidder. +* **Parrable ID** - an encrypted pseudonymous ID that is consistent across all browsers and webviews on a device for every publisher the device visits. This module contacts Parrable to obtain the Parrable EID belonging to the specific device which can then be used by the bidder. ## How It Works @@ -454,7 +454,7 @@ In addition to the parameters documented above in the Basic Configuration sectio {: .alert.alert-info :} NOTE: The Parrable ID that is delivered to Prebid is encrypted by Parrable with a time-based key and updated frequently in the browser to enforce consumer privacy requirements and thus will be different on every page view, even for the same user. -We recommend setting `storage.expires` to no more than`364` days, which is the default cookie expiration that Parrable uses in the standalone parrable integration. +We recommend setting `storage.expires` to no more than`364` days, which is the default cookie expiration that Parrable uses in the standalone Parrable integration. ### Parrable ID Examples