Just when publishers had wrapped their heads around the Interactive Advertising Bureau (IAB) Tech Lab’s anti-fraud initiative, ads.txt, it was announced that two new supply path optimisation (SPO) mechanism’s was being released—sellers.json and the related OpenRTB SupplyChain object (SCO).
This pair of specifications are designed to improve trust of the supply chain, allowing buyers to optimise their path to your inventory and ensure they are not being stung by the “tech tax”. Put simply, this pair of specifications could be seen as the ads.txt for the buy side.
Trade House Media is proud to be an early adopter of this fantastic initiative, having worked tirelessly to be a leader in this space and one of the first businesses globally to fully support sellers.json and SupplyChain Object across our entire ecosystem.
Why does the industry need an initiative like sellers.json and SupplyChain Object?
As programmatic buyers became more sophisticated, what became apparent is that not every impression was being offered to them in a financially efficient supply chain. Rather than a publisher offering an impression to a supply-side platform (SSP), who then offered it to the advertiser’s demand-side platform (DSP), they found that impressions were being sold and resold many times before being offered to them.
Each hop in this supply chain was subject to various ad tech platform fees. This ultimately means that publishers are losing out on revenue and that advertisers are having their brand spend diluted by this “tech tax”.
In a now infamous 2016 experiment, The Guardian secretly bought their own inventory and found that—in some circumstances—only 30% of the advertising spend was actually making it to the publishers.
In this sellers.json & SCO guide, we look at what sellers.json is, how it functions with the SupplyChain object, how it impacts publishers and what steps (if any) publishers need to undertake to be compliant with this initiative.
What is sellers.json?
Sellers.json is a published and publically accessible JSON (JavaScript Object Notation) file that sits on the root directory of an ad platform’s website. Pubmatic’s sellers.json, for example, can be publicly viewed here.
The sellers.json file is designed to be human and machine readable, allowing buyers to quickly ascertain the relationship they have with the inventory source and whether it is being offered to them directly from the publisher or via a reseller.
The file always follows the same structure. It opens by declaring some basic information about the business:
{
"contact_address": "PHYSICAL_ADDRESS_OF_AD_PLATFORM",
"contact_email": "EMAIL_ADDRESS_OF_AD_PLATFORM",
"version": VERSION_NUMBER,
"identifiers": [
{
"name": "TAG-ID",
"value": "AD_PLATFORM_TAG_ID_IF_APPLICABLE"
}
],
"ext": {
> "last_updated": "LAST_UPDATE_DATE"
},
"sellers": [
| ATTRIBUTE | TYPE | DESCRIPTION |
|---|---|---|
| sellers | object array; required | The list of all Seller objects that are represented by the advertising system. All sellers must be included even if they are confidential. |
| identifiers | object array; optional | Array of Identifier objects associated with this advertising system. Examples could be TAG-Ids, Dun & Bradstreet business identifiers, or any custom identifier that a consuming advertising system might need. |
| contact_email | string; optional | An email address to use to contact the Advertising System for questions or inquiries about this file. |
| contact_address | string; optional | The business address of the advertising system. |
| version | string; optional | The version of this spec, currently the only valid value is 1.0. |
| ext | string; optional | Placeholder for advertising-system specific extensions to this object. |
Once that is out of the way, the file then lists an array of “nodes” that contain all the relevant details of each publisher on the ad platform:
{
"seller_id": "UNIQUE_PUBLISHER_ID_ON_PLATFORM",
"name": "NAME_OF_PUBLISHER.",
"domain": "PUBLISHER_DOMAIN",
"seller_type": "RELATIONSHIP_TYPE"
},
That node can be repeated in this array for as many times as necessary to list every publisher on the platform.
It isn’t necessary to list each individual site on your sellers.json file. As per the spec:
“It is invalid for a seller_id to represent multiple entities. Every seller_id must map to only a single entity that is paid for inventory transacted with that seller_id. It is valid for a selling entity to have multiple seller_ids within an advertising system.”
So, for example, if you have a relationship with a publisher that owns 20 sites – it is not necessary to list each of the 20 sites in your sellers file. You just list the publisher once alongside their parent domain.
| ATTRIBUTE | TYPE | DESCRIPTION |
|---|---|---|
| seller_id | string; required | This is the same ID that appears in an ads.txt file and in the SupplyChain.nodes array sid property. In most cases will also appear in the Publisher.Id property of an OpenRTB request. |
| is_confidential | integer; optional, default 0 | Indicates whether the identity of the seller is confidential, where 0 = is not confidential and 1 = is confidential. |
| seller_type | string; required | An enumeration of the type of account, either PUBLISHER, INTERMEDIARY, or BOTH. A value of "PUBLISHER" indicates that the inventory sold through this account is on a site, app, or other medium owned by the named entity and the advertising system pays them directly. A value of “INTERMEDIARY" indicates that the inventory sold through this account is not owned by the named entity or the advertising system does not pay them directly. 'BOTH' indicates that both types of inventory are transacted by this seller. Note that this field should be treated as case insensitive when interpreting the data. |
| is_passthrough | integer; optional, default 0 | A passthrough seller is a facilitator of inventory from the upstream supplier to the consumer of the inventory. The upstream supplier and consumer must establish a business relationship with each other such that the upstream supplier has control of their account within the consumer’s platform. A value of 1 indicates the following: - This seller has an account control relationship with the downstream/consuming advertising system. - If this seller is the last link in a SupplyChain, the buying system has to have established an account control relationship with this seller to transact the seller’s inventory. - If this is not the last link in a SupplyChain than this seller should exist between two entities that have an account control relationship. A value of 0 indicates: - The downstream/consuming advertising system has no account control relationship with this seller. |
| name | string; required when is_confidential=0 | The name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. Can be omitted only when is_confidential is set to 1. |
| domain | string; required if seller has a web presence and is_confidential=0 | The business domain name of the company (the legal entity) that is paid for inventory that is transacted under the given seller_id. When the seller_type property is set to INTERMEDIARY or BOTH, this should be the root domain name of the seller’s Sellers.json file. Can be omitted when is_confidential is set to 1 or when the seller doesn’t have a web presence. |
| comment | string; optional | Any helpful description for this inventory. It is useful for sellers that have multiple seller ids to describe what this seller_id represents. |
| ext | object; optional | Placeholder for advertising-system specific extensions to this object. |
The full spec document for sellers.json can be found on the IAB Tech Lab website.
What is the OpenRTB SupplyChain Object?
It is all well and good to have a sellers.json file in place, but it is incomplete without also being able to also pass this information up the bid stream with the bid request. This is where the OpenRTB SupplyChain Object comes in.
The SCO allows buyers to view—in real time and at a bid level—the supply path that any bid request has taken. This allows them to optimise their supply paths and ensure they are bidding on the most direct route to the inventory.
In theory it is similar to sellers.json although in practice, instead of a publicly accessible JSON file, SCO is built into an ad tech platform by its development team.
Using the SupplyChain object an ad platform can pass all the same information in the sellers.json to the buyer in the bid request in a format that is ingestible buy their buying platform (DSP).
Added to the bid request, along with the usual location, cookie, and bid data, would be additional schain details:
"bidrequest" : {
"id": "BidRequest2",
"app": {
"publisher": {
"id": "aaaaa"
}
}
"source": {
"ext": {
"schain": {
"ver":"1.0",
"complete": 1,
"nodes": [
{
"asi":"directseller.com",
"sid":"00001"
"rid":"BidRequest1",
"hp":1
},
{
"asi":"reseller.com",
"sid":"aaaaa",
"rid":"BidRequest2",
"hp":1
}
]
}
}
}
}
What does this all look like in practice?
Using a real-world example, we can see how this looks in practice.
- A publisher or reseller has been given an ID of 11306 on our ad platform and this is being pushed as the SID value in the PreBid.js Schain module.
- This is referenced on the ad platform’s sellers.json file.
- This is referenced on the publisher’s ads.txt file:
When a page loads on the publisher site and the ad placement requests an ad, Trade House Media sends a bid request to a buyer as normal but includes the schain bid data in the bid request.
The buyer then passes that request on to their integrated DSPs, passing the same details up the bid stream to the advertisers.
Who needs to pay attention to this?
Generally this applies specifically to SSPs and DSPs.
Are there any steps I, as a Trade House Media publisher, need to undertake in order to be compliant?
The good news is that, as a publisher, there is very little for you to do to support this. Ensuring that your ads.txt file is up to date with all of your ad tech partners that support sellers.json and the SupplyChain object, incl. Trade House Media, will automatically ensure you are compliant.
If you would like to speak to a member of the team to discuss what we have done to ensure we are compliant or how we can help you navigate the various ad tech supply path optimisation initiatives being regularly announced, get in touch with us today. We specialise in providing unrivalled ad management as a service to blue chip clients globally and would love to speak to you.