msAddTrackingProtectionList method

  • Article

Adds an external Tracking Protection list.

 

Syntax

*object.*msAddTrackingProtectionList(URL, bstrFilterName)

Parameters

  • URL [in]
    Type: BSTR

    The address of the Tracking Protection list.

  • bstrFilterName [in]
    Type: BSTR

    The display name.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

A Tracking Protection list is a specially formatted text file that contains the following elements, each on their own line.

Element Description
msFilterList File header. This exact keyword must appear by itself on the first line of the file.
# (hash) Comment line. This character at the beginning of a line indicates a comment.
: (colon) Property rule. The only property rule currently defined is "Expires=N" where N represents the number of days (max 30) to elapse before refreshing the Tracking Protection list from the server. If not specified, the default value is 7.
- (hyphen) Block rule. The block rule can filter strings or domain labels, or a combination of both, as follows:
  • If the block character is followed by whitespace and a string, the rule blocks downloads of any resource that contains the string in its URL.
  • If the block character is followed by d, whitespace, and a domain label, the rule blocks domains according to rules described in the Domain Labels section.
  • If a block domain rule is followed by whitespace and a string, the domain request is blocked only if the URL contains the specified string.
+ (plus) Allow rule. Only domain labels can be allowed. The allow rule follows the same syntax as the block rule for domains.

 

A Tracking Protection list requires at least one valid block or allow rule.

Domain Labels

A domain name consists of one or more parts, called labels, that are concatenated and delimited by dots, such as host.contoso.com. Domain rules match against each domain label, as follows:

  • A block domain rule matches any contiguous domain labels in a domain name, for example,contoso, host.contoso, or contoso.com.
  • An allow domain rule is less permissive than a block rule, and matches only the right-most characters of the URL, such as contoso.com.

Domain rules can also specify an optional substring to match. There can be only one substring per domain rule line. Strings can contain a wildcard (*) that matches any number of characters.

Examples

The following simple Tracking Protection list contains one blocked string and two domain rules. The allow domain rule is matched only if the URL also contains the string value of home. This list is refreshed from the server every five days.

msFilterList
: Expires = 5
# blocked strings
-    &keyword=
# domain rules
-d   blockDomain
+d   allowDomain.com  home

The following script demonstrates how to install the Tracking Protection list by clicking a button.

function installTrackingProtectionList()
{
    var myList = 'http://example.com/tracklist.tpl';
    var myTitle = 'Example Tracking Protection List';
    external.msAddTrackingProtectionList(myList, myTitle);
}

<button onclick="installTrackingProtectionList();">Install List</button>

See also

window

external

msTrackingProtectionEnabled