add bidder schain docs

dev-docs/modules/schain.md

@@ -10,17 +10,33 @@ 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}
 
-## How to use the module:
+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:
+
+- **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.
+
+- **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
 
 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 performs validations on the schain data provided and makes it available to bidder adapters on the bidRequest object.
+
+### Global Supply Chains
+
+Call `setConfig` with the `schain` object to be used:
 
 {% highlight js %}
 pbjs.setConfig({
@@ -41,19 +57,53 @@ pbjs.setConfig({
 });
 {% endhighlight %}
 
-### 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.
+### Bidder-Specific Supply Chains
+
+This method uses the `pbjs.setBidderConfig` function, with a syntax similar to the global scenario above.
+
+{% highlight js %}
+pbjs.setBidderConfig({
+  "bidders": ['bidderA'],   // can list more bidders here if they share the same config
+  "config": {
+    "schain": {
+      "validation": "relaxed",
+      "config": {
+        "ver":"1.0",
+        "complete": 1,
+        "nodes": [
+          {
+            "asi":"bidderA.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).
 
-### Supply Chain Object
+### Global and Bidder-Specific Together
 
-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)
+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).
 
-## Adapters Supporting the Schain Module
+## SChain Config Syntax
 
-{% assign bidder_pages = site.pages | where: "layout", "bidder" %}
+{: .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 OpenRTB SupplyChain Object Specification](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md). | (See examples above) |
 
+## 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 Supporting the schain Module
+
+{% assign bidder_pages = site.pages | where: "layout", "bidder" %}
 
 <div class="adapters">
 {% for page in bidder_pages %}
@@ -74,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/)  

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 currently be used by the `schain` feature. Refer to the [schain]({{site.baseurl}}/dev-docs/modules/schain.html) documentation for examples.
 
 <a name="module_pbjs.getConfig"></a>