Tracking protection list API

The Tracking Protection API enables developers who build ActiveX controls to write code that works with Windows Internet Explorer Tracking Protection.

Introduction

A Tracking Protection list (TPL) is a list of websites that a user creates to prevent the listed sites from accessing the user's Internet usage. Lists are hosted on websites and can be uploaded and downloaded by users. When a TPL is installed, some third-party content is filtered as the user browses according to the rules defined in the TPL. Tracking Protection list rules dictate whether content from certain websites is blocked or allowed when a user visits a webpage. Windows Internet Explorer 9 and Internet Explorer 10 periodically check the website where the TPL was downloaded for updates. For more info about writing and using TPL files, see Create and Host Lists. This illustration shows the process of uploading and then accessing a TPL from a host website.

Tracking Protection API

Internet Explorer doesn't automatically block sub-downloads generated by ActiveX controls. ActiveX controls have full use of many Windows APIs for networking needs, including sockets, WinInet, URLMon, and so on. To integrate with Tracking Protection, ActiveX controls can use the following TPL tracking API.

The API enables your control to know if a particular Uniform Resource Identifier (URI) should be allowed or blocked. Internet Explorer handles blocking the UI display (indication of blocked or allowed content), and integrating multiple enabled and disabled TPLs.

API usage

The TPL tracking API is defined in the IDL as follows:

 cpp_quote("#define SID_STrackingProtection IID_ITrackingProtection")
    
    [
        object,
        pointer_default(unique),
        uuid(30510803-98b5-11cf-bb82-00aa00bdce0b)
    ]
    interface ITrackingProtection : IUnknown
    {
        [] HRESULT EvaluateUrl([in] BSTR bstrUrl, [out] BOOL *pfAllowed);
        [] HRESULT GetEnabled([out] BOOL *pfEnabled);
    };

You can obtain an "ITrackingProtection" interface pointer as an ActiveX control by following these steps:

  1. From an IOleClientSite interface, call QueryInterface() to request an IServiceProvider interface (IID_IServiceProvider).
  2. Call IServiceProvider::QueryService to get an ITrackingProtection interface, and specify SID_STrackingProtection for the guidService parameter and IID_ITrackingProtection for the rid parameter.

Note  These calls must occur on the STA thread. However, the object returned through the QueryService call and by implementing ITrackingProtection is free-threaded. It can thus be subsequently accessed from any thread.

 

ITrackingProtection::EvaluateUrl

To properly implement Tracking Protection for your ActiveX control, use EvaluateUrl with the following caveats:

  • Ensure that you call EvaluateUrl() before you attempt to download any Url. If *pfAllowed is FALSE or the function fails with a failed hr, don't download or connect to the url. It's essential that this API is called on every download when Tracking Protection is enabled. The Internet Explorer address bar UI will be set appropriately based on the calling of this API.
  • Ensure that on redirects, EvaluateUrl() is called as well. Once again, if *pfAllowed is FALSE or the function fails with a failed hr, your code should abort immediately and not download or connect to the redirected url.

Note  If you are using URLMON, set the BINDINFO_OPTIONS_DISABLEAUTOREDIRECTS flag to ensure your code is called for redirects.

 

ITrackingProtection::GetEnabled

For better performance, you can call "GetEnabled()" to decide whether to call EvaluateUrl and/or set the BINDINFO_OPTIONS_DISABLEAUTOREDIRECTS flag.

You can also cache the return value of GetEnabled() within your code. Discard your cached copy whenever your ActiveX control is disconnected from the markup, so that your control can get a new cached value.

Clean up

Make sure that all references to the ITrackingProtection interface are released from your code with a NULL parameter after Internet Explorer calls your control’s IOleClientSite::SetClientSite implementation.

Do Not Track header support

The “Do Not Track” header is a message that web browsers can send to websites, which indicates that a user prefers not to be tracked.

When ITrackingProtection::GetEnabled() returns TRUE (for example, Tracking Protection is ON), Internet Explorer automatically adds a “DNT: 1” header to any WinInet or URLMon-generated HTTP requests.

If your control uses a different networking stack for HTTP requests, it should include the “DNT: 1” header in all network requests when ITrackingProtection::GetEnabled() returns TRUE.

An Emerging Internet Standard that Helps Protect Consumers from Tracking

Create and Host Tracing Protection Lists

Get a Tracking Protection Lists

HTML5 Privacy: Transparency in a Complex On-Line World

IE9 and Privacy: Introducing Tracking Protection