ITP Debug Mode in Safari Technology Preview 62

Aug 5, 2018

by John Wilander

One of the more frequent questions we get from developers regarding Safari’s Intelligent Tracking Prevention (ITP) is how to debug your website with it enabled, especially since it is enabled by default in Safari. Today we’re happy to present you with an experimental version of ITP Debug Mode. Please try it out and send us feedback.

Enable ITP Debug Mode

This is how you enable ITP Debug Mode in Safari Technology Preview 62:

  1. Click the Safari Technology Preview menu → Preferences → Advanced
  2. Enable the Develop menu by clicking the checkbox next to “Show Develop menu in the menu bar”
  3. Click the Develop menu → Experimental Features → ITP Debug Mode

Disable ITP Debug Mode After Use

ITP Debug Mode should only be used when actively debugging your website for Intelligent Tracking Prevention behaviors. Remember to disable ITP Debug Mode when you’re done debugging. Why?

For privacy reasons, ITP Debug Mode logs on the INFO level to ensure domain names are not written to persistent log files. If you leave ITP Debug Mode enabled, you run the risk of having privacy-sensitive domain names included in your logs when running some system diagnostic tools, like capturing a sysdiagnose.

Domains Classified by Intelligent Tracking Prevention

When launching Safari Technology Preview, ITP Debug Mode logs which domains ITP has classified as having cross-site tracking abilities. To see these logs, do the following:

  1. Quit Safari Technology Preview
  2. Filter ITP Debug Mode log messages using the Console app or Terminal app
    1. If you prefer the Console app:
      1. Launch the Console app
      2. Click the Action menu → Include Info Messages
      3. Filter on “ResourceLoadStatisticsDebug” without the quotes
    2. If you prefer Terminal:
log stream -info | grep ResourceLoadStatisticsDebug
  1. Launch Safari Technology Preview

You will now see which domains ITP has already classified as having tracking abilities in one or more log statements, such as:

About to block cookies in third-party contexts for: 3rdpartytestwebkit.org.

3rdpartytestwebkit.org is set up to always be classified as a tracker in ITP Debug Mode and you can use it to test functionality such as the Storage Access API.

Depending on how much browsing you’ve done since starting fresh (see the “Starting Fresh” section below), you’ll see anything from just 3rdpartytestwebkit.org to hundreds of domain names listed in these log statements.

Further Logging as You Browse the Web

OK, so you’ve enabled ITP Debug Mode, set up Console or Terminal to capture the right logs, launched Safari Technology Preview, and seen the initial ITP Debug Mode logs. From this point you will see new log statements whenever Intelligent Tracking Prevention makes a new decision.

Such as when it purges website data:

About to remove data records for tracker.example, another-tracker.example.

When it classifies a new domain as having tracking abilities:

About to block cookies in third-party contexts for: a-third-tracker.example.

Or, when it prompts the user as a result of a call to the Storage Access API:

About to ask the user whether they want to grant storage access to 3rdpartytestwebkit.org under news.example or not.

Classifying A Custom Domain For Testing

One specific request we received from developers was for the ability to manually set a custom domain as permanently classified with tracking abilities. With ITP Debug Mode and User Defaults, that is now possible. Open Terminal and execute the following command (in this example to set example.com as permanently classified):

defaults write com.apple.SafariTechnologyPreview ResourceLoadStatisticsManualPrevalentResource example.com

When you launch Safari Technology Preview with ITP Debug Mode enabled, you will now see this added log statement in Console or Terminal:

Did set example.com as prevalent resource for the purposes of ITP Debug Mode.

You can inspect the setting in Terminal like this:

defaults read com.apple.SafariTechnologyPreview ResourceLoadStatisticsManualPrevalentResource

And you can delete the setting like this:

defaults delete com.apple.SafariTechnologyPreview ResourceLoadStatisticsManualPrevalentResource

Starting Fresh

When you’re debugging under Intelligent Tracking Prevention, it’s often useful to start fresh. You do that by deleting all Safari Technology Preview history. This not only deletes history and website data, but also resets ITP. Clearing your history will also sync with other devices over iCloud. To avoid that, we recommend creating a new user on your macOS system to use exclusively for debugging Intelligent Tracking Prevention. Be careful though. If you’re investigating an issue that is the result of real life browsing, resetting ITP may prevent you from reproducing the issue, since all of ITP’s data is deleted and the real life browsing that got you into the state with the issue may not be something you can replicate.

In ITP Debug Mode, 3rdpartytestwebkit.org and any custom domain you’ve set up through User Defaults stay classified even when you delete history. This behavior provides for controlled, repeatable testing.

Feedback and Bug Reports

Please report bugs about ITP Debug Mode using the WebKit bug tracker at bugs.webkit.org, and send feedback to our evangelist Jon Davis. If you have technical questions on debugging with ITP Debug Mode you can find me on Twitter @johnwilander.