Ad blocking

Litr blocks ads and trackers on every site, YouTube included. It is on by default.

To turn it off or on, open settings (⌘,) and change Block ads. Open pages reload so the change applies to them.

To allow ads on one site only, use View → Settings for This Site… → Allow on This Site (see Settings for a site).

What is blocked

• Ad and tracking requests. Scripts, images, frames and beacons from ad networks and trackers are never downloaded. Examples are Google AdSense and DoubleClick, Amazon ads, Criteo, Taboola, Outbrain, Google Analytics, Google Tag Manager, the Facebook pixel and Hotjar.
• Ad placeholders. Empty ad boxes left on the page are hidden.
• YouTube ads (see below).
• Tracking in links (see below).

The rules come from EasyList (ads) and EasyPrivacy (trackers), about 117,000 of them. They are converted to WebKit's content blocker format and built into Litr, so they update when Litr does.

Blocking happens inside WebKit before anything is fetched, which makes pages lighter and faster rather than slower.

YouTube

YouTube serves its ads from the same servers as its videos, so blocking by address doesn't work there. On YouTube pages, and on YouTube players embedded in other sites, Litr runs a small script that:

1. removes ad data from the player's responses before the player sees it,
2. hides ad slots, promotions and YouTube's "ad blockers are not allowed" dialog,
3. mutes and skips any ad that still starts, then turns the sound back on.

YouTube changes its site often. If ads come back after a YouTube change, the script needs an update in a new Litr release.

Tracking in links

Newsletters, ads and social sites add parameters to links that do nothing but tell the next site where you came from: utm_source and the other utm_ ones, fbclid (Facebook), gclid (Google Ads), msclkid (Microsoft), mc_eid (Mailchimp), _hsenc (HubSpot), igshid (Instagram), the si YouTube and Spotify add to shared links, and a few dozen more. When you follow a link to another site, Litr takes them out before the page is asked for, so they never leave your Mac. The rest of the link stays as it was.

• Only links to another site, followed or opened from another app: not links within a site, going back or forward, reloading, or sending a form.
• Not on sites where you allowed ads (Allow on This Site), nor with ad blocking off.
• The privacy report counts the links cleaned, and says which parameters were taken out of the link to the page you're on.

Privacy

Litr never downloads filter lists or reports what it blocks to anyone. The rules ship with the app and blocking happens on your Mac.

To see what was blocked, open the privacy report: the shield in the address bar, or View → Privacy Report.

How it works

WebKit compiles the rules into bytecode that every page process reads straight from disk, so blocking costs little memory. Compiling about 117,000 rules takes a few seconds and a lot of memory once. Litr therefore compiles them in a short-lived helper process, started with litr --compile-blocklist, which exits when it is done.

The compiled rules (about 47 MB) are kept in ~/Library/Application Support/Litr/ContentRules. Litr and all its web apps share them, and they are compiled again only when the rules change.

On the very first launch, and after an update with new rules, pages opened during those few seconds load without blocking. They reload automatically when the rules are ready.

When a site breaks

Ad blockers occasionally break a site: a video that won't play, or a missing comment section or login. Turn Block ads off, reload the site, and turn blocking back on when you are done. Per-site exceptions are not available yet.

Licence

EasyList and EasyPrivacy are by the EasyList authors and dual licensed under GPLv3 and CC BY-SA 3.0. The converted rules in Litr carry the same licence; see resources/blocklist-LICENSE.txt.