From efea87eb642eb7c52eba03cc2562b1c3b91443c2 Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Thu, 3 Feb 2022 16:47:36 +0100 Subject: [PATCH 1/5] update doc --- dev-docs/modules/weboramaRtdProvider.md | 127 ++++++++++++++++++------ 1 file changed, 99 insertions(+), 28 deletions(-) diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index 63e8f4d96a..f7b41d862e 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -29,43 +29,43 @@ Compile the Weborama RTD module into your Prebid build: Add the Weborama RTD provider to your Prebid config. -Minimal configuration: -``` +Minimal Configuration: + +```javascript var pbjs = pbjs || {}; pbjs.que = pbjs.que || []; pbjs.que.push(function () { pbjs.setConfig({ - debug: true, + debug: true, // to be possible log on console, perhaps should be disable in production realTimeData: { auctionDelay: 1000, dataProviders: [{ name: "weborama", waitForIt: true, params: { - // you should choose activate the site-centric and/or the user-centric data management below: - weboCtxConf: { - token: "to-be-defined", // mandatory to use the contextual api + weboCtxConf: { // site-centric configuration (contextual), omit if not needed + token: "to-be-defined", // mandatory }, - weboUserDataConf: { - accountId: 12345, // recommended to use the site-centric profile + weboUserDataConf: { // user-centric configuration (wam), omit if not needed + accountId: 12345, // recommended, } } }] } }); }); - ``` -More complete configuration -``` +More Complete Configuration: + +```javascript var pbjs = pbjs || {}; pbjs.que = pbjs.que || []; pbjs.que.push(function () { pbjs.setConfig({ - debug: true, + debug: true, // to be possible log on console, perhaps should be disable in production realTimeData: { auctionDelay: 1000, dataProviders: [{ @@ -74,9 +74,8 @@ pbjs.que.push(function () { params: { setPrebidTargeting: true, // optional sendToBidders: true, // optional - onData: function(data, site){ // optional - var kind = (site)? 'site' : 'user'; - console.log('onData', kind, data); + onData: function(data, meta){ // optional + console.log('onData', data, meta); }, weboCtxConf: { token: "to-be-defined", // mandatory @@ -90,10 +89,10 @@ pbjs.que.push(function () { //, onData: function (data, ...) { ...} }, weboUserDataConf: { - accountId: 12345, // optional, used for logging - setPrebidTargeting: true, // override param.setPrebidTargeting or default true - sendToBidders: true, // override param.sendToBidders or default true - defaultProfile: { // optional + accountId: 12345, // recommended, used for logging + setPrebidTargeting: true, // override param.setPrebidTargeting or default true + sendToBidders: ['foo',...], // alternative syntax to specify some bidders + defaultProfile: { // optional webo_cs: ['Red'], webo_audiences: ['bam'] }, @@ -115,10 +114,10 @@ pbjs.que.push(function () { | waitForIt | Boolean | Mandatory. Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true | | params | Object | | Optional | | params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | -| params.sendToBidders | Boolean | If true, may send the profile to all bidders | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | -| params.onData | Callback | If set, will receive the profile and site flag | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | +| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | | params.weboCtxConf | Object | Weborama Contextual Configuration | Optional | params.weboUserDataConf | Object | Weborama User-Centric Configuration | Optional | +| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | #### Contextual Configuration @@ -127,22 +126,94 @@ pbjs.que.push(function () { | token | String | Security Token provided by Weborama, unique per client | Mandatory | | targetURL | String | Url to be profiled in the contextual api | Optional. Defaults to `document.URL` | | setPrebidTargeting|Boolean|If true, will use the contextual profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or **true**.| -| sendToBidders|Boolean|If true, will send the contextual profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or **true**.| +| sendToBidders|Boolean or Array|If true, will send the contextual profile to all bidders. If an array, will specify the bidders to send data| Optional. Default is `params.sendToBidders` (if any) or **true**.| | defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | -| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | -| enabled | Boolean| if false, will ignore this configuration| default true| +| onData | Callback | If set, will receive the profile and metadata | Optional. Default is `params.onData` (if any) or log via prebid debug | +| enabled | Boolean| if false, will ignore this configuration| default true if this section is present| #### User-Centric Configuration | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | -| accountId|Number|WAM account id. If present, will be used on logging and statistics| Optional.| +| accountId|Number|WAM account id. If present, will be used on logging and statistics| Recommended.| | setPrebidTargeting|Boolean|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or **true**.| -| sendToBidders|Boolean|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or **true**.| +| sendToBidders|Boolean or Array|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or **true**.| +| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | | defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | | localStorageProfileKey| String | can be used to customize the local storage key | Optional | -| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | -| enabled | Boolean| if false, will ignore this configuration| default true| +| enabled | Boolean| if false, will ignore this configuration| default true if this section is present| + +##### Using onData callback + +We can specify a callback to handle the profile data from site-centric or user-centric data. + +This callback will be executed with the profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual` or `wam` | + +The metadata maybe not useful if we define the callback on site-centric of user-centric configuration, but if defined in the global level: + +```javascript +params: { + onData: function(data, metadata){ + var hasUserCentricData = metadata.user; + var dataSource = metadata.source; + console.log('onData', data, hasUserCentricData, dataSource); + }, + } +} +``` + +an interesting example is to set GAM targeting in global level instead in slot level only for contextual data: + +```javascript +params: { + weboCtxConf: { + token: 'to-be-defined', + setPrebidTargeting: false, + onData: function(data, metadata){ + var googletag = googletag || {}; + googletag.cmd = googletag.cmd || []; + googletag.cmd.push(function () { + for(var key in data){ + googletag.pubads().setTargeting(key, data[key]); + } + }); + }, + } +} +``` + +##### Specify Bidders to Share Data + +It is possible specify some bidders to share data by set an array on the configuration `sendToBidders`. In case of using bid _aliases_, we should match the same string used in the adUnit configuration. + +```javascript +pbjs.aliasBidder('appnexus', 'foo'); +pbjs.aliasBidder('criteo', 'bar'); +pbjs.aliasBidder('pubmatic', 'baz'); +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "to-be-defined", // mandatory + sendToBidders: ['foo','bar'], // will share site-centric data with bidders foo and bar + }, + weboUserDataConf: { + accountId: 12345, // recommended, + sendToBidders: ['baz'], // will share user-centric data with only bidder baz + } + } + }] + } +}); +``` ### Supported Bidders From 67e645077a90a42e1092efe3daad9f2eecbbbfe4 Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Thu, 3 Feb 2022 17:12:58 +0100 Subject: [PATCH 2/5] update docs --- dev-docs/modules/weboramaRtdProvider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index f7b41d862e..292a007477 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -223,7 +223,7 @@ We currently support the following bidder adapters: * AppNexus SSP * Rubicon SSP -We also set the bidder and global ortb2 `site` and `user` sections. The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from here: https://docs.prebid.org/dev-docs/bidders +We also set the bidder (and global, if no specific bidders are set on `sendToBidders`) ortb2 `site.ext.data` and `user.ext.data` sections (as arbitrary data). The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from here: https://docs.prebid.org/dev-docs/bidders * Adagio * AdformOpenRTB From 7fbf1a396c2f2a31a751e42e0a23f6f527f74b48 Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Fri, 29 Apr 2022 22:37:02 +0200 Subject: [PATCH 3/5] update doc --- dev-docs/modules/weboramaRtdProvider.md | 353 +++++++++++++++--------- 1 file changed, 230 insertions(+), 123 deletions(-) diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index 292a007477..275a7a9276 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -17,9 +17,15 @@ sidebarType : 1 * TOC {:toc} -Weborama provides a Semantic AI Contextual API that classifies in Real-time a web page seen by a web user within generic and custom topics. It enables publishers to better monetize their inventory and unlock it to programmatic. +## Description -Contact prebid-support@weborama.com for information. +Weborama provides a Real-Time Data Submodule for `Prebid.js`, allowing to easy integrate different products such as: + +* Semantic AI Contextual API that classifies in Real-time a web page seen by a web user within generic and custom topics. It enables publishers to better monetize their inventory and unlock it to programmatic. + +* Weborama Audience Manager (WAM) is a DMP (Data Management Platform) used by over 60 companies in the world. This platform distinguishes itself particularly by a high level interconnexion with the adtech & martech ecosystem and a transparent access to the database intelligence. + +Contact prebid-support@weborama.com for more information. ### Publisher Usage @@ -27,9 +33,7 @@ Compile the Weborama RTD module into your Prebid build: `gulp build --modules=rtdModule,weboramaRtdProvider` -Add the Weborama RTD provider to your Prebid config. - -Minimal Configuration: +Add the Weborama RTD provider to your Prebid config, use the configuration template below: ```javascript var pbjs = pbjs || {}; @@ -37,77 +41,58 @@ pbjs.que = pbjs.que || []; pbjs.que.push(function () { pbjs.setConfig({ - debug: true, // to be possible log on console, perhaps should be disable in production + debug: true, // Output debug messages to the web console, *should* be disabled in production realTimeData: { auctionDelay: 1000, dataProviders: [{ name: "weborama", waitForIt: true, params: { - weboCtxConf: { // site-centric configuration (contextual), omit if not needed - token: "to-be-defined", // mandatory - }, - weboUserDataConf: { // user-centric configuration (wam), omit if not needed - accountId: 12345, // recommended, - } - } - }] + /* add weborama rtd submodule configuration here */ + }, + }, + // other modules... + ] } }); }); ``` -More Complete Configuration: +The module configuration has 3 independent sections (`weboCtxConf` and `weboUserDataConf`), each one mapped to a single product (`contextual` and `wam`). No section is enabled by default, we must be explicit like in the minimal example below: ```javascript -var pbjs = pbjs || {}; -pbjs.que = pbjs.que || []; - -pbjs.que.push(function () { - pbjs.setConfig({ - debug: true, // to be possible log on console, perhaps should be disable in production - realTimeData: { - auctionDelay: 1000, - dataProviders: [{ - name: "weborama", - waitForIt: true, - params: { - setPrebidTargeting: true, // optional - sendToBidders: true, // optional - onData: function(data, meta){ // optional - console.log('onData', data, meta); - }, - weboCtxConf: { - token: "to-be-defined", // mandatory - targetURL: "https://prebid.org", // default is document.URL - setPrebidTargeting: true, // override param.setPrebidTargeting or default true - sendToBidders: true, // override param.sendToBidders or default true - defaultProfile: { // optional - webo_ctx: ['moon'], - webo_ds: ['bar'] - } - //, onData: function (data, ...) { ...} - }, - weboUserDataConf: { - accountId: 12345, // recommended, used for logging - setPrebidTargeting: true, // override param.setPrebidTargeting or default true - sendToBidders: ['foo',...], // alternative syntax to specify some bidders - defaultProfile: { // optional - webo_cs: ['Red'], - webo_audiences: ['bam'] - }, - localStorageProfileKey: 'webo_wam2gam_entry' // default - //, onData: function (data, ...) { ...} - } - } - }] - } - }); +pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { // contextual site-centric configuration, *omit if not needed* + token: "<>", // mandatory + }, + weboUserDataConf: { // wam user-centric configuration, *omit if not needed* + enabled: true, + }, + } + }, + // other modules... + ] + } }); ``` +Each module can perform two actions: + +* set targeting on [GPT](https://docs.prebid.org/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) / [AST](https://docs.prebid.org/dev-docs/publisher-api-reference/setTargetingForAst.html]) via `prebid.js` + +* send data to other `prebid.js` bidder modules (check the complete list at the end of this page) + ### Parameter Descriptions for the Weborama Configuration Section +This is the main configuration section + | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | | name | String | Real time data module name | Mandatory. Always 'Weborama' | @@ -115,115 +100,237 @@ pbjs.que.push(function () { | params | Object | | Optional | | params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | | params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | -| params.weboCtxConf | Object | Weborama Contextual Configuration | Optional -| params.weboUserDataConf | Object | Weborama User-Centric Configuration | Optional | +| params.weboCtxConf | Object | Weborama Contextual Site-Centric Configuration | Optional | +| params.weboUserDataConf | Object | Weborama WAM User-Centric Configuration | Optional | | params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | -#### Contextual Configuration +#### Contextual Site-Centric Configuration + +To be possible use the integration with Weborama Contextual Service you must be a client with a valid API token. Please contact weborama if you don't have it. + +On this section we will explain the `params.weboCtxConf` subconfiguration: | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | | token | String | Security Token provided by Weborama, unique per client | Mandatory | | targetURL | String | Url to be profiled in the contextual api | Optional. Defaults to `document.URL` | -| setPrebidTargeting|Boolean|If true, will use the contextual profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or **true**.| -| sendToBidders|Boolean or Array|If true, will send the contextual profile to all bidders. If an array, will specify the bidders to send data| Optional. Default is `params.sendToBidders` (if any) or **true**.| +| setPrebidTargeting|Various|If true, will use the contextual profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Various|If true, will send the contextual profile to all bidders. If an array, will specify the bidders to send data| Optional. Default is `params.sendToBidders` (if any) or `true`.| | defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | | onData | Callback | If set, will receive the profile and metadata | Optional. Default is `params.onData` (if any) or log via prebid debug | -| enabled | Boolean| if false, will ignore this configuration| default true if this section is present| +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| +| baseURLProfileAPI | String| if present, update the domain of the contextual api| Optional. Default is `ctx.weborama.com` | -#### User-Centric Configuration +#### WAM User-Centric Configuration + +To be possible use the integration with Weborama Audience Manager (WAM) you must be a client with an account id and you lust include the `wamfactory` script in your pages with `wam2gam` feature activated. +Please contact weborama if you don't have it. + +On this section we will explain the `params.weboUserDataConf` subconfiguration: | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | -| accountId|Number|WAM account id. If present, will be used on logging and statistics| Recommended.| -| setPrebidTargeting|Boolean|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or **true**.| -| sendToBidders|Boolean or Array|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or **true**.| +| accountId|Number|WAM account id. If you don't have it, please contact weborama. | Recommended.| +| setPrebidTargeting|Various|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Various|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or `true`.| | onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | | defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | -| localStorageProfileKey| String | can be used to customize the local storage key | Optional | -| enabled | Boolean| if false, will ignore this configuration| default true if this section is present| +| localStorageProfileKey| String | can be used to customize the local storage key | Optional | +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| -##### Using onData callback +### More configuration examples -We can specify a callback to handle the profile data from site-centric or user-centric data. +A more complete example can be found below. We can define default profiles, for each section, to be used in case of no data are found. -This callback will be executed with the profile and a metadata with the following fields +We can control if we will set prebid targeting or send data to bidders in a global level or on each section (`contextual` or `wam`). -| Name |Type | Description | Notes | -| :------------ | :------------ | :------------ |:------------ | -| user | Boolean | If true, it contains user-centric data | | -| source | String | Represent the source of data | can be `contextual` or `wam` | +By default we try to send the data to all destinations, always. To restrict we can have two choices: -The metadata maybe not useful if we define the callback on site-centric of user-centric configuration, but if defined in the global level: +* Set `setPrebidTargeting` or `sendToBidders` explicity to `true` or `false` on each section; +* Set `setPrebidTargeting` or `sendToBidders` globally to `false` and only enable on the right sections; ```javascript -params: { - onData: function(data, metadata){ - var hasUserCentricData = metadata.user; - var dataSource = metadata.source; - console.log('onData', data, hasUserCentricData, dataSource); - }, - } -} +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "<>", // mandatory + targetURL: "https://example.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + webo_ctx: [ ... ], // contextual segments + webo_ds: [ ...], // data science segments + }, + enabled: true, + }, + weboUserDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + webo_cs: [...], // wam custom segments + webo_audiences: [...], // wam audiences + }, + enabled: true, + }, + } + }] + } + }); +}); ``` -an interesting example is to set GAM targeting in global level instead in slot level only for contextual data: +Imagine we need to configure the following options using the previous example, we can write the configuration like the one below. + +||contextual|wam| +| :------------ | :------------ | :------------ | +|setPrebidTargeting|true|false| +|sendToBidders|false|true| ```javascript -params: { - weboCtxConf: { - token: 'to-be-defined', - setPrebidTargeting: false, - onData: function(data, metadata){ - var googletag = googletag || {}; - googletag.cmd = googletag.cmd || []; - googletag.cmd.push(function () { - for(var key in data){ - googletag.pubads().setTargeting(key, data[key]); +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + setPrebidTargeting: false, // optional. set the default value of each section. + sendToBidders: false, // optional. set the default value of each section. + weboCtxConf: { + token: "<>", // mandatory + targetURL: "https://example.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + enabled: true, + }, + weboUserDataConf: { + sendToBidders: true, // override param.sendToBidders. default is true + enabled: true, + }, } - }); - }, - } -} + }] + } + }); +}); ``` -##### Specify Bidders to Share Data +We can also define a list of adunits / bidders that will receive data instead of using boolean values. + +```javascript +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "to-be-defined", // mandatory + setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits + sendToBidders: ['appnexus',...], // overide, send to only some bidders + enabled: true, + }, + weboUserDataConf: { + accountId: 12345, // recommended + setPrebidTargeting: ['adUnitCode2',...], // set target only on certain adunits + sendToBidders: ['rubicon',...], // overide, send to only some bidders + enabled: true, + }, + } + }] + } + }); +}); +``` -It is possible specify some bidders to share data by set an array on the configuration `sendToBidders`. In case of using bid _aliases_, we should match the same string used in the adUnit configuration. +Finally, we can combine several styles in the same configuration if needed. Including the callback style. ```javascript -pbjs.aliasBidder('appnexus', 'foo'); -pbjs.aliasBidder('criteo', 'bar'); -pbjs.aliasBidder('pubmatic', 'baz'); -pbjs.setConfig({ - realTimeData: { - dataProviders: [{ - name: "weborama", - waitForIt: true, - params: { - weboCtxConf: { - token: "to-be-defined", // mandatory - sendToBidders: ['foo','bar'], // will share site-centric data with bidders foo and bar - }, - weboUserDataConf: { - accountId: 12345, // recommended, - sendToBidders: ['baz'], // will share user-centric data with only bidder baz +var pbjs = pbjs || {}; +pbjs.que = pbjs.que || []; + +pbjs.que.push(function () { + pbjs.setConfig({ + debug: true, + realTimeData: { + auctionDelay: 1000, + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + setPrebidTargeting: true, // optional + sendToBidders: true, // optional + onData: function(data, meta){ // optional + var userCentricData = meta.user; // maybe undefined + var sourceOfData = meta.source; // contextual or wam + var isDefault = meta.isDefault; // true if using default profile + + console.log('onData', data, meta); + }, + weboCtxConf: { + token: "to-be-defined", // mandatory + targetURL: "https://prebid.org", // default is document.URL + setPrebidTargeting: true, // override param.setPrebidTargeting or default true + sendToBidders: ['appnexus',...], // overide, send to only some bidders + defaultProfile: { // optional + webo_ctx: ['moon'], + webo_ds: ['bar'] + }, + enabled: true, + //, onData: function (data, ...) { ...} + }, + weboUserDataConf: { + accountId: 12345, // recommended + setPrebidTargeting: ['adUnitCode1',...], // set target only on certain adunits + sendToBidders: { // send to only some bidders and adunits + 'appnexus': true, // all adunits for appnexus + 'pubmatic': ['adUnitCode1',...] // some adunits for pubmatic + // other bidders will be ignored + }, + defaultProfile: { // optional + webo_cs: ['Red'], + webo_audiences: ['bam'] + }, + localStorageProfileKey: 'webo_wam2gam_entry', // default + enabled: true, + //, onData: function (data, ...) { ...} + }, } - } - }] - } + }] + } + }); }); ``` ### Supported Bidders We currently support the following bidder adapters: + * SmartADServer SSP * PubMatic SSP * AppNexus SSP * Rubicon SSP -We also set the bidder (and global, if no specific bidders are set on `sendToBidders`) ortb2 `site.ext.data` and `user.ext.data` sections (as arbitrary data). The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from here: https://docs.prebid.org/dev-docs/bidders +We also set the bidder (and global, if no specific bidders are set on `sendToBidders`) ortb2 `site.ext.data` and `user.ext.data` sections (as arbitrary data). The following bidders may support it, to be sure, check the `First Party Data Support` on the feature list for the particular bidder from [here](https://docs.prebid.org/dev-docs/bidders). * Adagio * AdformOpenRTB From b1b524346c3a2c637c5bcde1fbbf99021b24bfcb Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Thu, 5 May 2022 22:00:19 +0200 Subject: [PATCH 4/5] add mentions to sfbx-lite --- dev-docs/modules/weboramaRtdProvider.md | 253 ++++++++++++++++++++++-- 1 file changed, 242 insertions(+), 11 deletions(-) diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index 275a7a9276..596388ccaa 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -25,6 +25,8 @@ Weborama provides a Real-Time Data Submodule for `Prebid.js`, allowing to easy i * Weborama Audience Manager (WAM) is a DMP (Data Management Platform) used by over 60 companies in the world. This platform distinguishes itself particularly by a high level interconnexion with the adtech & martech ecosystem and a transparent access to the database intelligence. +* LiTE by SFBX® (Local inApp Trust Engine) provides “Zero Party Data” given by users, stored and calculated only on the user’s device. Through a unique cohorting system, it enables better monetization in a consent/consentless and identity-less mode. + Contact prebid-support@weborama.com for more information. ### Publisher Usage @@ -58,7 +60,7 @@ pbjs.que.push(function () { }); ``` -The module configuration has 3 independent sections (`weboCtxConf` and `weboUserDataConf`), each one mapped to a single product (`contextual` and `wam`). No section is enabled by default, we must be explicit like in the minimal example below: +The module configuration has 3 independent sections (`weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf`), each one mapped to a single product (`contextual`, `wam` and `lite`). No section is enabled by default, we must be explicit like in the minimal example below: ```javascript pbjs.setConfig({ @@ -75,6 +77,9 @@ pbjs.setConfig({ weboUserDataConf: { // wam user-centric configuration, *omit if not needed* enabled: true, }, + weboLiteDataConf: { // webo-lite site-centric configuration, *omit if not needed* + enabled: true, + }, } }, // other modules... @@ -98,11 +103,12 @@ This is the main configuration section | name | String | Real time data module name | Mandatory. Always 'Weborama' | | waitForIt | Boolean | Mandatory. Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true | | params | Object | | Optional | -| params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | -| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | +| params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | +| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | | params.weboCtxConf | Object | Weborama Contextual Site-Centric Configuration | Optional | | params.weboUserDataConf | Object | Weborama WAM User-Centric Configuration | Optional | -| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf` and `weboUserDataConf` sections | +| params.weboLiteDataConf | Object | Weborama LiTE Site-Centric Configuration | Optional | +| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | #### Contextual Site-Centric Configuration @@ -138,11 +144,202 @@ On this section we will explain the `params.weboUserDataConf` subconfiguration: | localStorageProfileKey| String | can be used to customize the local storage key | Optional | | enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| +#### Webo LiTE Site-Centric Configuration + +To be possible use the integration between Weborama and LiTE you should also contact SFBX® to setup this product. + +On this section we will explain the `params.weboLiteDataConf` subconfiguration: + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| setPrebidTargeting|Various|If true, will use the user profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js| Optional. Default is `params.setPrebidTargeting` (if any) or `true`.| +| sendToBidders|Varios|If true, will send the user profile to all bidders| Optional. Default is `params.sendToBidders` (if any) or `true`.| +| onData | Callback | If set, will receive the profile and site flag | Optional. Default is `params.onData` (if any) or log via prebid debug | +| defaultProfile | Object | default value of the profile to be used when there are no response from contextual api (such as timeout)| Optional. Default is `{}` | +| localStorageProfileKey| String | can be used to customize the local storage key | Optional | +| enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| + +##### Property setPrebidTargeting supported types + +This property support the following types + +| Type | Description | Example | Notes | +| :------------ | :------------ | :------------ |:------------ | +| Boolean|If true, set prebid targeting for all adunits, or not in case of false| `true` | default value | +| String|Will set prebid targeting only for one adunit | `'adUnitCode1'` | | +| Array of Strings|Will set prebid targeting only for some adunits| `['adUnitCode1','adUnitCode2']` | | +| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(adUnitCode){return adUnitCode == 'adUnitCode';}` | | + +The complete callback function signature is: + +```javascript +setPrebidTargeting: function(adUnitCode, data, metadata){ + return true; // or false, depending on the logic +} +``` + +This callback will be executed with the adUnitCode, profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +It is possible customize the targeting based on the parameters: + +```javascript +setPrebidTargeting: function(adUnitCode, data, metadata){ + // check metadata.source can be omitted if defined in params.weboUserDataConf + if (adUnitCode == 'adUnitCode1' && metadata.source == 'wam'){ + data['foo']=['bar']; // add this section only for adUnitCode1 + delete data['other']; // remove this section + } + return true; +} +``` + +##### Property sendToBidders supported types + +This property support the following types + +| Type | Description | Example | Notes | +| :------------ | :------------ | :------------ |:------------ | +| Boolean|If true, send data to all bidders, or not in case of false| `true` | default value | +| String|Will send data to only one bidder | `'appnexus'` | | +| Array of Strings|Will send data to only some bidders | `['appnexus','pubmatic']` | | +| Object |Will send data to only some bidders and some ad units | `{appnexus: true, pubmatic:['adUnitCode1']}` | | +| Callback |Will be executed for each adunit, expects return a true value to set prebid targeting or not| `function(bid, adUnitCode){return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode';}` | | + +A better look on the `Object` type + +```javascript +sendToBidders: { + appnexus: true, // send profile to appnexus on all ad units + pubmatic: ['adUnitCode1'],// send profile to pubmatic on this ad units +} +``` + +The complete callback function signature is: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + return true; // or false, depending on the logic +} +``` + +This callback will be executed with the bid object (contains a field `bidder` with name), adUnitCode, profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +It is possible customize the targeting based on the parameters: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + if (bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'){ + data['foo']=['bar']; // add this section only for appnexus + adUnitCode1 + delete data['other']; // remove this section + } + return true; +} +``` + +To be possible customize the way we send data to bidders via this callback: + +```javascript +sendToBidders: function(bid, adUnitCode, data, metadata){ + if (bid.bidder == 'other'){ + /* use bid object to store data based on this specific logic, like in the example below */ + + bid.params = bid.params || {}; + bid.params['some_specific_key'] = data; + + return false; // will prevent the module to follow the pre-defined logic per bidder + } + // others + return true; +} +``` + +In case of using bid _aliases_, we should match the same string used in the adUnit configuration. + +```javascript +pbjs.aliasBidder('appnexus', 'foo'); +pbjs.aliasBidder('criteo', 'bar'); +pbjs.aliasBidder('pubmatic', 'baz'); +pbjs.setConfig({ + realTimeData: { + dataProviders: [{ + name: "weborama", + waitForIt: true, + params: { + weboCtxConf: { + token: "to-be-defined", // mandatory + sendToBidders: ['foo','bar'], // will share site-centric data with bidders foo and bar + }, + weboUserDataConf: { + accountId: 12345, // recommended, + sendToBidders: ['baz'], // will share user-centric data with only bidder baz + } + } + }] + } +}); +``` + +##### Using onData callback + +We can specify a callback to handle the profile data from site-centric or user-centric data. + +This callback will be executed with the profile and a metadata with the following fields + +| Name |Type | Description | Notes | +| :------------ | :------------ | :------------ |:------------ | +| user | Boolean | If true, it contains user-centric data | | +| source | String | Represent the source of data | can be `contextual`, `wam` or `lite` | +| isDefault | Boolean | If true, it contains the default profile defined in the configuration | | + +The metadata maybe not useful if we define the callback on site-centric of user-centric configuration, but if defined in the global level: + +```javascript +params: { + onData: function(data, metadata){ + var hasUserCentricData = metadata.user; + var dataSource = metadata.source; + console.log('onData', data, hasUserCentricData, dataSource); + } +} +``` + +an interesting example is to set GAM targeting in global level instead in slot level only for contextual data: + +```javascript +params: { + weboCtxConf: { + token: 'to-be-defined', + setPrebidTargeting: false, + onData: function(data, metadata){ + var googletag = googletag || {}; + googletag.cmd = googletag.cmd || []; + googletag.cmd.push(function () { + for(var key in data){ + googletag.pubads().setTargeting(key, data[key]); + } + }); + }, + } +} +``` + ### More configuration examples A more complete example can be found below. We can define default profiles, for each section, to be used in case of no data are found. -We can control if we will set prebid targeting or send data to bidders in a global level or on each section (`contextual` or `wam`). +We can control if we will set prebid targeting or send data to bidders in a global level or on each section (`contextual`, `wam` or `lite`). By default we try to send the data to all destinations, always. To restrict we can have two choices: @@ -182,6 +379,14 @@ pbjs.que.push(function () { }, enabled: true, }, + weboLiteDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + defaultProfile: { // optional, used if nothing is found + /* add specific lite segments here */ + }, + enabled: true, + }, } }] } @@ -191,10 +396,10 @@ pbjs.que.push(function () { Imagine we need to configure the following options using the previous example, we can write the configuration like the one below. -||contextual|wam| -| :------------ | :------------ | :------------ | -|setPrebidTargeting|true|false| -|sendToBidders|false|true| +||contextual|wam|lite| +| :------------ | :------------ | :------------ |:------------ | +|setPrebidTargeting|true|false|true| +|sendToBidders|false|true|true| ```javascript var pbjs = pbjs || {}; @@ -221,6 +426,11 @@ pbjs.que.push(function () { sendToBidders: true, // override param.sendToBidders. default is true enabled: true, }, + weboLiteDataConf: { + setPrebidTargeting: true, // override param.setPrebidTargeting. default is true + sendToBidders: true, // override param.sendToBidders. default is true + enabled: true, + }, } }] } @@ -255,6 +465,11 @@ pbjs.que.push(function () { sendToBidders: ['rubicon',...], // overide, send to only some bidders enabled: true, }, + weboLiteDataConf: { + setPrebidTargeting: ['adUnitCode3',...], // set target only on certain adunits + sendToBidders: ['smartadserver',...], // overide, send to only some bidders + enabled: true, + } } }] } @@ -281,8 +496,9 @@ pbjs.que.push(function () { sendToBidders: true, // optional onData: function(data, meta){ // optional var userCentricData = meta.user; // maybe undefined - var sourceOfData = meta.source; // contextual or wam - var isDefault = meta.isDefault; // true if using default profile + var sourceOfData = meta.source; // contextual, wam or lite + + var isDefault = meta.isDefault; // true if uses default profile console.log('onData', data, meta); }, @@ -314,6 +530,21 @@ pbjs.que.push(function () { enabled: true, //, onData: function (data, ...) { ...} }, + weboLiteDataConf: { + setPrebidTargeting: function(adUnitCode){ // specify set target via callback + return adUnitCode == 'adUnitCode1'; + }, + sendToBidders: function(bid, adUnitCode){ // specify sendToBidders via callback + return bid.bidder == 'appnexus' && adUnitCode == 'adUnitCode1'; + } + defaultProfile: { // optional + lite_occupation: ['gérant', 'bénévole'], + lite_hobbies: ['sport', 'cinéma'], + }, + localStorageProfileKey: '_lite', // default + enabled: true, + //, onData: function (data, ...) { ...} + } } }] } From fe1d2909d8aed06f453331d7ba1d0ff3a6d23314 Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Fri, 13 May 2022 17:01:11 +0200 Subject: [PATCH 5/5] update docs --- dev-docs/modules/weboramaRtdProvider.md | 26 ++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/dev-docs/modules/weboramaRtdProvider.md b/dev-docs/modules/weboramaRtdProvider.md index 596388ccaa..ec9752ac35 100644 --- a/dev-docs/modules/weboramaRtdProvider.md +++ b/dev-docs/modules/weboramaRtdProvider.md @@ -60,7 +60,7 @@ pbjs.que.push(function () { }); ``` -The module configuration has 3 independent sections (`weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf`), each one mapped to a single product (`contextual`, `wam` and `lite`). No section is enabled by default, we must be explicit like in the minimal example below: +The module configuration has 3 independent sections (`weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf`), each one mapped to a single product (`contextual`, `wam` and `lite`). No section is enabled by default, we must be explicit like in the minimal example below: ```javascript pbjs.setConfig({ @@ -77,7 +77,7 @@ pbjs.setConfig({ weboUserDataConf: { // wam user-centric configuration, *omit if not needed* enabled: true, }, - weboLiteDataConf: { // webo-lite site-centric configuration, *omit if not needed* + sfbxLiteDataConf: { // sfbx-lite site-centric configuration, *omit if not needed* enabled: true, }, } @@ -103,12 +103,12 @@ This is the main configuration section | name | String | Real time data module name | Mandatory. Always 'Weborama' | | waitForIt | Boolean | Mandatory. Required to ensure that the auction is delayed until prefetch is complete | Optional. Defaults to false but recommended to true | | params | Object | | Optional | -| params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | -| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | +| params.setPrebidTargeting | Boolean | If true, may use the profile to set the prebid (GPT/GAM or AST) targeting of all adunits managed by prebid.js | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | +| params.sendToBidders | Boolean or Array | If true, may send the profile to all bidders. If an array, will specify the bidders to send data | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | | params.weboCtxConf | Object | Weborama Contextual Site-Centric Configuration | Optional | | params.weboUserDataConf | Object | Weborama WAM User-Centric Configuration | Optional | -| params.weboLiteDataConf | Object | Weborama LiTE Site-Centric Configuration | Optional | -| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `weboLiteDataConf` sections | +| params.sfbxLiteDataConf | Object | Sfbx LiTE Site-Centric Configuration | Optional | +| params.onData | Callback | If set, will receive the profile and metadata | Optional. Affects the `weboCtxConf`, `weboUserDataConf` and `sfbxLiteDataConf` sections | #### Contextual Site-Centric Configuration @@ -144,11 +144,11 @@ On this section we will explain the `params.weboUserDataConf` subconfiguration: | localStorageProfileKey| String | can be used to customize the local storage key | Optional | | enabled | Boolean| if false, will ignore this configuration| Default is `true` if this section is present| -#### Webo LiTE Site-Centric Configuration +#### Sfbx LiTE Site-Centric Configuration -To be possible use the integration between Weborama and LiTE you should also contact SFBX® to setup this product. +To be possible use the integration between Weborama and Sfbx LiTE you should also contact SFBX® to setup this product. -On this section we will explain the `params.weboLiteDataConf` subconfiguration: +On this section we will explain the `params.sfbxLiteDataConf` subconfiguration: | Name |Type | Description | Notes | | :------------ | :------------ | :------------ |:------------ | @@ -379,7 +379,7 @@ pbjs.que.push(function () { }, enabled: true, }, - weboLiteDataConf: { + sfbxLiteDataConf: { setPrebidTargeting: true, // override param.setPrebidTargeting. default is true sendToBidders: true, // override param.sendToBidders. default is true defaultProfile: { // optional, used if nothing is found @@ -426,7 +426,7 @@ pbjs.que.push(function () { sendToBidders: true, // override param.sendToBidders. default is true enabled: true, }, - weboLiteDataConf: { + sfbxLiteDataConf: { setPrebidTargeting: true, // override param.setPrebidTargeting. default is true sendToBidders: true, // override param.sendToBidders. default is true enabled: true, @@ -465,7 +465,7 @@ pbjs.que.push(function () { sendToBidders: ['rubicon',...], // overide, send to only some bidders enabled: true, }, - weboLiteDataConf: { + sfbxLiteDataConf: { setPrebidTargeting: ['adUnitCode3',...], // set target only on certain adunits sendToBidders: ['smartadserver',...], // overide, send to only some bidders enabled: true, @@ -530,7 +530,7 @@ pbjs.que.push(function () { enabled: true, //, onData: function (data, ...) { ...} }, - weboLiteDataConf: { + sfbxLiteDataConf: { setPrebidTargeting: function(adUnitCode){ // specify set target via callback return adUnitCode == 'adUnitCode1'; },