This proposal was sent to [email protected] on 5 October 2012.

New approach to Exceptions API

This proposal

Goals of the Exceptions API

  1. Send DNT:0 instead of DNT:1 in resource requests for which there is an exception
  2. Maintain the exceptions in a more persistent storage than generic browser storage (e.g. cookies)
  3. Prevent from being able to store exceptions for other sites
  4. Avoid browser UI that (probably) isn’t very customizable and that interrupts the user’s flow (and could need to be shown over and over on any given site)

Since DNT is a trust based system (we have to trust that sites correctly apply DNT:1) we should trust those same sites to only call the exceptions API when they have permission for an exception from the user. The site must obtain explicit informed consent from the user to ensure that the exception reflects the user’s preference. This means no UA trusted UI is required and the site has control of the entire user experience including explaining the context-specific value of agreeing to the exception.


Two APIs grant exceptions: one for site-wide and one for web-wide. The site-wide API allows a site to store that all resource requests made from visiting that site at the top-level browsing context should have DNT:0. The web wide API allows a site to store that all requests to its resources from any site should get DNT:0 and operates on the script browsing context (not top level) e.g. for the location of an iframe.

void SetSiteWideException(optional DOMString domain, optional sequence arrayOfSites);
void SetWebWideException(optional DOMString domain);

If domain is not specified or is null or empty then the script origin of the browsing context is used. If domain is supplied and not empty then it is treated in the same way as the domain parameter to cookies (allows setting for subdomains). This means that you can set an exception for any domain that domain-matches to the current script origin. The user agent should ensure that this is not a public suffix using an up-to-date public suffix list, such as the one maintained by the Mozilla project at (so is allowed and is not allowed). This means can set as the domain and can set or but cannot set

arrayOfSites is equivalent to the arrayOfDomainStrings in the current spec and if specified says which specific sites will get DNT:0 rather than for all requests. User Agents MAY choose to ignore the arrayOfSites even if provided and treat this as a general site-wide exception. The information is provided for browsers that choose to support this stricter exception. Strings in the arrayOfSites may be “wildcards” by starting with “*.” [Open Issue: is this the right syntax since it is different to domain].

User Agents MAY store these exception settings with no UI (the onus is on the site to ensure that the exception reflects the preference of the user). User Agents MAY confirm the exception with the user before using it but this is not required. User Agents MAY include a configuration UI that allows users to see their current exceptions and optionally modify the list (e.g. remove a previously granted exception).

bool QuerySiteWideException(optional DOMString domain, optional sequence arrayOfSites);
bool QueryWebWideException(optional DOMString domain);

The Query* methods return true if an exception is (still) in place matching the supplied parameters. This allows sites to determine if a user has rescinded an exception (for example through a management UI).

void RemoveSiteWideException(optional DOMString domain);
void RemoveWebWideException(optional DOMString domain);

The Remove* methods remove any exceptions that the user agent has stored for a matching domain.

Definition: “top-level site” means the hostname of the origin of the top-level browsing context.

SetSiteWideException Examples

  1. calls SetSiteWideException(). This means any resource requests made where is the top-level site (for example, an iframe or img) would receive DNT:0.
  2. calls SetSiteWideException(“”). This means any resource made where or any subdomain of (for example is the top-level site would receive DNT:0.
  3. calls SetSiteWideException(“”, [”*”, “*”]). This means that from any resource that matches * or * would get DNT:0. All other resources would still get the default signal. [[This assumes we allow wildcards, which is an open issue at this point]].
  4. calls SetSiteWideException(“”, [”*”, “*”]). This is the same as example 3 but for all resources matching on and any subdomains.

SetWebWideException Examples

  1. calls SetWebWideException(). This means any resource request where the origin is from any site will be sent DNT:0.
  2. calls SetWebWideException(“”). This means any resource request where the origin is or any subdomain of (for example from any site will receive DNT:0.
  3. includes an iframe that downloads a page from The page in the iframe calls SetWebWideException. This behaves the same as examples 1 and 2 because SetWebWideException works at the browsing context level not the top-level browsing context. This would allow choice sites to set these site wide exceptions for a number of sites using iframes and cross-document messaging (postMessage).