Introduction to Safari Content-Blocking Rules

A Content Blocker app extension customizes the way Safari and Safari View Controller handle your content. The extension can tailor your content by hiding elements, blocking loads, and stripping cookies from Safari requests. Your app extension provides content-blocking rules to tell Safari how to manipulate content.

Content-blocking rules are created in a structured format ahead-of-time, declaratively, rather than running extension-provided code at the moment a decision about blocking needs to be made. WebKit compiles the ruleset into a bytecode format that it can process efficiently at runtime, reducing latency between when a page request is created and when it is dispatched over the network. Safari does not request undesired content. By avoiding unnecessary or unwanted downloads, Safari uses less memory and has better performance.

Safari on macOS and Safari on iOS use the same format for content-blocking rules, an array of JSON objects. Each rule contains a trigger dictionary and an action. The trigger specifies when a rule applies, and the action specifies what Safari should do when a match is found.

Begin creating your content-blocking rules by examining the webpage resources with Web Inspector. After identifying the elements you want to block, create content-blocking rules that match only those target elements and choose the actions to perform.

To help add your rules to an app extension, Xcode provides a content blocker template. For more information on creating an app extension in Xcode, see App Extension Programming Guide.

For more information on content blocking, watch the WWDC 2015 session Safari Extensibility: Content Blocking and Shared Links.