Setup

1. Open Safari
2. Open Safari Preferences
3. Click Extensions
4. Click the checkmark next to the Content Blocker and the extension
5. Click on the AdZapper extension
6. Click Always Allow on Every Website
7. Follow the prompt 

Adding Filters to the Content Blocker

Jump to a section

• Adding Filters
• Blocking Domains
• Allowing Domains

Adding Filters

There are three ways to add filters

• Specify the filter url (ex: example.com/filter.txt)
• Import a local filter on your computer
• Import a file from the Share Sheet

Importing a local file:

1. Go to File -> Import Filters
2. Choose a filter from your computer. Only text files are allowed 
3. Enable your filter by clicking on Filters. Click the check box next to the filter you imported
4. Click the refresh button for your changes to take effect 

Specifying a filter URL 

1. Click on Filters in the sidebar.
2. Click on the plus button. 
3. Copy and paste (or type) the filter URL
4. Click Enable 
5. Click the refresh button for your changes to take effect 

Importing a file from the Share Sheet

1. Right click on a text file in Finder (or another app of your choosing) and press Share
2. Select AdZapper
3. Enter a name for your new filter
4. Press Post

If AdZapper doesn’t appear in the share menu

1. Right click on any file and select the share menu
2. Under the share menu, press More
3. Settings (macOS 13+ or System Preferences for macOS 12) will open
4. Scroll down and toggle AdZapper

For advanced users: 

Right Clicking “Imported from a file. Click to edit filter” will bring up an option that allows you to edit that filter with an external application, like Text Edit.

Adding Blocked Domains

These domains are also blocked by AdZapper 

1. Click on Blocklist in the sidebar
2. Click the plus button
3. Enter the domain you want to block (ex: to block google.com, type in google.com) 

For advanced users: 

See syntax notes on how to use CSS selectors on the blocklist

Adding Allowed Domains 

1. Click on Allowlist in the sidebar 
2. Click on the plus button
3. Enter the website domain that you want to disable AdZapper on.
4. Click Enable 

For advanced users: 

Toggling Invert Allow List will only block ads on the websites that are specified in the allowlist

Notes

• You MUST refresh AdZapper to see your changes take effect (Press Command-R or the refresh button)
• See these notes on filter syntax

Syntax

Jump to a Section

• Overview
• Examples
• Targeting Resources
• Unblocking websites

AdZapper works with all filters following these rules:

• All comments start with a # or !
• Digits before a domain will be ignored (ex: ‘10.0.1.0 example.com’ will only include ‘example.com’) 
• CSS Selectors must come after the domain. They must be separated by a space (” “), or by ##. The domain will not be blocked; only the CSS selector will (ex: ‘example.com a’ will block all links on example.com)
• Javascript code must come after the domain and be seperated by #$# or #%#. The domain will not be blocked and Javascript will be injected on to that webpage. (ex: ‘example.com#$#console.log(`Hello World`)’ will log Hello World into the Safari Web Inspector console on example.com)
• Block a specific resource (like an image) by using $ before the resource and after the domain (ex: ‘example.com^$script will block all javascript on example.com). See later section for more details.
• The :has CSS pseudo-selector only works in Safari 16.5 or later

Multiple resources must be separated by a comma (“,”). Every resource must start with a dollar sign (“$”)

Unblocking websites

Use @@ before a rule to create an exception rule. For example, @@||example.com will unblock example.com from any previous rule (like ||example.com^$script).

This page will be updated as AdZapper supports new rules. For more information, check out the AdBlock Plus guide and the AdGuard guide on how to write filters.

Other Settings

AdZapper includes a few other settings:

• The ability to change the appearance of the app
• Enable a warning before deleting a filter
• Syncing data between devices via iCloud

Changing the appearance of the app

1. Go to AdZapper -> Settings (macOS 13+ or Preferences – macOS 12) -> General
2. From the drop down menu, select your preferred appearance

Enabling a warning before deleting a filter

1. Go to AdZapper -> Settings (macOS 13+ or Preferences – macOS 12) -> General
2. Toggle Warn before deleting filters
3. When you delete a filter, a message will appear confirming if you want to delete that filter

Syncing data via iCloud

If you have iCloud Drive setup, AdZapper should automatically sync. For more help, visit https://help.apple.com/icloud.

Enable/Disable iCloud Syncing

1. Quit AdZapper
2. Go to System Settings (System Preferences for macOS 12)
3. Click on [YOUR NAME] (Apple ID for macOS 12)
4. Click on iCloud
5. Next to iCloud Drive, click Options
6. Scroll down and choose AdZapper
7. Click Done

Disable Ad Blocking

AdZapper can be disabled to stop ad blocking.

1. Open Safari
2. Click on AdZapper in the toolbar
3. Click Disable AdZapper on All Websites

Uninstalling AdZapper

In Launchpad, click and hold on AdZapper. Click the “x” and press delete to uninstall. AdZapper should be completely deleted. If not, delete the folders below:

• ~/Library/Application Scripts/com.grubysolutions.adzapper.contentblocker
• ~/Library/Application Scripts/com.grubysolutions.adzapper.extension
• ~/Library/Application Scripts/group.com.grubysolutions.adzapper
• ~/Library/Application Scripts/com.grubysolutions.adzapper
• ~/Library/Group Containers/group.com.grubysolutions.adzapper
• If you are not using iCloud:
  • ~/Library/Containers/com.grubysolutions.adzapper.extension
  • ~/Library/Containers/com.grubysolutions.adzapper.contentblocker
  • ~/Library/Containers/com.grubysolutions.adzapper