Create and Host Tracking Protection Lists

Article
08/15/2017

Tracking Protection Lists help give consumers more control over their privacy. This information describes how to create Tracking Protection Lists (TPLs) and host them on your own or a central website such as the Internet Explorer Gallery.

What Are Tracking Protection Lists
Using Tracking Protection Lists in Windows Internet Explorer 9
Creating Tracking Protection Lists
- Examples
- The Wildcard Character
- Example Tracking Protection List File
- Multiple Lists and Rule Precedence
- Performance Tips
Deploying Tracking Protection Lists
Detecting Whether Tracking Protection Lists Are Enabled
Best Practices

What Are Tracking Protection Lists

A Tracking Protection List (TPL) is a simple UTF-8-format text file that you can host on a web server. Users can install a TPL directly from a website. As a user browses the web, some third-party content is allowed or blocked according to the rules defined in the TPLs that the user has installed. Periodically, Windows Internet Explorer checks installed TPLs for updates and can automatically download and apply changes so the latest protection is offered to the user.

Microsoft maintains a gallery of Tracking Protection Lists to which anyone can add TPL files. You can host on your own website, or upload it to the Microsoft gallery.

Using Tracking Protection Lists in Windows Internet Explorer 9

To turn Tracking Protection Lists on or off

In Windows Internet Explorer 9, click the Tools button , point to Safety, and then click Tracking Protection.
In the Manage Add-ons dialog box, click a Tracking Protection List , and then click Enable.

To view the contents of an installed Tracking Protection List

In Internet Explorer 9, click the Tools button , point to Safety, and then click Tracking Protection.
In the Manage Add-ons dialog box, click a downloaded Tracking Protection List, and then click More information.

For more information, see Tracking Protection on the Internet Explorer 9 features page.

Creating Tracking Protection Lists

A Tracking Protection List is an 8-bit Unicode Transformation Format (UTF-8) text file that contains a version header, comments, settings, and a set of allow or block rules.

TPL files are parsed in a stateless manner across lines, meaning that the order of the lines has no effect. The only exception is that the version header "msFilterList" must be the first line of the file. Rules are used to indicate third-party content that is to be blocked or allowed. Third-party content is defined as having a different second-level domain name than the URL in the address bar.

Rules are matched against the URL of any third-party content that is downloaded in conjunction with the primary webpage. For blocking rules, a domain and/or a subdomain are specified. Optionally a string can be specified to further limit the scope.

Element	Description	Expected values	Example
msFilterList	Identifies the file as a Tracking Protection file. This is the only required element and must be the first line in the file.	msFilterList
# (pound sign)	Comment. Anything on this line is ignored.	# string	`# this is a comment`
: expires = n	Defines how often (in days) that Internet Explorer checks for an update to the list.	If missing, the default value is 7. Acceptable values are 1- 30.	`: expires = 5`
-d string [string]	Domain block rule. Domains and optional substrings can be specified.	String can be a domain with an optional discrete string to match.	`-d contoso.com -d ad.contoso.com -d contoso.com tracking`
+d string	Domain allow rule. Only domains can be specified.	Domain only	`+d contoso.com`
- (minus sign) string	Substring block rule.	Specifies a substring to match within a URL.	`- trackingbot`
*	Wildcard character	Specifies any value within a string or subdomain. Not allowed in a domain.	`+d contoso.com track* +d sub*domain.contoso.com`

Examples

Domain rules begin with a "+d" or "–d" and allow ("+") or block ("-") content on a particular third-party domain. If the domain rule is an allow rule, the string specified in the domain rule will be "anchored" on the right side of the matched domain. If the domain rule is a block rule, it will match any contiguous domain labels in the URL.

Domain Allow Rules Example

For example, given the following URL:

"http://www.glossary.contoso.com/file.html"

The following allow domain rules will match:

+d contoso.com

+d glossary.contoso.com

+d contoso.com file

