Apr 12, 2021 9 min read

Buyers.json and DemandChain Explained

Buyers.json and DemandChain Explained

Buyers.json and DemandChain make it easier to identify all buyers involved in a programmatic ad auction and trace ad creatives back to their origin. The two IAB Tech Lab specifications offer mechanisms that, when used in tandem, can increase the visibility into all of the entities buying an ad impression and help combat malvertising.

Why do we need more buy-side transparency?

In the specification documents, the IAB Tech Lab position the prevention of malvertising as the primary need for more buy-side transparency.

Malicious advertising or malvertising can introduce dangerous programs onto a device for nefarious purposes. These programs can include ransomware, spyware, or even bots designed to generate fake ad impressions. These malvertising programs often operate surreptitiously unbeknownst to the end-user.

Malvertising can propagate through the ad tech ecosystem through ads created to represent legitimate brands to trick users into interacting with a creative.

Bad actors introduce malvertising ads by posing as legitimate companies on DSPs or any ad-buying platform. The point of buyers.json and DemandChain is to make it easier for ad platforms and publishers to trace ads back to their provenance and identify who introduced a bad creative into the bid stream.

Malvertising is a pernicious threat solved by buyers.json and DemandChain, but the specifications can also help in other ways. Companies can also trace any low-quality ads or identify inefficiencies created through reseller relationships.

Buyers.json & DemandChain vs. Sellers.json & SupplyChain

You can think of buyers.json and DemandChain as the buy-side versions of the sellers.json and SupplyChain specifications introduced back in 2019.

Sellers.json outlined a standard method for supply-side platforms to publicly post all the entities selling inventory on their platform and whether they are direct or intermediaries.

SupplyChain is an ORTB bid request object that lists out all participants involved in the offer of an ad impression.

If you are familiar with these specifications, you will notice many similarities below.

What is buyers.json?

Buyers.json is a method for ad platforms to publicly communicate all of the entities buying on their platform.

The specification calls for a platform to host a publicly accessible buyers.json file on their root corporate domain.

JSON stands for JavaScript Object Notation and is the same format used for ORTB. So the specification is aptly named as it is a list of buyers presented in a JSON file.

If I wanted to look up the buyers.json file for Cool DSP I should be able to find it at:

https://cooldsp.com/buyers.json

There I would find something that looks like this:

{
  "contact_email": "contact@cooldsp.copm",
  "contact_address": "Cool DSP Inc., 101 1st Street, Los Angeles, CA 90001",
  "version": "1.0",
  "identifiers": [
    {
      "name": "TAG-ID",
      "value": "47dn38f1ngh3bi9q"
    }
  ],
  "buyers": [
    {
      "buyer_id": "1234",
      "name": "Advertiser, LLC",
      "domain": "advertisingdomain.com",
      "buyer_type": "ADVERTISER",
      "created_on": "2021-04-01"
    },
    {
      "buyer_id": "5678",
      "name": "Intermediary Inc.",
      "domain": "imanintermediary.com",
      "buyer_type": "INTERMEDIARY",
      "created_on": "2020-03-25"
    },
    {
      "buyer_id": "9475",
      "name": "Agency",
      "domain": "agencycorporate.com",
      "buyer_type": "INTERMEDIARY",
      “comment”: “Seat used for buying by agency for multiple brands”,
      "created_on": "2020-02-20"
    },
    {
      "buyer_id": "2837",
      "is_confidential": 1,
      "buyer_type": "INTERMEDIARY",
      "created_on": "2020-01-17"
    }
  ]
}

So what is going on here? Luckily for us, JSON has the benefit of being easily readable by both humans and machines alike.

The first section lists out contact information that interested parties can use if they have questions regarding the buyers.json file. This section is also where the entity listing the buyers.json file can list a unique trusted identifier like a TAG-ID (Trustworthy Accountability Group) for others to validate their identity.

But the real action happens in the buyers array. Platforms list all the buyers that purchase inventory on their system within this array.

A platform would list each buyer on their platform alongside other information tied to that buyer

Buyer ID

A unique identifier for the entity that is the same seat value that would be present in a bid response that contains a bid from this entity. Ad systems also include this value in the DemandChain (more on DemandChain in the next section).

Buyer Type

The buyer type can either be Advertiser, Intermediary, or Both. Advertisers are the accounts that pay for inventory. Intermediaries (agency or reseller) work on behalf of the advertiser to purchase inventory. A Both value represents entities that perform each based on the business context.

Name

The actual name of the company paying for the inventory under this buyer ID.

Domain

