The DNT-Consent qualifier

When a domain origin implements tracking for multiple distinct purposes, and these are described to the user before they are given the option to agree to one or more of them, the subset of purposes the user has selected must be communicated back to the origin. While cookies may be used for this, they may not be always available, and in any case an embedding parent context, e.g. a first-party origin, would not be able to set them for origins it had embedded.

The DNT-Consent qualifier allows an arbitrarily encoded string to be communicated to servers solely in circumstances where the user has given their informed consent. It is denoted by "0" followed by one or more alphanumeric characters. The JavaScript Site-Specific storeTrackingException API, with a sitedictionary property not set to "*", must be used to specify a DNT field-value containing the DNT-Consent qualifier, which can be encoded in any way that the relevent server that receives it can decode. The browsing context executing it must be secure, i.e. the content has been delivered over https.

If an origin server specifies a DNT-Consent qualifier it MUST implement a site-wide tracking status resource with a valid Purposes property. The Purposes property is a dynamically determined HTML resource containing a human-readable explanation of all the purposes for tracking that a domain origin implements, as well as the specific purposes a particular user has agreed to as communicated in the the DNT header of the request to the site-wide tracking status resource.

For example, a request containing

DNT:0 purpose=an,ad

Similarly, a request to a particular third-party server containing

DNT:0 audience=male>65

API to Store a Tracking Exception

When a site has obtained consent for a user-granted exception, or a user has indicated their objection to lawfully exempted tracking when their tracking preference is not enabled, a script running within an active browsing context or nested browsing context of that site can promise-call Navigator.storeTrackingException to store one or more tracking exceptions. A TrackingExData object is supplied as a parameter to define the exception's scope (the set of [site, target] duplets that encompass the granted exception) and optional information to be stored for that exception. The call returns a promise which either resolves to a TrackingExResult or is rejected with a DOMException identifying the reason for the failure.

        partial interface Navigator {
            Promise<TrackingExResult> storeTrackingException (
              TrackingExData properties
            );
        };
        dictionary TrackingExData {
           DOMString? site;
           sequence<DOMString>? targets;
           DOMString? name;
           DOMString? explanation;
           DOMString? details;
           long?      maxAge;
           DOMString  fieldValue;
        };
        dictionary TrackingExResult {
          boolean isSiteWide;
        };
        

Navigator.storeTrackingException passes a TrackingExData object. A user agent MUST ignore unknown properties of the TrackingExData object (for future extensibility). The following OPTIONAL properties are defined:

site

The referring domain scope for which the exception applies:

• If site is undefined, null, or the empty string, the exception's referring domain scope defaults to the script domain.
• If site is defined and equal to "*", the exception is intended to be web-wide< for the set of targets. A user agent MUST reject the promise with the DOMException named "SecurityError" if both site and any of the targets are "*".
• Otherwise, the exception's referring domain scope is defined by a domain found in site that is treated in the same way as the domain parameter to cookies [[!RFC6265]], allowing subdomains to be included with the prefix "*.". The value can be set to a fully-qualified right-hand segment of the document host name, up to one level below TLD.

targets

An array of target domains for which the exception applies:

• If targets is undefined or null, the user-granted exception to be stored is [site, *], meaning that the exception applies to all domains referenced by the site.
• If targets is an empty array, the user-granted exception to be stored is [site, script domain], meaning that the exception applies only to resources that share the same domain as the effective script origin.
• Otherwise, for each domain string in the targets array, a user-granted exception to be stored is the duplet [site, domain].

name

When defined and not null or an empty string, name is a user-readable string for naming the exception, usually descriptive of the targets or their intended purpose for this site.

explanation

When defined and not null or an empty string, explanation is a user-readable short explanation of the granted exception.

details

When defined and not null or an empty string, details is a URI reference at which further information about the granted exception can be found [[!RFC3986]].

maxAge

When defined and not null, maxAge is a positive number of seconds indicating the maximum lifetime of the grant:

• If maxAge is supplied and not null, empty, or negative, the user agent MUST remove the stored exception no later than the specified number of seconds after being stored.
• If maxAge is not supplied, the user agent MAY retain the stored grant indefinitely.

fieldValue

When defined and not null or an empty string, fieldValue indicates the field-value of the DNT header to be sent to all domains for which this exception applies. Only a field-value consisting of either the single character "1", or a string whose first character is "0" and which complies with the definition of a DNT-Consent value, is valid. A string whose first character is "0" can only be registered via this call when the browser is processing a user gesture in which user has given their informed consent, AND the Tracking Exception requested is site-specific (i.e. the site property is not "*"), AND the call is being executed within a secure top-level browsing context. For all other string values, or the executing browsing context is not secure, or the site property is "*", or the browser is not executing a user gesture, the user agent MUST NOT store the exception, and MUST reject the promise with a DOMException named "SyntaxError".

