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.


When you distribute your Safari App Extension, you may want it to completely replace your previously provided Legacy Safari Extensions. Two options are available:

  • Configure your Safari App Extension to provide a clean upgrade path that automatically removes the previous Legacy Safari Extension when the Safari App Extension is installed.

  • Manually convert your Legacy Safari Extension to a Safari App Extension.

Convert Legacy Safari Extensions Automatically

Add the SFSafariExtensionBundleIdentifiersToUninstall key to the NSExtension element inside your app extension’s Info.plist file. It specifies any Legacy Safari Extensions that you want to remove when your Safari App Extension is loaded. The value for this key should be an array of strings, each of which is the bundle identifier of a Legacy Safari Extension that you want to remove.

When your app is installed, the Safari App Extension is installed with it, and the Legacy Safari Extensions you identified in the Info.plist file are removed from Safari. If any of the Legacy Safari Extensions you listed are enabled when the upgrade occurs, the Safari App Extension is also enabled.

Convert Legacy Safari Extensions Manually

If you already have a Legacy Safari Extension and you want to convert it to a Safari App Extension, you’ll need to modify parts of it and completely rewrite others. The lists below describe these changes:

Modifications are required in these areas:

  • Context menu item validation. Specify these items statically. In a Safari App extension, there’s no validation of contextual menu items before the menu is displayed.

  • Number of toolbar items. You can have only one toolbar item. In a Safari App Extension, the image displayed in the toolbar item is determined statically at build time.

  • Extension bars. Remove any extension bars from your Legacy Safari Extension. A Safari App Extension can’t create extension bars.

Rewrites are required in these areas:

  • Using an Info.plist file. Create an Xcode project for your Safari App Extension. For data that you previously entered in the Safari Extension Builder interface, enter it instead in the app extension’s Info.plist file. For more information, see Safari App Extension Info Property List Keys.

  • Working in the native app extension. A Safari App Extension doesn’t have a global HTML page. Instead, pass messages from your injected code into the app extension.

  • Sending messages. In Legacy Safari Extensions, you used a object to send messages. In a Safari App Extension, if you specify user data when sending a message, the data must be a dictionary object. For more about the message-handling process in the native app extension, see Passing Messages Between Safari App Extensions and Injected Scripts.

  • Creating popovers. Use AppKit views and view controllers to create popovers in native code.

See Also

First Steps

Building a Safari App Extension

Add, build, and enable a Safari App Extension.

Troubleshooting Your Safari App Extension

Debug your Safari App Extension with these techniques.