7.4.1 API to Request a Site-specific Exception

partial interface Navigator {
    Promise<void> storeSiteSpecificTrackingException (StoreSiteSpecificExceptionPropertyBag properties);
};

dictionary StoreExceptionPropertyBag {
             DOMString? domain;
             DOMString? siteName;
             DOMString? explanationString;
             DOMString? detailURI;
             DOMString? expires;
             long?      maxAge;
};

dictionary StoreSiteSpecificExceptionPropertyBag : StoreExceptionPropertyBag {
             sequence<DOMString> arrayOfDomainStrings;
};

The storeSiteSpecificTrackingException method takes a dictionary argument of type StoreSiteSpecificExceptionPropertyBag that allows optional information to be provided.

If the request does not include the arrayOfDomainStrings, then this request is for a site-wide exception. Otherwise each string in arrayOfDomainStrings specifies a target. When called, storeSiteSpecificTrackingException MUST return immediately with a Promise resolving to a void or rejected with a DOMException SYNTAX_ERR.

If the list arrayOfDomainStrings is supplied, the user agent MAY choose to store a site-wide exception. If it does so it MUST indicate this in the return value.

If domain is not specified or is null or empty then the execution of this API and the use of the resulting permission (if granted) use the 'implicit' parameter, when the API is called, the document origin. This forms the first part of the duplet in the logical model, and hence in operation will be compared with the top-level origin.

If permission is stored for an explicit list, then the set of duplets (one per target):

[document-origin, target]

is added to the database of remembered grants.

If permission is stored for a site-wide exception, then the duplet:

[document-origin, * ]

is added to the database of remembered grants.

If domain is supplied and not empty then it is treated in the same way as the domain parameter to cookies and allows setting for subdomains. The domain argument can be set to fully-qualified right-hand segment of the document host name, up to one level below TLD.

For example, www.foo.bar.example.com can set the domain parameter as as "bar.example.com" or "example.com", but not to "something.else.example.com" or "com".

If the document-origin would not be able to set a cookie on the domain following the cookie domain rules [RFC6265] (e.g. domain is not a right-hand match or is a TLD) then the duplet MUST NOT be entered into the database and the returned Promise is rejected with DOMException SYNTAX_ERR SHOULD be thrown.

If permission is stored for an explicit list, then the set of duplets (one per target):

[*.domain, target]

is added to the database of remembered grants.

If permission is stored for a site-wide exception, then the duplet:

[*.domain, * ]

is added to the database of remembered grants.

A particular response to the API — like a DNT response header field — is only valid once the returned Promise is resolved; a user might later choose to edit stored exceptions and revoke some or all of them.

If expires is supplied and not null or empty the remembered grant will be cancelled (i.e. processed as if the relevant Cancel API had been called) no later than the specified date and time. After this the database of remembered grants will no longer contain any duplets for which the first part is the current document origin; i.e., no duplets [document-origin, target] for any target.

If maxAge is supplied and not null, empty or negative the remembered grant will be cancelled (i.e. processed as if the relevant Cancel API had been called) no later than the specified number of seconds following the grant.

If both maxAge and expires are supplied, maxAge has precedence. If neither maxAge or expires are supplied, the user agent MAY retain the remembered grant until it is cancelled.

7.4.2 API to Cancel a Site-specific Exception

partial interface Navigator {
    Promise<void> removeSiteSpecificTrackingException (RemoveExceptionPropertyBag properties);
};

dictionary RemoveExceptionPropertyBag {
             DOMString? domain;
};

When the returned Promise is resolved, the database of grants no longer contains the indicated grant(s); if some kind of processing error occurred then an appropriate exception will be thrown.

If there are no matching duplets in the database of remembered grants when the method is called then this operation does nothing (and does not throw an exception).

7.4.3 API to Confirm a Site-specific Exception

partial interface Navigator {
    Promise<boolean> confirmSiteSpecificTrackingException (ConfirmSiteSpecificExceptionPropertyBag properties);
};

dictionary ConfirmExceptionPropertyBag {
             DOMString? domain;
};

dictionary ConfirmSiteSpecificExceptionPropertyBag : ConfirmExceptionPropertyBag {
             sequence<DOMString> arrayOfDomainStrings;
};

If the call does not include the arrayOfDomainStrings, then this call is to confirm a site-wide exception. Otherwise each string in arrayOfDomainStrings specifies a target.

If the list arrayOfDomainStrings is supplied, and the user agent stores only site-wide exceptions, then the user agent MUST match by confirming a site-wide exception.

If the domain argument is not supplied or is null or empty then the execution of this API uses the 'implicit' parameter, when the API is called, the document origin. This forms the first part of the duplet in the logical model.

If the user agent stores explicit lists, and the call includes one, the database is checked for the existence of all the duplets (one per target):

[document-origin, target]

If the user agent stores only site-wide exceptions or the call did not include an explicit list, the database is checked for the single duplet:

[document-origin, * ]

If the user agent stores explicit lists, the call includes one, and the domain argument is provided and is not empty, then the database is checked for the existence of all the duplets (one per target):

[*.domain, target]

If the user agent stores only site-wide exceptions or the call did not include an explicit list, and the domain argument is provided and is not empty then the database is checked for the single duplet:

[*.domain, * ]

The returned Promise resolves to a boolean which has the following possible values:

• true all the duplets exist in the database;
• false one or more of the duplets does not exist in the database.

7.5.1 API to Request a Web-wide Exception

partial interface Navigator {
    Promise<void> storeWebWideTrackingException (StoreExceptionPropertyBag properties);
};

This API requests the addition of a web-wide grant for a specific site to the database.

7.5.2 API to Cancel a Web-wide Exception

partial interface Navigator {
    Promise<void> removeWebWideTrackingException (RemoveExceptionPropertyBag properties);
};

7.5.3 API to Confirm a Web-wide Exception

partial interface Navigator {
    Promise<boolean> confirmWebWideTrackingException (ConfirmExceptionPropertyBag properties);
};

The returned Promise resolves to a boolean indicating whether the duplet [ * , document-origin] or [ * , *.domain] (based on if domain is provided and is not null and not empty) exists in the database.

• true indicates that the web-wide exception exists;
• false indicates that the web-wide exception does not exist.