Sellers.json and Supply Chain Object

Introduction

Sellers.json is an instrument for increasing transparency of the RTB chain by listing the authorized tech platforms allowed to resell the inventory.

In addition to ads.txt, which is used by end publishers, sellers.json is an attempt to reveal parties involved in reselling traffic and make the supply chain more clear. 

Applied to the intermediary platforms (SSP, exchange), Sellers.json file should be put in the root domain and list all partners which resell traffic. This application allows buyers to scan sellers.json files and ensure the clarity of the supply chain.

Sellers.json

How to set up Sellers.json

To set up sellers.json, open the Companies section. You will see the list of companies.
Pay attention to the Domain column. Some companies do not have domains:

 

Only companies with domains appear in sellers.json.

 

Open the profile of each SSP company without the domain, and add it:

 



 

Then, open Settings:

 

Scroll down to ‘Sellers.json’ and set contact email and contact address (required; contact phone is optional).

Also, the ‘Domain’ field is required to ensure the correct operation of the file:

Click ‘Download file’ and move to the next step: place the file on your domain.

 

How to use sellers.json

After file downloaded, check downloaded ‘sellers.json’ file via text editor to ensure everything is correct and all SSPs you need is present in the file.

 

Sellers.json must contain records listed as JSON objects:

{
	"contact_email":"smarthub@smartyads.com",
	"contact_address":"New York 5555",
	"version":1,
	"identifiers":	[
		{
			"name":"TAG-ID",
			"value":"a23a4238a0b927520dcc519a6f55841b"
		}
	],
	"sellers":	[
		{
			"seller_id":"7ceab3a1649fda2b3ff8d02edfd5659f",
			"seller_type":"INTERMEDIARY",
			"name":"SSP_1_Banner_12",
			"domain":"ssp1.com"
		},
		{
			"seller_id":"69add1e107d7f7d035d7dafd4342e1ca",
			"seller_type":"INTERMEDIARY",
			"name":"SSP_5_Video",
			"domain":"ssp5.com"
		}
	]
}

The main object contains contact info of the sellers.json issuer, version of the file, and identifiers, such as TAG-ID.

Sellers array must contain objects for each partner. Such an object consists of fields seller_id, seller_type, seller_name, and domain, and also optional is_passthrough field.

 

If everything is correct, place the file in the root directory of your main domain, so your partners can scan the file, and scan other sellers.json files down the supply chain.

For example, if the platform URL is exchange.company.com, seller.json should be added to the company.com domain, so the resulting address should be company.com/sellers.json.


 

Supply Chain Object

Smarthub can include Supply Chain object into requests for demand side endpoints that require that.

To do so, open an endpoint and set ‘Schain’ option:


 

If set, each bid request will contain the Schain object that reveals the entire supply chain through which the request passed.

The request will look like this:

"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",
...

The Schain object, as shown above, contains the specification version, the completion flag, and an array of nodes. Each node corresponds to a reseller that is a link in a supply chain. The first node represents the initial advertising system that received the request.

Let's take a closer look at the object. It contains such fields:

  • asi – The domain name of the advertising system intermediary.
    Note: This should be the same value as used to identify sellers in an ads.txt file if one exists.
  • sid – The identifier of the seller or reseller account within the advertising system.
  • rid – The request ID as issued by the seller or reseller.
  • hp – Flag of involvement in the flow of payments.
    Note: This field is required and should always be set to 1.


 

An example of building a supply chain object:

  1. The website1.com issues a bid request.
  2. The request was received by SSP1
  3. Then, the request transmitted sequentially:
    to Exchange Platform 1
    to Exchange 2
  4. And finally, the request comes to DSP1, which responded with a bid response.

 

The final supply chain object will look like:

"nodes": [
          {
            "asi":"ssp1.com",
            "sid":"website1com-id-within-ssp1"
            "rid":"BidRequest1",
            "hp":1
          },
          {
            "asi":"adx1.com",
            "sid":"id-of-ssp1-in-adexchange1"
            "rid":"BidRequest2",
            "hp":1
          },
          {
            "asi":"reseller2.net",
            "sid":"adex1-id-within-reseller2"
            "rid":"BidRequest3",
            "hp":1
          }
]

Schain object formation mechanism::



 

Together, the ads.txt (app-ads.txt), sellers.json, and Schain object provide supply chain transparency. 

The buyer (DSP) can check the sequence of data: the presence of a seller in the ads.txt, the presence of all further resellers in sellers.json files, that Schain object addresses to – and decide whether to bid depending on consistency check.


The chain integrity verification scheme:

 

Each reseller must be declared in the sellers.json file of the next reseller.

The first participant in the sales chain must be specified in the ads.txt file of the publisher whose traffic is being sold.