--- title: Creating a content blocker framework: safariservices role: article role_heading: Article path: safariservices/creating-a-content-blocker --- # Creating a content blocker Create a content blocker for Safari in Xcode. ## Overview Overview 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 in the App Store. The containing app defines the context to provide to the extension and initiates the extension life cycle by sending a request in response to a user action. When the content blocker launches, 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. Click Next and 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 blockerList.json file. 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 it encounters a match for the trigger. The trigger tells Safari when to perform the corresponding action. Content blockers are JSON arrays of these rules. [ { "trigger": { ... }, "action": { ... } }, { "trigger": { ... }, "action": { ... } } ] 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 Safari finds a match for a specific domain. For example, to write a trigger for image and style sheet resources that Safari finds on any domain except those specified, add the following to the JSON file: "trigger": { "url-filter": ".*", "resource-type": ["image", "style-sheet"], "unless-domain": ["your-content-server.com", "trusted-content-server.com"] } Capture URLs by pattern In url-filter, match more than just a specific URL, using regular expressions. | | | | | | | | | Use trigger fields to define patterns There are many valid trigger fields you can use to define patterns. | | | | | | | | | | | 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, and executes the actions in order. When a domain matches a trigger, Safari skips all rules after the triggered rule that specify the same action. 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: type and selector. An action type is required. If the type is css-display-none, a selector is required as well; otherwise, the selector is optional. For example, you can specify the following type and selector: "action": { "type": "css-display-none", "selector": "#newsletter, :matches(.main-page, .article) .news-overlay" } Select values for the type field | | | | | | For the 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, Safari ignores the selector field. Use CSS identifiers as the individual selector values, separated by commas. Safari and WebKit support all of the CSS selectors for Safari content-blocking rules. ## See Also ### Content blockers - [SFContentBlockerManager](safariservices/sfcontentblockermanager.md) - [SFContentBlockerState](safariservices/sfcontentblockerstate.md)