This document describes the standard way to communicate Supply Chain information via a tag rather than OpenRTB. You most commonly need to do this when an advertising system provides a tag to be inserted into an ad server, video player, SSAI vendor, and so on, to initiate an ad request.
Goals of the serialization
- Support all properties of Supply Chain object.
- Minimize the need to serialize URL encoding.
- Maintain compatibility for future Supply Chain versions.
This appendix outlines a methodology defining well-structured key-value pair Supply Chain data.
A target advertising system handling a tag-based request and forming an outbound OpenRTB request to another advertising system should initiate the following procedure:
- Parse the incoming Supply Chain data as described below.
- Create and fill the Supply Chain object with the incoming data.
- Append target advertising system's own information to the array in the Supply Chain object
Advertising system receives Supply Chain via tags or URLs
The target system should support a parameter in its ad tags or VAST URLs to accept a Supply Chain serialized string. The best practice is to name this parameter,
sChain. For example, an ad server may have a display ad tag format like:
<script src="sChain=[SUPPLYCHAIN GOES HERE]"></script>
Or a VAST URL format like:
OpenRTB Supply Chain object serialization within a URL parameter
The best practice is to use the parameter name,
Serialization is composed of the
SChainObject properties and the
SChainNode array, separated by a bang ( ! ) character, like so:
SChainObject contains two properties:
ver (version) and
complete. Separate the two values with a comma ( , ), and they must come at the beginning of the serialized value:
Array of SChainNode properties
SChainObject properties, the serialized values must include every node in
SChainNode object properties using commas ( , ) and separate multiple nodes bang ( ! ) characters. Order properties like so:
ext property content is exchange-specific, so is beyond the scope of this document. Consult developer documentation for the target exchange.
You can omit optional
SChainNode property values, and you can also exclude trailing separators; for example,
URL encode any values that require it, including any values that contain a comma or a bang character.
Do not encode…
Any comma or bang that is a delimiter between values.
This represents an
sid of “
exampleexchange.com, which handles payments.
If the target advertising system of an incoming Supply Chain object is unable to parse the
sChain data and attempts to pass
sChain to a downstream recipient, the best practice is to initiate a new
complete=0 rather than trying to interpret the unreadable format.
The best practice for entries that parse but are deemed invalid by the advertising system parser, is to include them in the outgoing downstream requests.
The following examples illustrate the various use cases above.
Single Hop - Complete Chain
Single Hop - Chain Complete, optional fields missing SChain
Multiple Hops - With all properties supplied SChain
Multiple Hops - Chain Complete, optional fields missing
Multiple Hops Expected - Chain Incomplete SChain
Single Hop - Chain Complete, encoded values SChain