Create a Content Blocker for Safari in Xcode.
Content Blockers are app extensions that you build using Xcode. They indicate to Safari a set of rules to use to block content in the browser window. Blocking behaviors include hiding elements, blocking loads, and stripping cookies from Safari requests.
You use a containing app to contain and deliver a Content Blocker on the App Store. The containing app defines the context provided to the extension and initiates the extension life cycle by sending a request in response to a user action.
When the Content Blocker is launched, it communicates with its containing app through a set of shared resources, and it communicates directly with Safari.
Apps tell Safari in advance what kinds of content to block. Because Safari doesn't have to consult with the app during loading, and because Xcode compiles Content Blockers into bytecode, this model runs efficiently. Additionally, Content Blockers have no knowledge of users' history or the websites they visit.
Add the Extension Target to Your Containing App
Choose File > New > Target and select Content Blocker Extension. Give your Content Blocker a name.
Add Behaviors to Your Content Blocker
In your Xcode project, open the folder with the same title as your Content Blocker. This folder contains the action request handler and a JSON file, along with a property list file and an entitlements file. Open the
In the JSON file, write rules to define content-blocking behaviors. Each rule is a JSON object containing action and trigger dictionaries. The action tells Safari what to do when the trigger is matched. The trigger tells Safari when to perform the corresponding action. Content Blockers are JSON arrays of these rules.
Add Triggers to Your Content Blocker
A trigger dictionary must include a
url-filter key, which specifies a pattern to match the URL against. The remaining keys are optional and modify the behavior of the trigger. For example, you can limit the trigger to specific domains or have it not apply when a match is found on a specific domain.
For example, to write a trigger for image and stylesheet resources found on any domain except those specified:
Capture URLs by Pattern
url-filter, match more than just a specific URL, using regular expressions:
Matches all strings with a dot appearing zero or more times. Use this syntax to match every URL.
Matches any character.
Explicitly matches the dot character.
Matches a range of alphabetic characters.
Matches groups of the specified characters.
Matches the preceding term one or more times.
Matches the preceding character zero or more times.
Matches the preceding character zero or one time.
Use Trigger Fields to Define Patterns
There are many valid trigger fields you can use to define patterns:
A Boolean value. The default value is false.
An array of strings matched to a URL's domain; limits action to a list of specific domains. Values must be lowercase ASCII, or punycode for non-ASCII. Add
An array of strings matched to a URL's domain; acts on any site except domains in a provided list. Values must be lowercase ASCII, or punycode for non-ASCII. Add
An array of strings representing the resource types (how the browser intends to use the resource) that the rule should match. If not specified, the rule matches all resource types. Valid values:
An array of strings that can include one of two mutually exclusive values. If not specified, the rule matches all load types.
An array of strings matched to the entire main document URL; limits the action to a specific list of URL patterns. Values must be lowercase ASCII, or punycode for non-ASCII. Can't be used with
An array of strings matched to the entire main document URL; acts on any site except URL patterns in provided list. Values must be lowercase ASCII, or punycode for non-ASCII. Can't be used with
Add Actions to Your Content Blocker
When a trigger matches a resource, the browser queues the associated action for execution. Safari evaluates all the triggers, it executes the actions in order. When a domain matches a trigger, all rules after the triggered rule that specify the same action are skipped.
Group the rules with similar actions together to improve performance. For example, first specify rules that block content loading, followed by rules that block cookies. The trigger evaluation continues at the first rule that specifies a different action.
There are only two valid fields for actions:
selector. An action type is required. If the type is
selector is required as well; otherwise the
selector is optional.
For example, you can specify the follow type and selector:
Select Values for the Type Field
Stops loading of the resource. If the resource was cached, the cache is ignored.
Hides elements of the page based on a CSS selector. A
Ignores previously triggered actions.
Changes a URL from
selector field, specify a string that defines a selector list. This value is required when the action type is
css-display-none. If it's not, the
selector field is ignored by Safari. Use CSS identifiers as the individual selector values, separated by commas. Safari and WebKit supports all of its CSS selectors for Safari content-blocking rules.