Custom rules
Custom rules sit alongside the built-in categories. Add one in Settings, under Filters, then Custom rules: type the rule under Add a rule and tap Add.
Blue Guard reads a subset of Adblock filter syntax. Each rule is translated into a Safari content rule as you add it, and a rule that cannot be translated faithfully is rejected rather than accepted and quietly ignored. Everything below has an exact equivalent in Safari's content rule format, which is what keeps the subset small.
One rule per entry, on one line, up to 512 characters. Comment lines starting
with ! or [ are not rules and are rejected.
Blocking a domain
||example.com^
Blocks requests to example.com and its subdomains. This is the only pattern
form Blue Guard accepts: it must begin with || and end with ^, and between
them may contain only ASCII letters, digits, full stops and hyphens.
Wildcards, path fragments, regular expressions and bare-string patterns are not accepted.
Making an exception
@@||example.com^
Ignores earlier rules for that domain. This is the same mechanism behind allowed sites. If you only want to stop blocking a whole site, Allowing a site does it without writing a rule.
Options
Options go after a $, separated by commas.
||example.com^$third-party,script
Party
| Option | Meaning |
|---|---|
third-party | Only when the request goes to a different site than the page |
~third-party | Only when the request stays on the page's own site |
Resource type
script, image, stylesheet (or css), font, media, document,
xmlhttprequest (or xhr), websocket, ping, other. More than one may be
listed.
Site
| Option | Meaning |
|---|---|
domain=a.com|b.com | Only on those sites, and their subdomains |
domain=~a.com|~b.com | On every site except those, and their subdomains |
A single domain= list is either all included or all excluded. Mixing
a.com|~b.com is rejected, because Safari's format keeps the two as separate
fields and there is no faithful translation of the mixture.
Any other option is rejected, including ones you may know from desktop
blockers, such as popup, important and redirect.
Hiding an element
example.com##.advert-banner
Hides elements matching the CSS selector on that site. Several sites can share one rule, separated by commas:
example.com,example.org##.advert-banner
Leaving the site list out applies the rule everywhere:
##.advert-banner
Element hiding sets display: none and nothing more. A banner that also locks
the page by setting overflow: hidden on the body will disappear and leave the
page unscrollable. Where the element comes from a third party, blocking its
domain is the better fix.
The cosmetic exception form #@# is not supported.
Which rules reach app-wide blocking
Custom rules are published to app-wide blocking as well as to Safari, but the domain filter only sees hostnames, so only the rules that read as whole domains carry across:
| Rule | Safari | App-wide |
|---|---|---|
||example.com^ | Yes | Yes |
@@||example.com^ | Yes | Yes |
||example.com^$script | Yes | No |
example.com##.advert | Yes | No |
A rule carrying options describes a request rather than a domain, and element hiding needs a document. Neither is something a domain filter can act on.
When a rule is rejected
Blue Guard says why. The usual causes are a pattern that is not in the
||domain^ form, an option with no Safari equivalent, an empty selector after
##, a duplicate of a rule you already have, or a line over 512 characters.