Article

Building a Safari App Extension

Add, build, and enable a Safari App Extension.

Overview

You deliver a Safari App Extension inside a macOS app. When a user runs your app for the first time, the app extension immediately becomes available in Safari. This article walks you through the following steps to build your own Safari App Extension:

  1. Adding a Safari App Extension target to your app in Xcode.

  2. Adding script and style sheet files to inject into your app and modify webpage content.

  3. Adjusting property list values in your app that relate to the Safari App Extension.

  4. Building and running your application, which builds your Safari App Extension for use.

  5. Enabling your Safari App Extension in Safari so you can use it.

Add a Safari App Extension Target in Xcode

To create a Safari App Extension, add a new target to an existing macOS app project in Xcode:

  1. Launch Xcode and either open an existing project containing a macOS app or create a new one.

  2. Choose File > New > Target.

  3. From the list of templates in the Application Extension section, select Safari Extension, and click Next.

  4. Enter a product name for your extension, such as “My Extension.”

  5. Make sure that your application project is selected in the Project menu, and that your macOS application target is selected in the Embed in Application menu.

  6. Click Finish.

  7. When Xcode asks you if you want to activate a new scheme for your new extension, click Cancel.

Xcode adds a new group into your project, which contains several new files, including an Info.plist file, a variety of supporting source files, an Interface Builder file, a JavaScript file, and a toolbar image PDF.

Add Scripts and Style Sheets

After you add scripts and style sheets to your Safari App Extension, you'll be able to read and modify webpage content, and read and send data from your app. For more about injecting scripts and style sheets into your webpage content, see About Injected Style Sheets and Scripts.

Add Keys to the Info Property List Template

The default Info.plist file identifies your new Safari App Extension and specifies its capabilities and access limits under the NSExtension key. For more about setting these capabilities and limits, see Safari App Extension Info Property List Keys. In your info property list file, you can also specify custom UI options, like contextual menu items and toolbar items. For more about these settings, see About Contextual Menu and Toolbar Item Keys.

Build and Run the Application

Before Safari can find your new extension, you must run the parent application at least once:

  1. Make sure that your macOS app is selected in the Scheme menu next to the Run and Stop buttons in Xcode’s main toolbar.

  2. Click the Run button, or choose Product > Run (Command-R) to build and run your app.

When you build your app, Xcode builds your Safari App Extension first, then embeds it inside the finished app bundle. As soon as your app runs, your extension is ready for use in Safari.

Enable Your App Extension in Safari

If you’re not part of the Apple Development Program, or if you haven’t yet configured a developer identity for your existing Xcode project, your Safari App Extension won’t be signed with a development certificate. For security purposes, Safari, by default, ignores unsigned extensions, so your extension won’t show up in Safari Extensions preferences.

To develop without a certificate, each time Safari is launched, you must tell it to load unsigned extensions using the Develop menu:

  1. Open Safari and choose Safari > Preferences.

  2. Select the Advanced tab, then select the “Show Develop menu in menu bar” checkbox.

  3. Choose Develop > Allow Unsigned Extensions. The Allow Unsigned Extensions setting is reset when a user quits Safari; you must set it again the next time Safari is launched.

  4. Select the Extensions tab. This tab shows the localized description, display name, and version number for the selected Safari App Extension. It also provides a more nuanced message about the permissions claimed by the extension.

  5. Find your new extension in the list on the left, and enable it by selecting the checkbox.

  6. Close Safari Preferences.

Your new extension is now enabled. If you built the default template extension without modifying it, you’ll see a new toolbar item (a button) in the Safari toolbar. When you press this button, the Safari App Extension logs a message that you can view in the System Console—this message comes from your SFSafariExtensionHandler subclass.

If you have trouble getting your extension to work, see Troubleshooting Your Safari App Extension.


See Also

First Steps

Converting a Legacy Safari Extension to a Safari App Extension

Convert a Legacy Safari Extension to a Safari App Extension, automatically with keys or manually.

Troubleshooting Your Safari App Extension

Debug your Safari App Extension with these techniques.