• If fieldValue is equal to "1" the user agent must send a DNT header with the field-value set to "1" for all requests to domains for which this exception applies; or
• If the first character of fieldValue is "0", the executing context is top-level, secure and processing a user gesture, and the rest of the string is a valid DNT-Consent value, the user agent MUST send a DNT header with the field-value set to fieldValue for all requests to domains for which this exception applies; or
• If fieldValue is not defined, null or the empty string the user agent MUST send a DNT header with the field-value set to "0" for all requests to domains for which this exception applies; or
• If fieldValue is any other value then the user agent MUST NOT store an exception and MUST reject the promise with a DOMException named "SyntaxError".

The properties name, explanation, and details are provided by the caller for the sake of potential user interfaces. If a user agent presents these properties to the user, it ought to be clear that they are provided for informational value and are less important than the exception's technical effect.

In addition to the data above, a user agent might also store ambient information about the call, such as the URI associated with the top-level browsing context, the effective script origin, a current timestamp, or other information potentially obtained from applicable tracking status resources.

The calling script domain MUST have a site-wide tracking status resource with a valid tracking status representation that includes a policy property. This allows a user agent to obtain and possibly store additional information about the caller’s controller and tracking policies at the time an exception is granted.

A user agent MAY reject the promise with a DOMException named "InvalidStateError" if it cannot determine the effective script origin or if the site corresponding to that origin does not have a site-wide tracking status resource with a valid tracking status representation.

For each site-specific exception being stored, a user agent MUST NOT store the duplets and MUST reject the promise with a DOMException named "SecurityError" if the script would not be able to set a cookie on that duplet's referring domain scope following the cookie domain rules [[!RFC6265]].

For example, a script on www.foo.bar.example.com can set the site as "bar.example.com" or "example.com", but not to "something.else.example.com" or "com".

For each web-wide exception being stored, a user agent MUST NOT store the duplets and MUST reject the promise with a DOMException named "SecurityError" if the script would not be able to set a cookie on that target domain following the cookie domain rules [[!RFC6265]]. This limits storing of a web-wide exception to scripts that share the same domain scope as the exception targets, but allows such scripts to be embedded within iframes of a common consent portal.

For any other failure, such as an incorrectly formatted parameter in the TrackingExData, the user agent MUST NOT store any of the target duplets in the database and MUST reject the promise with a DOMException named "SyntaxError".

Upon fulfillment, the user agent has added to its local database one or more site-pair duplets [site, target], each indicating that a request from that site domain to the target domain will include DNT:0 regardless of the user's general tracking preference. The fulfilled promise object contains the following TrackingExResult attribute:

isSiteWide

true if the user agent stored a potentially broader exception that applies to all domains (as opposed to just the listed targets); otherwise, false.

When a list of targets is supplied for a site-specific exception, the user agent MAY ignore that list, choosing instead to store a site-specific exception for all domains ([site, *]), if it also indicates that result by setting the returned promise's isSiteWide property to true.

User agents MAY instantiate Navigator.storeTrackingException even when Navigator.doNotTrack is null. Scripts SHOULD test for the existence of Navigator.storeTrackingException before calling the method.

There are some security concerns here regarding the ability of a script with an effective script origin matching one site being able to persist the DNT value received by resources on other (target) sites. In particular, this feature could be abused to set/unset an array of exceptions, similar to an array of bit values, and be "read" as a persistent identifier by embedding requests to those domains (which might all point to the same Internet host). However, we expect that would leave an obvious trail on the user agent, unlike other sources of fingerprinting.

Likewise, allowing an exception to be stored within an iframe of another site's page could be ripe for abuse unless the calling script ensures that it is being run within a page where it expects to be collecting user consent and where the context of that consent is consistent with the exceptions being stored.

This design is consistent with the fact that there is no technical restraint from sites calling the API without having first obtained an informed consent from the user. We are assuming that the social and regulatory environment will be sufficient to punish those who might misuse the API or abuse the scope of stored exceptions. A user agent might further limit such risks by checking for a site-wide tracking status resource when its presence is required by the API.

Status Object

A tracking status representation consists of a single status object containing properties that describe the tracking status applicable to the designated resource. Most of the properties are optional and can be extended over time, as illustrated by the following Orderly schema [[Orderly]]:

object {
    string tracking;                 // TSV
    array { string; } compliance?;   // hrefs
    string qualifiers?;              // compliance flags
    array { string; } controller?;   // hrefs
    array { string; } same-party?;   // domains
    array { string; } audit?;        // hrefs
    string policy?;                  // href
    string config?;                  // href
    string purposes?;                // href
}*;

The following example representation demonstrates a status object with all of the properties defined by this specification.

{
  "tracking": "T",
  "compliance": ["https://acme.example.org/tracking101"],
  "qualifiers": "afc",
  "controller": ["https://www.example.com/privacy"],
  "same-party": [
    "example.com",
    "example_vids.net",
    "example_stats.com"
  ],
  "audit": [
    "http://auditor.example.org/727073"
  ],
  "policy": "/privacy.html#tracking",
  "config": "http://example.com/your/data"
}

Purposes Property

An origin server MAY send a property named purposes with a string value containing a URI reference to a human-readable document that describes each of the purposes for tracking implemented by this origin server.

If the origin server supports the DNT-Consent qualifier then this property MUST be supported and be dynamically generated by decoding the field-value of the request's DNT header, to highlight or otherwise indicate the specific subset of purpose the user has agreed to.