Let’s talk about the SupplyChain Object today. Our blog has previously covered the topics of ads.txt and sellers.json, but for those needing a bit of a refresher:

  • Ads.txt is an industry-wide initiative, championed by the IAB, which aims to reduce the prevalence of domain spoofing. In order to combat the risk of domain spoofing, publishers host a file at the “{domain}/ads.txt” directory, and this file lets buyers known exactly what combinations of ad system & publisher ID may announce their inventory for sale.
  • Sellers.json is an IAB initiative aimed at bringing even greater transparency to each advertising opportunity. It allows buyers to map publisher/seller IDs to the human readable name of the seller making inventory available during the course of an auction.

These 2 tools combined create a sort of directory of authorized sellers which is understandable to any reader, and not just automated systems which ingest publisher IDs as part of their decisioning processes.

The SupplyChain object was announced at the same time as sellers.json; it’s a JSON object which is passed with each bid request, and it contains any entities that participate in the sale of a piece of inventory.

The great thing about this intiative is that it gives you impression level insights into the supply chain. It tells you about things that are confirmed to have happened, rather than what ads.txt & sellers.json tells you, which is what’s possible.


Where Can I Find a Supply Chain Object?

For readers who are not intimately antiquated with how the Real Time Bidding (RTB) process works, some context from the IAB open RTB spec may help: “RTB transactions are initiated when an exchange or other supply source sends a bid request to a bidder. The bid request consists of the top-level bid request object, at least one impression object, and may optionally include additional objects providing impression context.”

To rephrase & expand on that a bit:

  • The RTB process begins when a seller announces that it has inventory available. This announcement is called a bid request.
  • The IAB recommends encoding bid requests as JSON. The top level object in a bid request is officially called the “BidRequest” object.
  • A BidRequest object may have many child objects depending on the type of inventory which is being made available. The only required child object is the “Imp” (short for impression) object.

The SupplyChain object is found within the BidRequest object, but exactly where depends on which version of Open RTB is being used:

  • OpenRTB 2.5 or later: BidRequest.Source.ext.schain
  • OpenRTB 2.4 or prior: BidRequest.ext.schain

What Does a Supply Chain Object Look Like?

sample supplychain object

The above example, taken from the documentation, shows a mock-up of a BidRequest Object containing a valid and complete SupplyChain.

The SupplyChain object here = the BidRequest.Source.ext.schain object. The schain has several attributes, which are included here with their definitions from the documentation:

  1. complete (REQUIRED): Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes.”
  2. ver (REQUIRED): Version of the supply chain specification in use, in the format of ‘major.minor'”
  3. nodes (REQUIRED): Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, i.e. the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.”

To reduce that all a bit:

  • The nodes object array has the juicy info on the sellers and resellers who have handled the inventory you are bidding on.
  • If complete = 1, then then all the sellers are accounted for in the nodes array.

Understanding the nodes

The innermost object in the example bid request is considered a “SupplyChainNode;” each one contains information on a seller who has participated up to this point.

Each node has the following pieces of information:

  • asi (REQUIRED): this is the SSP / seller ad system which offers inventory for sale. It announcing ad system should use the same domain as they do in the publisher’s ads.txt file.
  • sid (REQUIRED): this is the seller/ publisher ID within the asi ad system. Should match a record in the publisher’s ads.txt file.
  • hp (OPTIONAL): The ad system in the asi field directly pays the seller in the sid field when this flag is set to “1.” If there are multiple SupplyChainNodes, then the newest node is responsible for paying the previous node until the chain of payment is resolved.
  • rid (OPTIONAL): the request ID of the associated impression.
  • name (OPTIONAL): the name of the seller, if it’s not available in the sellers.json file associated with the asi ad system.

It’s possible for the nodes array to have multiple SupplyChainNodes, and they are ordered from oldest to newest when that happens. For example, take this schain from the documentation:

example schain with 2 SupplyChainNodes

What this example shows is that: seller “00001” of the ad system “directseller.com” has already sold this inventory to seller “aaaaa” of the ad system “reseller.com.” Now, seller “aaaaa” of the ad system “reseller.com” is making that inventory available to us.

Now that we have a high level understanding of how it works, let’s apply this knowledge to a real life example!

Putting it All Together

Well be using an example bid request captured from live traffic on cnn.com today, and verify the authenticity of the opportunity:

SupplyChain Object brings light to darkness

We can see that this nodes array has only one SupplyChainNode and complete = 1; this means that this should be a direct transaction.

Armed with this information, the next step is to go to cnn.com/ads.txt, and search for a DIRECT entry where “outbrain.com” is the ad system & the publisher account id = “0048938c4af9641f2e04565be89ece5954.”

relevant entry in cnn.com's ads.txt file

Indeed there is a DIRECT entry which matches this ID & ad system! This entry lines up with what we know about the opportunity based off the bid request.

The next step is to ensure that this seller ID is authorized by the ad system. To confirm this ID is authorized , we consult outbrain’s sellers.json record for seller id “0048938c4af9641f2e04565be89ece5954”

oubtrain sellers.son record for the ID in question

The ad system’s sellers.json record shows that this seller’s name is “CNN (Turner U.S.),” which lines up directly with the source of the bid request. At this point, we have successfully confirmed that the opportunity we were presented with came from an authorized source!

This is much the same way that ad-buyers use the data from these initiatives, but they do it at a much larger scale. This type of data allows them to cut out unnecessary middlemen, and optimize their bidding strategies.