The business domain of the company. E.g. advertisingdomain.com.

Comment

Buying platforms can use this field to describe or clarify the buyer's identity, like if a buyer has multiple seats on the same platform.

Created On

Date indicating when the platform created the seat. Malvertisers typically have short lifespans, so platforms inspecting buyers.json could limit newly created seats if they choose.

Is Confidential

If a buyer does not want to reveal their true identity (how mysterious!) the platform listing the file can utilize this flag. However, supply-side platforms could choose to limit confidential buyers.

Cool, a list of buyers. How can this help increase transparency and restore balance to the programmatic universe, you ask? Enter, DemandChain.

What is DemandChain?

DemandChain is a new OpenRTB bid response object that details all entities participating in the purchase of an ad impression. This object enables publishers and selling platforms a transparent method of tracing the origin of a bid and its associated ad creative.

Much like SupplyChain, DemandChain consists of nodes that represent each entity participating in the programmatic ad transaction.

Let’s take a look at an example DemandChain that a DSP might include in a bid response to an SSP:

"dchain" : {
  "ver": "1.0",
  "complete" : 1,
  "nodes" : [
    {
      "asi": null,
      "name": "Funky Advertiser",
      "domain": "funkyadvertiser.com"
    },
    {
      "asi": null,
      "name": "Elegant Agency",
      "domain": "imanagency.com"
    },
    {
      "asi": "cooldsp.com",
      "bsid": "12345"
    }
  ]
}

In this example, our favorite Cool DSP will create the DemandChain object and add themselves to it along with any known entities participating in the transaction. In this case, the DSP knows that Elegant Agency is an agency that represents Funky Advertiser, the advertiser that provided the original creative.

So what do all these values mean?

asi

Advertising system identifier — the domain name of the DSP (cooldsp.com) or buying platform that is generating the bid response. The domain would be the same place where the buyers.json is hosted.

bsid

The buyer’s seat id. This is the same value present in ORTB bid responses and listed in the buyers.json file.

Name

The name of the company that is paying for this transaction. This value is not required if it is listed in a buyers.json file under the bsid, but it must be listed if there is no asi included in the node.

Domain

The business domain of the company in the node. Just like name, it is not required if it is listed in a buyers.json file under the bsid, but it must be listed if there is no asi included in the node.

Complete

A flag that indicates if the DemandChain contains all nodes back to the original advertiser paying for the ad impression and providing the creative. 0= no, 1 = yes.

You will notice that in our example the DSP includes both the agency and the advertiser without the asi value. According to the DemandChain specification, the DSP should “identify any non-programmatic payment relationships downstream of the DSP, to the extent it is able”.

So a DSP should make the whole chain of participants available if the path is known.

If an SSP receives this bid response, they would add themselves to the Demand Chain in the associated bid response back to the original site or app requesting an ad:

"dchain" : {
  "ver": "1.0",
  "complete" : 1,
  "nodes" : [
    {
      "asi": null,
      "name": "Funky Advertiser",
      "domain": "funkyadvertiser.com"
    },
    {
      "asi": null,
      "name": "Elegant Agency",
      "domain": "imanagency.com"
    },
    {
      "asi": "cooldsp.com",
      "bsid": "12345"
    },
    {
      "asi": "awesomessp.com",
      "bsid": "435827"
    }
  ]
}

The SSP adds themselves as the last node along with the Cool DSP buyer seat ID on the SSP.

Anybody inspecting DemandChain could cross-reference this value with the Awesome SSP buyers.json file to confirm that 435827 maps to Cool DSP.

Boom! Transparency.

Ok, so we now know that DemandChain reveals all the participants in buying an ad impression, and anybody can confirm the identities of those participants by inspecting buyers.json files, but what about all that malvertising talk? How do we trace bad creatives back to their origin?

Serializing and Exposing Creative Source Data

According to the sole keeper of all truths, Wikipedia, serialization in computing is:

“The process of translating a data structure or object state into a format that can be stored or transmitted and reconstructed later”

The DemandChain specification outlines a method of serializing creative origination data and transmitting it in ad markup to assist in tracing its source. The spec calls for three pieces of data to be serialized:

  • DSP Domain
  • Buyer Seat ID
  • Creative ID

The system providing the creative should serialize these values into a comma-delimited string:

Ver,dsp_domain,buyer_seat_id,creative_id,ext

Ver is the version of DemandChain used and ext is available for passing platform-specific information. The completed string would look like this:

1.0,cooldsp.com,hb3j7p,25736285

Cool DSP would provide the above string and it would signify that the buyer’s seat is hb3j7p and the id for the creative is 25736285.

