AdZapper | Gruby Solutions AdZapper User Guide

AdZapper User Guide

Table of Contents

What's New


Version 1.0.2


Various bug fixes and improvements

--

FIX - The AdZapper folder now appears on iCloud Drive

FIX - Filters now properly sync across devices

FIX - Rules on the Allowlist no longer appear twice


Version 1.0.3


Various Bug Fixes

Setup


iOS

  1. Open Settings
  2. Go to Safari -> Extensions
  3. Toggle AdZapper
  4. Click on the AdZapper Extension (below the content blocker)
  5. Click the Toggle
  6. Click on All Websites
  7. Click on Allow
  8. Quit and relaunch Safari
  9. Make sure the default list is enabled
  10. Open doubleclick.net. AdZapper is setup if the page says 'The URL was blocked by a content blocker'

macOS

  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

Troubleshooting & FAQ

FAQ

Q: What is the privacy policy for AdZapper?

See our privacy policy

Q: Does AdZapper block YouTube Ads?

Nope... but you can always find other filters that will block YouTube ads

Q: Does AdZapper block ads outside of Safari?

Nope... Find a different ad blocker if you want system-wide blocking

Q: How much does AdZapper cost?

AdZapper is free forever

Q: What is a rule and a filter?

Rules tell AdZapper what to block, and a filter is a list of rules combined into one document

Troubleshooting

AdZapper isn't blocking ads

Does AdZapper block doubleclick.net?

• If so, AdZapper may have missed an ad. You can use the Safari Web Inspector to add a new domain or CSS selector to AdZapper

• If not, try these steps:

  1. Make sure the default list is enabled
  2. Refresh AdZapper's filters (swipe down on the filter in iOS or click refresh button on macOS)
  3. Toggle AdZapper's content blocker and extension in Safari Settings
  4. Restart Safari
  5. Restart your device

AdZapper encounters an error when pressing "Disable AdZapper" in Safari

  1. Turn off AdZapper's extension
  2. Restart Safari
  3. Turn on AdZapper's extension
  4. Restart your device if that fails

AdZapper crashes when opening the app

AdZapper will crash if its folder in Documents (macOS) or On My iPhone/On My iPad is deleted. Usually, this can never happen, but if it does, uninstall and reinstall AdZapper

A message appears saying AdZapper would like to access data from other apps

This is a new security feature on macOS that prevents apps from accessing files outside of the sandbox. AdZapper needs to access a folder outside of the sandbox in order for it to communicate with the extension. This folder is located at ~/Library/Group Containers/com.grubysolutions.adzapper

At this time, if you do not allow access to this folder, AdZapper will crash.

To prevent this popup, enable full disk access for AdZapper in System Settings -> Privacy and Security -> Full Disk Access

AdZapper only needs Full Disk Access to access the folder above. AdZapper does not access any other folder outside of its sandbox.

Adding Filters to the Content Blocker



Adding Filters

The default AdZapper filter is based on the EasyList with some modifications to make it work with AdZapper

There are 3 ways to add filters

  • Load the filter from a website (and specify the url)
  • Import a local filter from your device
  • Use the share sheet
Loading filters from a website
  1. In the Filters tab, click on the plus button
  2. Copy and paste (or type) the filter URL
  3. Click Enable
  4. Refresh AdZapper by clicking the refresh button (macOS), or swiping down on the filter list (iOS)
Importing a local file
  1. In the Filters tab, click on the import button (looks like a square with an arrow pointing down)
    • On macOS, you can also go to File -> Import
  2. Select your file to import and click on Open or Import
  3. Click Enable
  4. Refresh AdZapper by clicking the refresh button (macOS), or swiping down on the filter list (iOS)

For Advanced Users:

You can edit filters with an external editor. On macOS, right click 'Imported from a file. Click to edit filter' to edit that filter with another app, like Text Edit

Blocking Domains

These domains will be blocked by AdZapper's content blocker

  1. Click on Blocklist
  2. Click on the plus button (on iPhone click Add Domain)
  3. Enter the domain you want to block
  4. Click enable and refresh AdZapper

Allowing Domains

These domains will prevent AdZapper from running rules specific to that site

  1. Click on Allowlist
  2. Click on the plus button (on iPhone click Add Domain)
  3. Enter the domain you want to disable AdZapper on
  4. Click enable and refresh AdZapper

Notes

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

Syntax



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 separated by #$# or #%#. The domain will not be blocked and Javascript will be injected onto 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

Examples

  • example.com a blocks all links on any domain containing example.com
  • example.com blocks any domain containing example.com
  • ||example.com blocks the domain example.com
  • 10.0.1.0 example.com a blocks all links on any domain containing example.com
  • 10.0.1.0 example.com blocks any domain containing example.com
  • #My comment here is a comment and is skipped over
  • !My comment here is a comment and is skipped over
  • ||example.com #My Comment Here blocks the CSS selectors #My, Comment, and Here
  • ||example.com a h1 blocks all links and h1 headers on example.com (note the spaces in between)
  • ||example.com#$#console.log(`Hello World`) will log Hello World into the Safari Web Inspector console on example.com
  • example.com#%#console.log(`Hello World`) will log Hello World into the Safari Web Inspector console on example.com
  • #%#console.log(`Hello World`) will log Hello World into the Safari Web Inspector console on every website you visit
  • ||example.com^$script,$cookie will block javascript and cookies on example.com and it's subdomains. This is experimental and may not work
  • ||example.com^$script,domain="example.org" will block javascript from example.com if it is loaded from example.org. This is experimental and may not work
  • @@||example.com will unblock example.com from all previous rules
  • @@||example.com^$domain=example.net|example.org will unblock any resource from example.com if it is loaded from example.net or example.org (Only available on AdZapper 1.0.4+)

Targeting Resources

This is currently experimental and may not work properly
You can target a specific resource on a website. AdZapper supports blocking the following resources and load types:

  • $document
  • $image
  • $script
  • $font
  • $raw
  • $media
  • $popup
  • $style-sheet
  • $svg-document
  • $first-party
  • $third-party

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

Change the appearance and warning message by going into AdZapper's settings (AdZapper -> Settings on macOS and Settings -> Apps -> AdZapper on iOS)

Syncing via iCloud

If you have iCloud Drive setup, AdZapper automatically syncs. Visit https://help.apple.com/icloud to learn more.

Disable AdZapper

macOS

  • To disable AdZapper temporarily, click on AdZapper in the Safari toolbar and click Disable AdZapper on All Websites
  • To completely disable AdZapper, go to Safari -> Settings -> Extensions and toggle AdZapper

iOS

  • To disable AdZapper temporarily, click on AdZapper in the Safari toolbar and click Disable AdZapper on All Websites
  • To completely disable AdZapper, go to Settings -> Apps -> Safari -> Extensions and toggle AdZapper

Uninstalling AdZapper

macOS

See https://support.apple.com/en-us/102610 for more information on how to uninstall apps from your computer

There may be leftovers folders (see below) if you delete AdZapper via Finder

  • ~/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

iOS

See https://support.apple.com/en-us/101550 for more information on how to uninstall apps from your iPhone or iPad