+d contoso.com file.html

+d contoso.com html

The following allow domain rules will not match:

+d glossary.contoso

+d orderform.contoso.com

+d contoso.com /path/file.html

For example, given the following URL:

"http://www.glossary.contoso.com/file.html"

The following block domain rules will match:

-d contoso.com

-d glossary.contoso.com

-d contoso.com file

-d contoso.com file.html

-d contoso.com html

-d glossary.contoso

The following block domain rules will not match:

-d orderform.contoso.com
-d contoso.com /path/file.html

Substring rules

Substring rules specify a match of a portion or substring of a URL. Substring rules can be only block (-) rules. Substring allow (+) rules are not permitted.

For example, given the following URL:

"https://www.contoso.com/test.html"

The following substring rules will match:

-contoso

-conto

-test.html

-co*so

The Wildcard Character

The wildcard character "*"can be used within a substring rule, and means "match 0 or more of any character."

The wildcard character cannot be used in the domain part of a domain rule. It can be used in the substring part of a domain rule.

For example, the following rule will match because the wildcard is used in the substring part of the domain rule:

"+d contoso.com sub*string"

The following rule is invalid because the wildcard is used in the domain part of the domain rule:

"+d contoso*.com substring "

Example Tracking Protection List File

Below is a complete example TPL. The comments in the TPL describe the various rules and settings in the TPL.

msFilterList
# Above is a version header. 
# This is a comment. Any line that starts with
# a “#” character will be ignored.
# “Expires” sets the number of days when to check the server for an update
: Expires=3
# allow everything from contoso.com
+d contoso.com
# block anything containing the string “spam_ads”
- spam_ads
# block any file with name that starts with a “1x1” and has a “.gif” extension- 1x1*.gif
# block anything from treyresearch.net
-d treyresearch.net
# block bad_script.js from litwareinc.com
-d litwareinc.com bad_script.js

Multiple Lists and Rule Precedence

Users can install multiple Tracking Protection Lists, and can use them in conjunction with their Personalized Filtering List. When multiple lists are used, all of the rules from all of the TPLs are grouped together into a single list.

The precedence of rules for Tracking Protection is as follows:

Rules from the Personalized Filtering List if enabled in Manual Mode
TPL allow rules
TPL block rules
Rules from the Personalized Filtering List if enabled in Automatic Mode

For example, if a domain is allowed on one list, and blocked in another, the domain will be allowed. Similarly, if a user manually blocks a domain in a personalized list, and it is allowed in another, the domain will be blocked.

Performance Tips

Tracking Protection Lists can have a negative effect on browser performance if authored poorly. The following tips will help you write a fast-performing list:

Use domain rules wherever possible. Domain rules make it easy to match content on a domain, and they are optimized by Internet Explorer to run very quickly.
Limit the use of short substring rules. Writing many (> 25) short (fewer than eight characters) substring rules can have a negative impact on performance.
Expand out complex wildcard rules into multiple non-wildcard rules. Using wildcards, especially in the first eight characters of a rule, can negatively affect performance. When possible, refrain from using wildcards by writing multiple substring rules.

Deploying Tracking Protection Lists

Tracking Protection Lists can be hosted on any web server. A JavaScript method is added to a webpage that will prompt the user to add the TPL.

        window.external.msAddTrackingProtectionList(URL, description);

Parameters:

URL This is the URL of the list to be added. The URL can be a relative or absolute URL. An absolute URL does not need to be hosted on the same server as the page that calls the msAddTrackingProtectionList method.
description The description provided will be shown in the prompt to the user.

See the API reference page for more information.

function loadTPFile() {
        var URL = document.getElementById("tplfile").value;        
        var description = 'Example Tracking Protection List';
        window.external.msAddTrackingProtectionList(URL, description);
    }

When this code is called, the user will see a dialog box similar to the following.

Detecting Whether Tracking Protection Lists Are Enabled

