From 372522509ba36d05b50194719ed812d066e4e906 Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Mon, 9 Dec 2019 09:59:01 -0500 Subject: [PATCH 1/4] add bidder schain docs --- dev-docs/modules/schain.md | 70 +++++++++++++++++++++++++++++ dev-docs/publisher-api-reference.md | 3 +- 2 files changed, 71 insertions(+), 2 deletions(-) diff --git a/dev-docs/modules/schain.md b/dev-docs/modules/schain.md index cf44c2d40d..5e6d32a3c4 100644 --- a/dev-docs/modules/schain.md +++ b/dev-docs/modules/schain.md @@ -41,6 +41,76 @@ pbjs.setConfig({ }); {% endhighlight %} +Another way to setup the schain object can be done through the `pbjs.setBidderConfig` function. This method would allow you to specify unique schain configs for indiviual bidders; this can be helpful if you have a different relationship with certain bidders and need to represent the schain information differently than normal. + +You can opt to use the `pbjs.setBidderConfig` function in conjunction with the `pbjs.setConfig` function. When together, the schain config setup via the `pbjs.setConfig` acts as a global config that applies to all your bidders, while the `pbjs.setBidderConfig` overrides the global config for the noted bidder(s). + +Below is an example of how this would look: +{% highlight js %} +pbjs.setConfig({ + "schain": { + "validation": "strict", + "config": { + "ver":"1.0", + "complete": 1, + "nodes": [ + { + "asi":"indirectseller.com", + "sid":"00001", + "hp":1 + } + ] + } + } +}); + +pbjs.setBidderConfig({ + bidders: ['rubicon'], // can list more bidders here if they share the same config (eg if they had an alias you were using) + config: { + schain: { + "validation": "relaxed", + "config": { + "ver":"1.0", + "complete": 1, + "nodes": [ + { + "asi":"myoverride1.com", + "sid":"00001", + "hp":1 + }, { + "asi":"myoverride2.com", + "sid":"00002", + "hp":1 + } + ] + } + } + } +}); + +pbjs.setBidderConfig({ + bidders: ['appnexus'], + config: { + schain: { + "validation": "off", + "config": { + "ver":"1.0", + "complete": 1, + "nodes": [ + { + "asi":"myothersite.com", + "sid":"00001", + "hp":1 + } + ] + } + } + } +}); +{% endhighlight%} + +You can find more information about the `pbjs.setBidderConfig` function in the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setBidderConfig). + ### Validation modes - `strict`: It is the default validation mode. In this mode, schain object will not be passed to adapters if it is invalid. Errors are thrown for invalid schain object. - `relaxed`: In this mode, errors are thrown for an invalid schain object but the invalid schain object is still passed to adapters. diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 97c0f7edd8..f2a6823496 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -2227,8 +2227,7 @@ When 'bidderA' calls `getConfig('bidderA')`, it will receive the object that con If any other bidder calls `getConfig('bidderA')`, it will receive nothing. {: .alert.alert-info :} -The `setBidderConfig` function will soon be used by the `schain` and -`first party data` features. +While the `setBidderConfig` function will soon be used by the `first party data` feature, it can be used by the `schain` feature; refer to the [schain]({{site.baseurl}}/dev-docs/modules/schain.html) documentation for some examples. From 9fc0b3e7700582da79fab24f0d2445196145e5fc Mon Sep 17 00:00:00 2001 From: Jason Snellbaker Date: Mon, 9 Dec 2019 10:06:54 -0500 Subject: [PATCH 2/4] fix formatting in examples --- dev-docs/modules/schain.md | 64 +++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/dev-docs/modules/schain.md b/dev-docs/modules/schain.md index 5e6d32a3c4..1d9e555a60 100644 --- a/dev-docs/modules/schain.md +++ b/dev-docs/modules/schain.md @@ -65,45 +65,45 @@ pbjs.setConfig({ }); pbjs.setBidderConfig({ - bidders: ['rubicon'], // can list more bidders here if they share the same config (eg if they had an alias you were using) - config: { - schain: { + "bidders": ['rubicon'], // can list more bidders here if they share the same config + "config": { + "schain": { "validation": "relaxed", - "config": { - "ver":"1.0", - "complete": 1, - "nodes": [ - { - "asi":"myoverride1.com", - "sid":"00001", - "hp":1 - }, { - "asi":"myoverride2.com", - "sid":"00002", - "hp":1 - } - ] - } + "config": { + "ver":"1.0", + "complete": 1, + "nodes": [ + { + "asi":"myoverride1.com", + "sid":"00001", + "hp":1 + }, { + "asi":"myoverride2.com", + "sid":"00002", + "hp":1 + } + ] + } } } }); pbjs.setBidderConfig({ - bidders: ['appnexus'], - config: { - schain: { + "bidders": ['appnexus'], + "config": { + "schain": { "validation": "off", - "config": { - "ver":"1.0", - "complete": 1, - "nodes": [ - { - "asi":"myothersite.com", - "sid":"00001", - "hp":1 - } - ] - } + "config": { + "ver":"1.0", + "complete": 1, + "nodes": [ + { + "asi":"myothersite.com", + "sid":"00001", + "hp":1 + } + ] + } } } }); From 8578405b9e1adaf6606807a191f5118292cb8e02 Mon Sep 17 00:00:00 2001 From: Bret Gorsline Date: Mon, 9 Dec 2019 19:30:55 -0500 Subject: [PATCH 3/4] wordsmithing the global/bidder-specific scenarios --- dev-docs/modules/schain.md | 90 +++++++++++++++----------------------- 1 file changed, 35 insertions(+), 55 deletions(-) diff --git a/dev-docs/modules/schain.md b/dev-docs/modules/schain.md index 1d9e555a60..56f48924a1 100644 --- a/dev-docs/modules/schain.md +++ b/dev-docs/modules/schain.md @@ -10,8 +10,18 @@ sidebarType : 1 --- # Supply Chain Object Module +{:.no_toc} -Aggregators who manage Prebid wrappers on behalf of multiple publishers and handle payment on behalf of the publishers need to declare their intermediary status in the Supply Chain Object. As the Supply Chain Object spec prohibits SSPs from adding upstream intermediaries, Prebid requests in this case need to come with the `schain` information. +* TOC +{:toc} + +Service Providers who manage Prebid wrappers on behalf of multiple publishers and handle payments to the publishers need to declare their intermediary status in the Supply Chain (aka `SChain`) object. As the [IAB's Supply Chain Object spec](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) prohibits SSPs from adding upstream intermediaries, publishers or Prebid.js managed service providers need to specify `schain` information. + +Two modes are supported: + +1) Global SChain - use this configuration when the Prebid.js implementation is managed by an entity who needs to add an SChain node to every bid request. i.e. payments flow through this entity for all traffic. + +2) Bidder-Specific SChain - use this config when one or more bid adapters is an entity (e.g. a reseller) that requires an SChain node, but other adapters do not require the node. e.g. payments flow through a bidder that doesn't add its own schain node. ## How to use the module: @@ -20,7 +30,12 @@ First, build the schain module into your Prebid.js package: gulp build --modules=schain,... ``` -Next, in your page, call setConfig with the schain object to be used. Example: +The module does validations on the schain data provided and makes it available to bidder adapters on the +bidRequest object. + +### Global Supply Chains + +Just call setConfig with the `schain` object to be used: {% highlight js %} pbjs.setConfig({ @@ -41,31 +56,14 @@ pbjs.setConfig({ }); {% endhighlight %} -Another way to setup the schain object can be done through the `pbjs.setBidderConfig` function. This method would allow you to specify unique schain configs for indiviual bidders; this can be helpful if you have a different relationship with certain bidders and need to represent the schain information differently than normal. +### Bidder-Specific SChain -You can opt to use the `pbjs.setBidderConfig` function in conjunction with the `pbjs.setConfig` function. When together, the schain config setup via the `pbjs.setConfig` acts as a global config that applies to all your bidders, while the `pbjs.setBidderConfig` overrides the global config for the noted bidder(s). +This method uses the `pbjs.setBidderConfig` function, with a syntax similar to the global scenario above: Below is an example of how this would look: {% highlight js %} -pbjs.setConfig({ - "schain": { - "validation": "strict", - "config": { - "ver":"1.0", - "complete": 1, - "nodes": [ - { - "asi":"indirectseller.com", - "sid":"00001", - "hp":1 - } - ] - } - } -}); - pbjs.setBidderConfig({ - "bidders": ['rubicon'], // can list more bidders here if they share the same config + "bidders": ['bidderA'], // can list more bidders here if they share the same config "config": { "schain": { "validation": "relaxed", @@ -74,31 +72,7 @@ pbjs.setBidderConfig({ "complete": 1, "nodes": [ { - "asi":"myoverride1.com", - "sid":"00001", - "hp":1 - }, { - "asi":"myoverride2.com", - "sid":"00002", - "hp":1 - } - ] - } - } - } -}); - -pbjs.setBidderConfig({ - "bidders": ['appnexus'], - "config": { - "schain": { - "validation": "off", - "config": { - "ver":"1.0", - "complete": 1, - "nodes": [ - { - "asi":"myothersite.com", + "asi":"bidderA.com", "sid":"00001", "hp":1 } @@ -111,19 +85,25 @@ pbjs.setBidderConfig({ You can find more information about the `pbjs.setBidderConfig` function in the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setBidderConfig). -### Validation modes -- `strict`: It is the default validation mode. In this mode, schain object will not be passed to adapters if it is invalid. Errors are thrown for invalid schain object. -- `relaxed`: In this mode, errors are thrown for an invalid schain object but the invalid schain object is still passed to adapters. -- `off`: In this mode, no validations are performed and schain object is passed as is to adapters. +### Both Global and Bidder-Specific -### Supply Chain Object +Yes, you can set both global and bidder-specific SChain config. When together, the schain config setup via the `pbjs.setConfig` acts as a global config that applies to all your bidders, while the `pbjs.setBidderConfig` overrides the global config for the noted bidder(s). -The `config` paramter contains a complete supply object confirming to the [IAB's OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) +## SChain Config Syntax -## Adapters Supporting the Schain Module +{: .table .table-bordered .table-striped } +| SChain Param | Scope | Type | Description | Example | +| --- | --- | --- | --- | --- | +| validation | optional | string | `'strict'`: In this mode, schain object will not be passed to adapters if it is invalid. Errors are thrown for invalid schain object. `'relaxed'`: errors are thrown for an invalid schain object but the invalid schain object is still passed to adapters. `'off'`: no validations are performed and schain object is passed as is to adapters. The default value is `'strict'`. | 'strict' | +| config | required | object | This is the full Supply Chain object sent to bidders conforming to the [IAB's OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md). | (see examples above) | -{% assign bidder_pages = site.pages | where: "layout", "bidder" %} +## Adapters Supporting the SChain Module +Adapters can read the `bidRequest.schain` object and pass it through to their endpoint. The adapter does not +need to be concerned about whether a bidder-specific schain was provided; the system will provide the +relevant one. + +{% assign bidder_pages = site.pages | where: "layout", "bidder" %}
{% for page in bidder_pages %} From 801c6d86c1799cba831baf21a86e62b4c8fbba0b Mon Sep 17 00:00:00 2001 From: Jean Stemp Date: Mon, 9 Dec 2019 17:17:33 -0800 Subject: [PATCH 4/4] minor edits --- dev-docs/modules/schain.md | 38 ++++++++++++++--------------- dev-docs/publisher-api-reference.md | 2 +- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/dev-docs/modules/schain.md b/dev-docs/modules/schain.md index 56f48924a1..8b030aeb05 100644 --- a/dev-docs/modules/schain.md +++ b/dev-docs/modules/schain.md @@ -15,27 +15,28 @@ sidebarType : 1 * TOC {:toc} -Service Providers who manage Prebid wrappers on behalf of multiple publishers and handle payments to the publishers need to declare their intermediary status in the Supply Chain (aka `SChain`) object. As the [IAB's Supply Chain Object spec](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) prohibits SSPs from adding upstream intermediaries, publishers or Prebid.js managed service providers need to specify `schain` information. +Service Providers who manage Prebid wrappers on behalf of multiple publishers and handle payments to the publishers need to declare their intermediary status in the Supply Chain (a.k.a `SChain`) object. The [IAB OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) prohibits SSPs from adding upstream intermediaries, so publishers or Prebid.js managed service providers need to specify `schain` information. Two modes are supported: -1) Global SChain - use this configuration when the Prebid.js implementation is managed by an entity who needs to add an SChain node to every bid request. i.e. payments flow through this entity for all traffic. +- **Global Supply Chains** + Use this configuration when the Prebid.js implementation is managed by an entity that needs to add an SChain node to every bid request. i.e. payments flow through this entity for all traffic. -2) Bidder-Specific SChain - use this config when one or more bid adapters is an entity (e.g. a reseller) that requires an SChain node, but other adapters do not require the node. e.g. payments flow through a bidder that doesn't add its own schain node. +- **Bidder-Specific Supply Chains** + Use this configuration when one or more bid adapters is an entity (such as a reseller) that requires an SChain node, but other adapters do not require the node. e.g. payments flow through a bidder that doesn't add its own schain node. -## How to use the module: +## How to Use the Module First, build the schain module into your Prebid.js package: ``` gulp build --modules=schain,... ``` -The module does validations on the schain data provided and makes it available to bidder adapters on the -bidRequest object. +The module performs validations on the schain data provided and makes it available to bidder adapters on the bidRequest object. ### Global Supply Chains -Just call setConfig with the `schain` object to be used: +Call `setConfig` with the `schain` object to be used: {% highlight js %} pbjs.setConfig({ @@ -56,11 +57,10 @@ pbjs.setConfig({ }); {% endhighlight %} -### Bidder-Specific SChain +### Bidder-Specific Supply Chains -This method uses the `pbjs.setBidderConfig` function, with a syntax similar to the global scenario above: +This method uses the `pbjs.setBidderConfig` function, with a syntax similar to the global scenario above. -Below is an example of how this would look: {% highlight js %} pbjs.setBidderConfig({ "bidders": ['bidderA'], // can list more bidders here if they share the same config @@ -85,23 +85,23 @@ pbjs.setBidderConfig({ You can find more information about the `pbjs.setBidderConfig` function in the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setBidderConfig). -### Both Global and Bidder-Specific +### Global and Bidder-Specific Together -Yes, you can set both global and bidder-specific SChain config. When together, the schain config setup via the `pbjs.setConfig` acts as a global config that applies to all your bidders, while the `pbjs.setBidderConfig` overrides the global config for the noted bidder(s). +Yes, you can set both global and bidder-specific SChain configs. When together, the schain config setup via `pbjs.setConfig` acts as a global config that applies to all your bidders, while `pbjs.setBidderConfig` overrides the global config for the noted bidder(s). ## SChain Config Syntax {: .table .table-bordered .table-striped } | SChain Param | Scope | Type | Description | Example | | --- | --- | --- | --- | --- | -| validation | optional | string | `'strict'`: In this mode, schain object will not be passed to adapters if it is invalid. Errors are thrown for invalid schain object. `'relaxed'`: errors are thrown for an invalid schain object but the invalid schain object is still passed to adapters. `'off'`: no validations are performed and schain object is passed as is to adapters. The default value is `'strict'`. | 'strict' | -| config | required | object | This is the full Supply Chain object sent to bidders conforming to the [IAB's OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md). | (see examples above) | +| validation | optional | string | `'strict'`: In this mode, schain object will not be passed to adapters if it is invalid. Errors are thrown for invalid schain object. `'relaxed'`: Errors are thrown for an invalid schain object but the invalid schain object is still passed to adapters. `'off'`: No validations are performed and schain object is passed as-is to adapters. The default value is `'strict'`. | 'strict' | +| config | required | object | This is the full Supply Chain object sent to bidders conforming to the [IAB OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md). | (See examples above) | -## Adapters Supporting the SChain Module +## Adapter Information -Adapters can read the `bidRequest.schain` object and pass it through to their endpoint. The adapter does not -need to be concerned about whether a bidder-specific schain was provided; the system will provide the -relevant one. +Adapters can read the `bidRequest.schain` object and pass it through to their endpoint. The adapter does not need to be concerned about whether a bidder-specific schain was provided; the system will provide the relevant one. + +## Adapters Supporting the schain Module {% assign bidder_pages = site.pages | where: "layout", "bidder" %} @@ -124,5 +124,5 @@ $(function(){ ## Further Reading -- [IAB's OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) +- [IAB OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) - [Sellers.json Specification](https://iabtechlab.com/sellers-json/) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index f2a6823496..0981fcaa7a 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -2227,7 +2227,7 @@ When 'bidderA' calls `getConfig('bidderA')`, it will receive the object that con If any other bidder calls `getConfig('bidderA')`, it will receive nothing. {: .alert.alert-info :} -While the `setBidderConfig` function will soon be used by the `first party data` feature, it can be used by the `schain` feature; refer to the [schain]({{site.baseurl}}/dev-docs/modules/schain.html) documentation for some examples. +While the `setBidderConfig` function will soon be used by the `first party data` feature, it can currently be used by the `schain` feature. Refer to the [schain]({{site.baseurl}}/dev-docs/modules/schain.html) documentation for examples.