From e21ba60df7b634a2b1b8112a734c5d3d10557939 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Fri, 17 Jan 2025 16:54:39 +0100 Subject: [PATCH 01/14] optableRtdProvider draft doc --- dev-docs/modules/optableRtdProvider.md | 134 +++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 dev-docs/modules/optableRtdProvider.md diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md new file mode 100644 index 0000000000..383b20af6d --- /dev/null +++ b/dev-docs/modules/optableRtdProvider.md @@ -0,0 +1,134 @@ +--- +layout: page_v2 +title: Optable RTD Provider Module +display_name: Optable RTD Module +description: Optable Real Time Data Module +page_type: module +module_type: rtd +module_code : optable +enable_download : true +vendor_specific: true +sidebarType : 1 +--- + +{: .alert.alert-warning :} +This module may load a publisher-specific JavaScript bundle. The external resource provides flexibility in ID handling without the need to modify the RTD submodule source code. + +# Optable RTD Submodule +{:.no_toc} + +* TOC +{:toc} + +## Description + +Optable module enriches an OpenRTB request by setting `user.ext.eids` and `user.ext.data` using an identity graph and audience segments service hosted by Optable on behalf of the publisher. As input the module may consume user's sha256-hashed email, phone, post_code or (non-hashed) publisher provided identifiers (PPIDs). + +## Usage + +### Integration + +Compile the Optable RTD Module with other modules and adapters into your Prebid.js build: + +```bash +gulp build --modules="rtdModule,optableRtdProvider,appnexusBidAdapter,..." +``` + +> Note that Optable RTD module is dependent on the global real-time data module, `rtdModule`. + +### Preloading Optable SDK bundle + +In order to use the module you first need to register with Optable and obtain a bundle URL. The bundle URL may be specified as a `bundleUrl` parameter to the script, or otherwise it can be added directly to the page source as: + +``` + ``` In this case bundleUrl parameter is not needed and the script will await bundle loading before delegating to it. ### Configuration -This module is configured as part of the `realTimeData.dataProviders`. We recommend setting `auctionDelay` to 1000 ms and make sure `waitForIt` is set to `true` for the `Optable` RTD provider. +This module is configured as part of the `realTimeData.dataProviders`. We recommend setting `auctionDelay` to 1000 ms and make sure `waitForIt` is set to `true` for the `Optable` RTD provider. ```javascript pbjs.setConfig({ - debug: true, // we recommend turning this on for testing as it adds more logging - realTimeData: { - auctionDelay: 1000, - dataProviders: [ - { - name: 'optable', - waitForIt: true, // should be true, otherwise the auctionDelay will be ignored - params: { - bundleUrl: '', - adserverTargeting: '', - ppidMapping: { - // optional mapping between eids sources and optable custom identifier names - "example.com": "c0", - "source-id.com": "c1", //... - } - }, - }, - ], - }, + debug: true, // we recommend turning this on for testing as it adds more logging + realTimeData: { + auctionDelay: 1000, + dataProviders: [ + { + name: 'optable', + waitForIt: true, // should be true, otherwise the auctionDelay will be ignored + params: { + bundleUrl: '', + adserverTargeting: '', + ppidMapping: { + // optional mapping between eids sources and optable custom identifier names + "example.com": "c0", + "source-id.com": "c1", //... + } + }, + }, + ], + }, }); ``` ### Additional input to the module -Besides PPID (publisher provided IDs) in the `user.ext.eids` the module will pick up the following keys: +Besides PPID (publisher provided IDs) in the `user.ext.eids` the module will pick up the following keys: + - `user.ext.optable.email` - a SHA256-hashed user email - `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone]() (meaning a phone number consisting of digits only without spaces or any additional characters, f.e. a US number would be: `12345678999`) - `user.ext.optable.postal_code` - a ZIP postal code string -Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig` like so: +Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig` like so: -``` +```javascript pbjs.mergeConfig({ - ortb2: { - user: { - ext: { - optable: { - email: await sha256("test@example.com"), - phone: await sha256("12345678999"), - postal_code: "61054" - } - } + ortb2: { + user: { + ext: { + optable: { + email: await sha256("test@example.com"), + phone: await sha256("12345678999"), + postal_code: "61054" } + } } + } }) ``` -Where `sha256` function can be defined as: +Where `sha256` function can be defined as: -``` +```javascript async function sha256(input) { return [...new Uint8Array( await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input)) @@ -109,26 +110,29 @@ async function sha256(input) { } ``` -### Parameters +### Parameters {: .table .table-bordered .table-striped } -| Name | Type | Description | Default | -|:----------------------|:--------|:-------------------------------------------------------------------------------------------------|:-------------------| -| name | String | Real time data module name | Always 'optable' | -| waitForIt | Boolean | Should be set `true` together with auctionDelay: 1000 | `false` | -| params | Object | | | -| params.bundleUrl | String | Optable bundle URL | '' | -| params.adserverTargeting | boolean | If set to `true` targeting keywords will be passed to the ad server upon auction completion | false | -## Example +| Name | Type | Description | Default | +|--------------------------|---------|----------------------------------------------------------------------------------------------|------------------| +| name | String | Real time data module name | Always `optable` | +| waitForIt | Boolean | Should be set `true` together with auctionDelay: 1000 | `false` | +| params | Object | | | +| params.bundleUrl | String | Optable bundle URL | `null` | +| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | + +## Example If you want to see an example of how the optable RTD module works, run the following command: -`gulp serve --modules=rtdModule,optableRtdProvider,consentManagementTcf,tcfControl, consentManagementGpp,appnexusBidAdapter` +```bash +gulp serve --modules=optableRtdProvider,consentManagementGpp,consentManagementTcf,appnexusBidAdapter +``` and then open the following URL in your browser: -`http://localhost:9999/integrationExamples/gpt/optableRtdProvider_example.html` +[`http://localhost:9999/integrationExamples/gpt/optableRtdProvider_example.html`](http://localhost:9999/integrationExamples/gpt/optableRtdProvider_example.html) Open the browser console to see the logs. @@ -137,5 +141,3 @@ Open the browser console to see the logs. Any suggestions or questions can be directed to [prebid@optable.co](mailto:prebid@optable.co). Alternatively please open a new [issue](https://github.com/prebid/prebid-server-java/issues/new) or [pull request](https://github.com/prebid/prebid-server-java/pulls) in this repository. - - From 73025c58249400b46547b909303186565f52f3a4 Mon Sep 17 00:00:00 2001 From: Bohdan V <25197509+BohdanVV@users.noreply.github.com> Date: Tue, 18 Feb 2025 14:34:51 +0100 Subject: [PATCH 06/14] optableRtdProvider: update doc with a new parameter --- dev-docs/modules/optableRtdProvider.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 0c75ff5e6f..2bedfeef86 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -114,13 +114,14 @@ async function sha256(input) { {: .table .table-bordered .table-striped } -| Name | Type | Description | Default | -|--------------------------|---------|----------------------------------------------------------------------------------------------|------------------| -| name | String | Real time data module name | Always `optable` | -| waitForIt | Boolean | Should be set `true` together with auctionDelay: 1000 | `false` | -| params | Object | | | -| params.bundleUrl | String | Optable bundle URL | `null` | -| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | +| Name | Type | Description | Default | Notes | +|--------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| +| name | String | Real time data module name | Always `optable` | | +| waitForIt | Boolean | Should be set `true` together with `auctionDelay: 1000` | `false` | | +| params | Object | | | | +| params.bundleUrl | String | Optable bundle URL | `null` | Optional | +| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | +| params.handleRtd | Function | A function to handle RTD data. If not provided, the module will use the default handler. The function signature is `[async] (optableBundle, reqBidsConfigObj, userConsent, mergeFn, optableLog) => {}` | `null` | Optional | ## Example From c04718c94535adf006ab3e7001ee44f6eb85a59d Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 19 Feb 2025 19:14:25 +0100 Subject: [PATCH 07/14] add a paragraph on publisher customized RTD handler --- dev-docs/modules/optableRtdProvider.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 2bedfeef86..673e81deff 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -121,7 +121,21 @@ async function sha256(input) { | params | Object | | | | | params.bundleUrl | String | Optable bundle URL | `null` | Optional | | params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | -| params.handleRtd | Function | A function to handle RTD data. If not provided, the module will use the default handler. The function signature is `[async] (optableBundle, reqBidsConfigObj, userConsent, mergeFn, optableLog) => {}` | `null` | Optional | +| params.handleRtd | Function | An optional function that uses Optable data to enrich `reqBidsConfigObj` with the real-time data. If not provided, the module will do a default call to Optable bundle. The function signature is `[async] (reqBidsConfigObj, mergeFn) => {}` | `null` | Optional | + +## Publisher Customized RTD Handler Function + +When there is more pre-processing or post-processing needed prior/post calling Optable bundle - a custom `handleRtd` function can be supplied to do that. This function will also be responsible for the `reqBidsConfigObj` enrichment. `mergeFn` parameter taken by `handleRtd` is a standard Prebid.js utility function that take an object to be enriched and an object to enrich with: the second object's fields will be merged into the first one (also see the code of an example mentioned below): + +``` +mergeFn( + reqBidsConfigObj.ortb2Fragments.global, // or other nested object as needed + rtdData, +); + +``` + +A `handleRtd` function implementation has access to its surrounding context including capturing a `pbjs` object, calling `pbjs.getConfig()` and f.e. reading off the `consentManagement` config to make the appropriate decision based on it. ## Example From fc6e8af951b502481a8d2963d68a9f5006df17f5 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 19 Feb 2025 19:26:19 +0100 Subject: [PATCH 08/14] optableRtdProvider: improve wording --- dev-docs/modules/optableRtdProvider.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 673e81deff..ba9c0afe8d 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -22,7 +22,7 @@ This module may load a publisher-specific JavaScript bundle. The external resour ## Description -Optable module enriches an OpenRTB request by setting `user.ext.eids` and `user.ext.data` using an identity graph and audience segments service hosted by Optable on behalf of the publisher. As input the module may consume user's sha256-hashed email, phone, post_code or (non-hashed) publisher provided identifiers (PPIDs). +The Optable module enhances an OpenRTB request by populating `user.ext.eids` and `user.ext.data` using an identity graph and audience segmentation service hosted by Optable on behalf of the publisher. This RTD submodule primarily relies on the Optable bundle loaded on the page, which leverages the Optable-specific Visitor ID and other PPIDs to interact with the identity graph, enriching the bid request with additional user IDs and audience data. ## Usage @@ -62,11 +62,6 @@ pbjs.setConfig({ params: { bundleUrl: '', adserverTargeting: '', - ppidMapping: { - // optional mapping between eids sources and optable custom identifier names - "example.com": "c0", - "source-id.com": "c1", //... - } }, }, ], @@ -76,7 +71,8 @@ pbjs.setConfig({ ### Additional input to the module -Besides PPID (publisher provided IDs) in the `user.ext.eids` the module will pick up the following keys: +Optable bundle may use PPIDs (publisher provided IDs) from the `user.ext.eids` as input. +In addition other arbitrary keys can be used as input, f.e. the following: - `user.ext.optable.email` - a SHA256-hashed user email - `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone]() (meaning a phone number consisting of digits only without spaces or any additional characters, f.e. a US number would be: `12345678999`) @@ -110,6 +106,8 @@ async function sha256(input) { } ``` +To handle PPIDs and the above input - a custom `handleRtd` function may need to be provided. + ### Parameters {: .table .table-bordered .table-striped } From 408e1a0c8ebfb579ba5c939619f35c96b621ee22 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Wed, 26 Feb 2025 19:21:35 +0100 Subject: [PATCH 09/14] optable: phone format normalization clarified --- dev-docs/modules/optableRtdProvider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index ba9c0afe8d..269cc5affc 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -75,7 +75,7 @@ Optable bundle may use PPIDs (publisher provided IDs) from the `user.ext.eids` a In addition other arbitrary keys can be used as input, f.e. the following: - `user.ext.optable.email` - a SHA256-hashed user email -- `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone]() (meaning a phone number consisting of digits only without spaces or any additional characters, f.e. a US number would be: `12345678999`) +- `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone](https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization) (meaning a phone number consisting of digits and leading plus sign without spaces or any additional characters, f.e. a US number would be: `+12345678999`) - `user.ext.optable.postal_code` - a ZIP postal code string Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig` like so: From 9401de55e55acc6139898bb1b900f020772b30d7 Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Fri, 28 Feb 2025 17:33:58 +0100 Subject: [PATCH 10/14] optableRTDSubmodule: enhance summary --- dev-docs/modules/optableRtdProvider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 269cc5affc..03543c8713 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -22,7 +22,7 @@ This module may load a publisher-specific JavaScript bundle. The external resour ## Description -The Optable module enhances an OpenRTB request by populating `user.ext.eids` and `user.ext.data` using an identity graph and audience segmentation service hosted by Optable on behalf of the publisher. This RTD submodule primarily relies on the Optable bundle loaded on the page, which leverages the Optable-specific Visitor ID and other PPIDs to interact with the identity graph, enriching the bid request with additional user IDs and audience data. +Optable RTD submodule enriches the OpenRTB request by populating `user.ext.eids` and `user.ext.data` using an identity graph and audience segmentation service hosted by Optable on behalf of the publisher. This RTD submodule primarily relies on the Optable bundle loaded on the page, which leverages the Optable-specific Visitor ID and other PPIDs to interact with the identity graph, enriching the bid request with additional user IDs and audience data. ## Usage From b56cb0604fda1809066e8ea91b39e6b4aa35e707 Mon Sep 17 00:00:00 2001 From: Bohdan V <25197509+BohdanVV@users.noreply.github.com> Date: Fri, 7 Mar 2025 15:32:17 +0100 Subject: [PATCH 11/14] optableRtdProvider: fix lint issues --- dev-docs/modules/optableRtdProvider.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 03543c8713..a78f67a881 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -74,9 +74,9 @@ pbjs.setConfig({ Optable bundle may use PPIDs (publisher provided IDs) from the `user.ext.eids` as input. In addition other arbitrary keys can be used as input, f.e. the following: -- `user.ext.optable.email` - a SHA256-hashed user email -- `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone](https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization) (meaning a phone number consisting of digits and leading plus sign without spaces or any additional characters, f.e. a US number would be: `+12345678999`) -- `user.ext.optable.postal_code` - a ZIP postal code string +* `user.ext.optable.email` - a SHA256-hashed user email +* `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone](https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization) (meaning a phone number consisting of digits and leading plus sign without spaces or any additional characters, f.e. a US number would be: `+12345678999`) +* `user.ext.optable.postal_code` - a ZIP postal code string Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig` like so: @@ -112,25 +112,24 @@ To handle PPIDs and the above input - a custom `handleRtd` function may need to {: .table .table-bordered .table-striped } -| Name | Type | Description | Default | Notes | -|--------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| -| name | String | Real time data module name | Always `optable` | | -| waitForIt | Boolean | Should be set `true` together with `auctionDelay: 1000` | `false` | | -| params | Object | | | | -| params.bundleUrl | String | Optable bundle URL | `null` | Optional | -| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | +| Name | Type | Description | Default | Notes | +|--------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| +| name | String | Real time data module name | Always `optable` | | +| waitForIt | Boolean | Should be set `true` together with `auctionDelay: 1000` | `false` | | +| params | Object | | | | +| params.bundleUrl | String | Optable bundle URL | `null` | Optional | +| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | | params.handleRtd | Function | An optional function that uses Optable data to enrich `reqBidsConfigObj` with the real-time data. If not provided, the module will do a default call to Optable bundle. The function signature is `[async] (reqBidsConfigObj, mergeFn) => {}` | `null` | Optional | ## Publisher Customized RTD Handler Function When there is more pre-processing or post-processing needed prior/post calling Optable bundle - a custom `handleRtd` function can be supplied to do that. This function will also be responsible for the `reqBidsConfigObj` enrichment. `mergeFn` parameter taken by `handleRtd` is a standard Prebid.js utility function that take an object to be enriched and an object to enrich with: the second object's fields will be merged into the first one (also see the code of an example mentioned below): -``` +```javascript mergeFn( reqBidsConfigObj.ortb2Fragments.global, // or other nested object as needed rtdData, ); - ``` A `handleRtd` function implementation has access to its surrounding context including capturing a `pbjs` object, calling `pbjs.getConfig()` and f.e. reading off the `consentManagement` config to make the appropriate decision based on it. From eca6fe31fd8fc6d079acd0fb5a33645b693bb46a Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 13 Mar 2025 13:48:43 +0100 Subject: [PATCH 12/14] optableRtdProvider: fix typo: user.ext.data -> user.data --- dev-docs/modules/optableRtdProvider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index a78f67a881..6596c78438 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -22,7 +22,7 @@ This module may load a publisher-specific JavaScript bundle. The external resour ## Description -Optable RTD submodule enriches the OpenRTB request by populating `user.ext.eids` and `user.ext.data` using an identity graph and audience segmentation service hosted by Optable on behalf of the publisher. This RTD submodule primarily relies on the Optable bundle loaded on the page, which leverages the Optable-specific Visitor ID and other PPIDs to interact with the identity graph, enriching the bid request with additional user IDs and audience data. +Optable RTD submodule enriches the OpenRTB request by populating `user.ext.eids` and `user.data` using an identity graph and audience segmentation service hosted by Optable on behalf of the publisher. This RTD submodule primarily relies on the Optable bundle loaded on the page, which leverages the Optable-specific Visitor ID and other PPIDs to interact with the identity graph, enriching the bid request with additional user IDs and audience data. ## Usage From c32595aa9a2fe813de780a50a25f1dbd81d1cc4b Mon Sep 17 00:00:00 2001 From: Eugene Dorfman Date: Thu, 13 Mar 2025 14:01:07 +0100 Subject: [PATCH 13/14] optableRtdProvider: add a note on erasing custom fields in user.ext.optable --- dev-docs/modules/optableRtdProvider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index 6596c78438..b0fd226087 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -106,7 +106,7 @@ async function sha256(input) { } ``` -To handle PPIDs and the above input - a custom `handleRtd` function may need to be provided. +To handle PPIDs and the above input - a custom `handleRtd` function may need to be provided. In the custom `handleRtd` implementation make sure to erase any `user.ext.optable` fields not meant to be propagated to the bidders. ### Parameters From b4b1b5b94b2e9b9520a2b1b475279dbee4ea1199 Mon Sep 17 00:00:00 2001 From: Bohdan V <25197509+BohdanVV@users.noreply.github.com> Date: Wed, 26 Mar 2025 17:32:49 +0100 Subject: [PATCH 14/14] optableRtdProvider: change the method of passing extra data --- dev-docs/modules/optableRtdProvider.md | 51 +++++++++++++------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/dev-docs/modules/optableRtdProvider.md b/dev-docs/modules/optableRtdProvider.md index b0fd226087..f65daa1809 100644 --- a/dev-docs/modules/optableRtdProvider.md +++ b/dev-docs/modules/optableRtdProvider.md @@ -72,26 +72,20 @@ pbjs.setConfig({ ### Additional input to the module Optable bundle may use PPIDs (publisher provided IDs) from the `user.ext.eids` as input. -In addition other arbitrary keys can be used as input, f.e. the following: +In addition, other arbitrary keys can be used as input, f.e. the following: -* `user.ext.optable.email` - a SHA256-hashed user email -* `user.ext.optable.phone` - a SHA256-hashed [E.164 normalized phone](https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization) (meaning a phone number consisting of digits and leading plus sign without spaces or any additional characters, f.e. a US number would be: `+12345678999`) -* `user.ext.optable.postal_code` - a ZIP postal code string +* `optableRtdConfig.email` - a SHA256-hashed user email +* `optableRtdConfig.phone` - a SHA256-hashed [E.164 normalized phone](https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization) (meaning a phone number consisting of digits and leading plus sign without spaces or any additional characters, f.e. a US number would be: `+12345678999`) +* `optableRtdConfig.postal_code` - a ZIP postal code string -Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig` like so: +Each of these identifiers is completely optional and can be provided through `pbjs.mergeConfig(...)` like so: ```javascript pbjs.mergeConfig({ - ortb2: { - user: { - ext: { - optable: { - email: await sha256("test@example.com"), - phone: await sha256("12345678999"), - postal_code: "61054" - } - } - } + optableRtdConfig: { + email: await sha256("test@example.com"), + phone: await sha256("12345678999"), + postal_code: "61054" } }) ``` @@ -106,24 +100,31 @@ async function sha256(input) { } ``` -To handle PPIDs and the above input - a custom `handleRtd` function may need to be provided. In the custom `handleRtd` implementation make sure to erase any `user.ext.optable` fields not meant to be propagated to the bidders. +To handle PPIDs and the above input - a custom `handleRtd` function may need to be provided. ### Parameters {: .table .table-bordered .table-striped } -| Name | Type | Description | Default | Notes | -|--------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| -| name | String | Real time data module name | Always `optable` | | -| waitForIt | Boolean | Should be set `true` together with `auctionDelay: 1000` | `false` | | -| params | Object | | | | -| params.bundleUrl | String | Optable bundle URL | `null` | Optional | -| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | -| params.handleRtd | Function | An optional function that uses Optable data to enrich `reqBidsConfigObj` with the real-time data. If not provided, the module will do a default call to Optable bundle. The function signature is `[async] (reqBidsConfigObj, mergeFn) => {}` | `null` | Optional | +| Name | Type | Description | Default | Notes | +|--------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| +| name | String | Real time data module name | Always `optable` | | +| waitForIt | Boolean | Should be set `true` together with `auctionDelay: 1000` | `false` | | +| params | Object | | | | +| params.bundleUrl | String | Optable bundle URL | `null` | Optional | +| params.adserverTargeting | Boolean | If set to `true`, targeting keywords will be passed to the ad server upon auction completion | `true` | Optional | +| params.handleRtd | Function | An optional function that uses Optable data to enrich `reqBidsConfigObj` with the real-time data. If not provided, the module will do a default call to Optable bundle. The function signature is `[async] (reqBidsConfigObj, optableExtraData, mergeFn) => {}` | `null` | Optional | ## Publisher Customized RTD Handler Function -When there is more pre-processing or post-processing needed prior/post calling Optable bundle - a custom `handleRtd` function can be supplied to do that. This function will also be responsible for the `reqBidsConfigObj` enrichment. `mergeFn` parameter taken by `handleRtd` is a standard Prebid.js utility function that take an object to be enriched and an object to enrich with: the second object's fields will be merged into the first one (also see the code of an example mentioned below): +When there is more pre-processing or post-processing needed prior/post calling Optable bundle - a custom `handleRtd` +function can be supplied to do that. +This function will also be responsible for the `reqBidsConfigObj` enrichment. +It will also receive the `optableExtraData` object, which can contain the extra data required for the enrichment and +shouldn't be shared with other RTD providers/bidders. +`mergeFn` parameter taken by `handleRtd` is a standard Prebid.js utility function that take an object to be enriched and +an object to enrich with: the second object's fields will be merged into the first one (also see the code of an example +mentioned below): ```javascript mergeFn(