Introduction
An ads.txt file is how a publisher says which advertising systems are authorised to sell its advertising
space. It sits at /ads.txt on the publisher’s root domain, and buyers and ad exchanges read it to check that a
seller is on the list. It was specified by the IAB Tech Lab in 2017 and
is at version 1.1 (final release July 2022). It is inspired by robots.txt. Apps have a
companion file, app-ads.txt.
Structure
The file is lines of two kinds, plus comments. A record has the form
domain, account ID, relationship[, certification authority ID]; a variable has the form
NAME=value. A # starts a comment that runs to the end of the line.
# ads.txt file for example.com
OWNERDOMAIN=mediacompany.com
CONTACT=adops@example.com
greenadexchange.com, XF7342, DIRECT, 5jyxf8k54
blueadexchange.com, 4536, RESELLER
A file that wants to say that no system is authorised uses the placeholder record
placeholder.example.com, placeholder, DIRECT, placeholder; an empty file no longer means that (since version 1.0.2,
ignored from 1 March 2020). The records and variables page has every field and variable.
The file is served as text/plain (any other content type is to be treated as an error), preferably over HTTPS, and
readers are to be liberal about line ends (CR, LF, CR LF) and white space.
In the explorer
Drop a file named ads.txt on the explorer to see one node per line: records (DIRECT, RESELLER, placeholder),
variables, comments and lines that are none of those. The tabs list the records, the variables, the advertising systems with a
count of records each, and the problems. A real ads.txt can have thousands of records and the tabs show every one: a table of more than 5,000
rows is paged, 200 rows at a time with Previous and Next, and the heading and the Overview give the true total.
Rules that are broken are listed as Issues, with the section of the specification: too few or too many fields, a first field
that is not a domain name, an empty account ID, white space in the account ID or in the certification authority ID (section 3.4.2),
a relationship that is not DIRECT or RESELLER, a repeated OWNERDOMAIN, two
MANAGERDOMAIN lines for one country, an OWNERDOMAIN or MANAGERDOMAIN that begins with "www." (only that form of a hostname is detected: the Public
Suffix List is not part of the viewer), a MANAGERDOMAIN country that is not two letters (only the shape is tested), and a file with no record at
all. Nothing is refused.
The Issues list has no classes, so a message that starts with Note: is an observation or a recommendation, not a broken rule: a record that appears twice (the specification does not forbid it; the Overview counts the repeats), a variable name written in another case, a hostname in OWNERDOMAIN, a non-ASCII account ID (our inference from the URL-encoding sentence of 3.4.2) and a SUBDOMAIN line in app-ads.txt.
A file is recognised as ads.txt by its name and its content. By name (how a dropped or listed ads.txt reaches the viewer)
it is enough that the text is not HTML or XML and holds one valid record or one of the five variables written NAME=value, so a file in
which many lines are faulty still opens here and shows its Issues. The stricter content test (at least four of every five lines that are not blank or
comments are valid records or those variables) is kept for callers that have no name. Any other file called ads.txt (an HTML error page, a
compressed body, prose) opens as plain text, as before. There is no size limit on the claim (a file over 4 MiB opens in the viewer; the viewer says
"too large" above 8 MiB). The text is not coloured: no highlighting family exists for it yet.
Not described
Known, not yet covered
- Viewer: the domain in field 1 and the values of OWNERDOMAIN, MANAGERDOMAIN and SUBDOMAIN are checked as DNS names (RFC 1123 labels), not against the Public Suffix List; “Public Suffix List +1” is not verified.
- Viewer: the redirect and subdomain-lookup rules (one hop to another domain, INVENTORYPARTNERDOMAIN followed one hop) are described, not performed: nothing is fetched.
- Viewer: sellers.json, the companion file that the account IDs are checked against, is not read.
- Viewer: the text is shown plain: there is no highlighting family for ads.txt.
- Viewer: a hostname where a domain is wanted is detected only as a leading “www.” on OWNERDOMAIN and MANAGERDOMAIN (any other subdomain passes: the Public Suffix List is needed); the country of MANAGERDOMAIN is checked as two letters, not against the ISO 3166-1 list, so “ZZ” passes.
- Viewer: the rule that a non-ASCII character in an account ID is noted is our inference from the URL-encoding sentence of section 3.4.2 (“No field should contain tabs, commas or whitespace, otherwise it should be escaped with URL encoding”), which does not name non-ASCII characters.
- Viewer: a text that is not an ads.txt at all (no valid record and no variable written NAME=value) opens as plain text even when it is called ads.txt.
Unknown
- Reference: the format of the certification authority ID beyond “a TAG ID”; the specification says the field may be deprecated and that sellers.json supersedes it, and gives no pattern.
- Reference: whether variable names written in lower case are valid: the specification’s examples use both
SUBDOMAIN=andsubdomain=and states no rule, so the viewer matches names without regard to case. - Viewer: a size limit for the file: the specification gives none.
Links
Reference
- IAB Tech Lab: ads.txt – the specification’s home and its version history
- Ads.txt Version 1.1 – the specification text
- Implementation guidance – IAB Tech Lab’s guidance for implementers