Buying platforms should pass this string in the ad markup. The method of passing varies based on the creative type.

HTML

The string should live in the outermost HTML tags and be noted via a standardized identifier: “data-ad- creative-source="serialized_data".

Example:

<div name="adm" data-ad-creative-source="1.0,cooldsp.com,hb3j7p,25736285">... </div>

Participants can also pass the string as an HTML or JavaScript comment.

HTML comment:

<!-- data-ad-creative-source="1.0,cooldsp.com,hb3j7p,25736285" -->

JavaScript comment:

// data-ad-creative-source="1.0,cooldsp.com,hb3j7p,25736285"

VAST (video)

Platforms passing the string for video creatives should utilize the extension object in VAST and create an “AdCreativeSource” tag containing a “data-ad-creative-source” attribute.

<Extensions>
<Extension>
<AdCreativeSource data-ad-creative-source="1.0,cooldsp.com,hb3j7p,25736285">
</Extension>
</Extensions>

So when ad ops staff at an ad platform or publisher identify a malicious creative, they can inspect the ad markup to find the serialized creative source data to identify the originating DSP, the buyer who placed it, and the exact creative id.

The serialized string makes identifying individual creatives and their source a much simpler task since it is a standardized method.

Performing this task today would require intimate knowledge of the various proprietary ways platforms construct bid responses in addition to playing a game of detective with any ad platform participating in a transaction to identify the buyer supplying a given creative.

When will Buyers.json and DemandChain gain adoption?

Honestly, it may take some time. Specifications like these do not gain widespread support without the correct incentives for those who can force adoption — buyers, advertisers, and DSPs.

The companies paying the bills steer the industry, and the correct incentives usually boil down to a direct monetary impact on their bottom-line.

Initiatives like Sellers.json, SupplyChain, and even ads.txt, gained quick adoption since they directly benefited buyers. These specifications presented immediate and material benefits to the bottom line of DSPs. They helped eliminate wasted spend on ad fraud and facilitated supply path optimization.

Digital advertising veterans of the last decade will also clearly remember the rapid uptake in fraud prevention and viewability solutions. As soon as verification vendors made the immense amount of wasted ad spend on bots and non-viewable ads apparent, fraud prevention and viewability support were a table-stakes feature on any ad platform.

Do buyers.json and DemandChain offer the right incentives for buyers? Will the threat of malvertising alone drive the buy-side to force uptake of these new specifications?

Advertisers can protect their coveted brand reputation by eliminating malvertisers that hijack their logos to trick users into interacting with bad ads. Scam artists and malvertisers create entire landing pages masquerading as legitimate companies to impose their will on users.

Just recently, TechCrunch received reports of fake ads on Facebook for the drop-in audio app, Clubhouse. The scammers capitalized on the meteoric rise in popularity of the app to trick users into installing a fake Clubhouse for PC app that injected ransomware onto a target device.

Scam artists leverage the brand capital and trust of companies like Microsoft to dupe users into paying attention. YouTuber, Jim Browning, uncovered a fake tech support scam where the criminals mocked up a Microsoft support landing page to lure users into their scheme.

Eliminating malvertising will severely inhibit the propagation of scams like the two above examples.

Eradicating malvertising is a noble endeavor. But product teams with clogged feature backlogs do not often consider nobility in their prioritization decisions. So will eliminating malvertising save buyer revenue?

A 2015 study by the IAB and Ernst & Young concluded that the digital advertising industry stands to gain $1.1 billion by eliminating malvertising. $204 million from "investigating, remediating, and documenting" malvertising threats and $781 million from users driven to using ad blockers to avoid malicious ads.

That $1.1 billion has most likely grown in correlation with the industry itself, so there may be even more potential revenue at stake. Although, these new specifications could offer negative drawbacks to some buy-side players.

Buyers.json and DemandChain could open a new avenue of demand path optimization for the supply-side. Suppliers could trim some fat and find shorter paths to the original buyers — which could negatively affect some buying platforms.

Publishers also stand to gain by protecting their users from any potential malicious digital threats. Supporting these new specifications will make it easier to secure trust from users of their apps and websites.

Buyers and sellers both have incentives to advocate for buyers.json and DemandChain, but only time will tell whether those incentives alone can drive widespread adoption.

Photo by Edge2Edge Media on Unsplash

Trey Titone
Author of Ad Tech Explained and VP of Client Success at Logiq. Former Principal Product Manager at SpotX and Head of Product at Beachfront Media.
Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Ad Tech Explained.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.