Blog Transparency

ads.txt, app-ads.txt and sellers.json: how buyers check who is selling

Three small files and one object in the bid request let a buyer trace an impression from the app to every company that touched it. Here is how they fit together, and how to keep yours clean.

5 min readBy the Arcaneflow team

A programmatic buyer bidding on an impression wants to answer two questions: is this inventory really what it claims to be, and is the company selling it allowed to? The industry’s answer is a set of open standards from IAB Tech Lab. Individually they are simple. Together they let a buyer trace an impression from the app to every company that touched it.

ads.txt: the publisher’s list of authorized sellers

ads.txt (“Authorized Digital Sellers”), published by IAB Tech Lab in 2017, is a plain text file a publisher places at the root of its website domain. Each line names an advertising system, the publisher’s account ID in that system, and the type of relationship:

ssp.example, 4821, DIRECT, a1b2c3d4e5f60789
exchange.example, pub-77310, RESELLER
FieldMeaning
Advertising system domainThe SSP or exchange where the account lives
Account IDThe publisher’s seller ID in that system
RelationshipDIRECT if the publisher controls the account, RESELLER if another company sells on its behalf
Certification authority IDOptional, for example the account’s TAG ID

A buyer that sees a request claiming to come from a site checks that site’s ads.txt. If the SSP and seller ID in the request are not listed, the buyer can treat the inventory as unauthorized.

app-ads.txt: the same idea for apps and CTV

Apps do not have a domain in the request, so in 2019 IAB Tech Lab extended the standard. With app-ads.txt, the developer hosts the same kind of file on the website listed for the app in its app store. A buyer finds the app’s store listing, follows the developer URL, and reads /app-ads.txt from that domain.

The same approach works for connected TV: CTV apps are listed in their platform’s store (Roku, Amazon Fire TV, Samsung and others), and the developer URL on that listing is where buyers look. If an app’s store listing has no developer URL, or the file is missing or outdated, buyers may not be able to validate the inventory at all.

The format has grown a few useful variables over time:

  • CONTACT tells buyers whom to ask about the file.
  • INVENTORYPARTNERDOMAIN supports CTV inventory sharing. When a streaming service sells ad breaks that belong to a content owner, it points to the partner’s domain instead of listing every account itself.
  • OWNERDOMAIN and MANAGERDOMAIN, added in ads.txt 1.1, declare the business that owns the property and any company authorized to manage its programmatic monetization, so buyers can match them to sellers.json entries.

sellers.json: the advertising system’s side

ads.txt is written by the publisher. sellers.json, released by IAB Tech Lab in 2019, is the other half, written by the advertising system. Each SSP or exchange publishes a JSON file at /sellers.json on its own domain, listing every account it represents:

{
  "version": "1.0",
  "contact_email": "adops@ssp.example",
  "sellers": [
    { "seller_id": "4821", "name": "Example Media", "domain": "example-media.com", "seller_type": "PUBLISHER" },
    { "seller_id": "9013", "name": "Example Network", "domain": "example-network.com", "seller_type": "INTERMEDIARY" }
  ]
}

seller_type says whether the account belongs to the owner of the inventory (PUBLISHER), a company selling someone else’s inventory (INTERMEDIARY), or both (BOTH). An entry can be marked confidential, but it must still be listed. One seller ID must represent exactly one entity.

ads.txt and sellers.json meet at the seller ID. The ID in the publisher’s file should match an entry in the system’s file, and the domain in that entry should lead back to the publisher.

The SupplyChain object: every hop in the request

The files describe who may sell. The SupplyChain object, usually called schain, describes who actually did, request by request. It travels inside the bid request (in OpenRTB 2.6 it lives at source.schain) and lists a node for every company that handled the impression:

"schain": {
  "ver": "1.0",
  "complete": 1,
  "nodes": [
    { "asi": "ssp.example", "sid": "4821", "hp": 1 },
    { "asi": "exchange.example", "sid": "9013", "hp": 1 }
  ]
}

Each node names the advertising system (asi) and the seller ID in it (sid). hp indicates that the node is involved in the flow of payment. complete is 1 when the chain reaches all the way back to the owner of the inventory.

How a buyer puts it together

For a single request, a careful buyer will:

  1. Identify the inventory: the site domain, or for apps the store listing and its developer URL.
  2. Read that publisher’s ads.txt or app-ads.txt.
  3. Walk the schain nodes, and check each advertising system and seller ID against the publisher’s file and against that system’s sellers.json.
  4. Decide what to do with anything that does not line up: lower the bid, or skip the impression.

Many buyers also prefer the shortest path to the inventory, which is why DIRECT lines and complete chains matter in practice.

A checklist for app and CTV publishers

  • Make sure every app’s store listing has the correct developer URL, and host app-ads.txt at the root of that domain.
  • Add a line for every account that sells your inventory, exactly as each partner gives it to you, including the relationship and any certification ID.
  • Remove lines for partners you no longer work with.
  • If you own several apps or properties, use OWNERDOMAIN consistently; if a partner manages your monetization, declare it with MANAGERDOMAIN.
  • If you share CTV inventory with a distribution partner, agree how INVENTORYPARTNERDOMAIN will be used before you go live.
  • Check your partners’ sellers.json entries for your accounts, and ask for corrections when names or domains are wrong.

ManaForge declares its sellers in sellers.json and expects authorized paths in app-ads.txt, end to end. If you are setting up a new integration, we will give you the exact lines to add. Get in touch to start.

Further reading

Strike while
it’s hot.

Share your inventory and what you want to achieve. Let’s find where Arcaneflow fits.