In addition to providing a link to download the TPL, a webpage can detect whether the user has enabled any Tracking Protection Lists, personal or otherwise. This could be good information for a network administrator to enforce the use of a corporate Tracking Protection List.

The following JavaScript method can be used in an if statement to determine whether any lists are enabled.

if (window.external.msTrackingProtectionEnabled())

Returns:

True At least one TPL has been enabled on the user’s browser.
False No lists are enabled.

Note that lists can be installed, but not enabled. This method will tell you only whether any are enabled. For more information on this method, see the msTrackingProtectionEnabled method reference.

The following example contains two functions, one to check whether any lists are enabled, the other to import our fictious list. If you have lists off, click the "Check tracking protection" button first to confirm. Then click and load the sample file. When you click "Check tracking protection" again, you will see that it has been enabled.

<!DOCTYPE html>
<html >
<head>
    <title>Internet Explorer 9 Tracking Protection Example</title>
    <script type="text/javascript">
    
    function checkTP() {
    //checks whether Tracking Protection has been enabled (any list is on) 
        if (window.external.msTrackingProtectionEnabled())
      {
            document.getElementById("results").innerHTML = "Tracking protection is: ON";
        } else {
            document.getElementById("results").innerHTML = "Tracking protection is: OFF";
        }
    }

    //loads a list specified by input field
    function loadTPFile() {
        var URL = document.getElementById("tplfile").value;        
        var description = 'Example Tracking Protection List';         
        window.external.msAddTrackingProtectionList(URL, description);
    }
</script>

</head>
<body>
<div>
  <button onclick="checkTP();">Check tracking protection</button> 
  <span id="results">Tracking protection is: </span>
</div>
<p />
<div>
  <button onclick="loadTPFile();">Load TPL file</button>
  <input id= "tplfile" type="text" value="sample.tpl" size="60" />
</div>

</body>
</html>

To remove the sample.tpl list

In Internet Explorer 9, click the Tools button , point to Safety, and then click Tracking Protection.
In the Manage Add-ons dialog box, click Example Tracking Protection List , and then click Remove.

Best Practices

Although there are no restrictions on creating lists, the following best practices help provide the best customer experience for your users:

Notice. Consider providing notice of the limits of your tracking protection list (that is, it is a privacy tool, not a privacy guarantee) to your users so they do not have unrealistic expectations. You might also want to consider including standard warranty disclaimers in your notice.

Some sites may choose to present this notice as part of their site's terms of use, while others might incorporate it into a click-through dialog box that is presented to users before they download the TPL.
Criteria. Consider publishing documentation on your site that explains the criteria you use to determine which sites will be included on the list. Having your criteria documented and following them when creating your TPL will help prevent confusion on the part of TPL users and third-party website publishers.
Inquiries. You might want to provide a process for third parties to follow if they have questions or concerns about your TPL. For example, a website owner might feel that their site has been incorrectly included on your list. A typographical error could lead to the wrong site being included, or a site’s privacy policy and practices may have changed after publication of your TPL.

Having a clear process in place for reviewing these inquiries and updating the TPL when appropriate will reduce your administrative burden and may help head off complaints from website owners.

Microsoft has implemented a similar process that allows web administrators and website owners to report issues with SmartScreen Filter, a feature in Internet Explorer that helps detect phishing websites.
Discoverability. You can make it easier for others to discover your Tracking Protection Lists by adding them to the Internet Explorer Tracking Protection Gallery.

Create and Host Tracking Protection Lists

What Are Tracking Protection Lists

Using Tracking Protection Lists in Windows Internet Explorer 9

Creating Tracking Protection Lists

Examples

Domain Allow Rules Example

Substring rules

The Wildcard Character

Example Tracking Protection List File

Multiple Lists and Rule Precedence

Performance Tips

Deploying Tracking Protection Lists

Detecting Whether Tracking Protection Lists Are Enabled

Best Practices

Additional resources