7.4 Site-specific Exceptions

7.4.1 API to Request a Site-specific Exception

partial interface Navigator {
    Promise<void> storeSiteSpecificTrackingException (StoreSiteSpecificExceptionPropertyBag properties);
};
storeSiteSpecificTrackingException
Called by a page to store a site-specific tracking exception.
ParameterTypeNullableOptionalDescription
propertiesStoreSiteSpecificExceptionPropertyBag
Return type: Promise resolving to void
dictionary StoreExceptionPropertyBag {
             DOMString? domain;
             DOMString? siteName;
             DOMString? explanationString;
             DOMString? detailURI;
             DOMString? expires;
             long?      maxAge;
};
detailURI of type DOMString, nullable
A location at which further information about this request can be found.
domain of type DOMString, nullable
a cookie-domain as defined in [RFC6265], to which the exception applies.
expires of type DOMString, nullable
A date and time, encoded as described for the cookie Expires attribute described in [RFC6265], indicating the maximum lifetime of the remembered grant.
explanationString of type DOMString, nullable
A short explanation of the request.
maxAge of type long, nullable
A positive number of seconds indicating the maximum lifetime of the remembered grant.
siteName of type DOMString, nullable
A user-readable string for the name of the top-level origin.
dictionary StoreSiteSpecificExceptionPropertyBag : StoreExceptionPropertyBag {
             sequence<DOMString> arrayOfDomainStrings;
};
arrayOfDomainStrings of type sequence<DOMString>,
A JavaScript array of strings.

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);
};
removeSiteSpecificTrackingException

If domain is not supplied or is null or empty then this ensures that the database of remembered grants no longer contains any duplets for which the first part is the current document origin; i.e., no duplets [document-origin, target] for any target.

If domain is supplied and is not empty then this ensures that the database of remembered grants no longer contains any duplets for which the first part is the domain wildcard; i.e., no duplets [*.domain, target] for any target.

A Promise resolving to void is returned. When the Promise has been resolved, it is assured that there are no site-specific or site-wide exceptions for the given top-level origin.

ParameterTypeNullableOptionalDescription
propertiesRemoveExceptionPropertyBag
Return type: Promise resolving to void
dictionary RemoveExceptionPropertyBag {
             DOMString? domain;
};
domain of type DOMString, nullable
a cookie-domain as defined in [RFC6265], to which the exception applies.

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);
};
confirmSiteSpecificTrackingException
Called by a page to confirm a site-specific tracking exception.
ParameterTypeNullableOptionalDescription
propertiesConfirmSiteSpecificExceptionPropertyBag
Return type: Promise resolving to boolean
dictionary ConfirmExceptionPropertyBag {
             DOMString? domain;
};
domain of type DOMString, nullable
a cookie-domain as defined in [RFC6265], to which the exception applies.
dictionary ConfirmSiteSpecificExceptionPropertyBag : ConfirmExceptionPropertyBag {
             sequence<DOMString> arrayOfDomainStrings;
};
arrayOfDomainStrings of type sequence<DOMString>,
A JavaScript array of strings.

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 Web-wide Exceptions

7.5.1 API to Request a Web-wide Exception

partial interface Navigator {
    Promise<void> storeWebWideTrackingException (StoreExceptionPropertyBag properties);
};
storeWebWideTrackingException
The single duplet [ * , document-origin] or [ * , *.domain] (based on if domain is provided and is not null and not empty) is added to the database of remembered grants. The properties of the StoreExceptionPropertyBag dictionary are as described above in the request for site-specific exceptions.
ParameterTypeNullableOptionalDescription
propertiesStoreExceptionPropertyBag
Return type: Promise resolving to void

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);
};
removeWebWideTrackingException
Ensures that the database of remembered grants no longer contains the duplet [ * , document-origin] or [ * , *.domain] (based on if domain is provided and is not null and not empty). A Promise resolving to void is returned. When the Promise has been resolved, the indicated pair is assured not to be in the database. The same matching process defined for determining which header field to send is also used to detect which entry (if any) to remove from the database.
ParameterTypeNullableOptionalDescription
propertiesRemoveExceptionPropertyBag
Return type: Promise resolving to void

7.5.3 API to Confirm a Web-wide Exception

partial interface Navigator {
    Promise<boolean> confirmWebWideTrackingException (ConfirmExceptionPropertyBag properties);
};
confirmWebWideTrackingException
Confirms that there exists in the database a web-wide exception for a specific site.
ParameterTypeNullableOptionalDescription
propertiesConfirmExceptionPropertyBag
Return type: boolean

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.