Article

About Safari App Extension Default Keys

Learn about the default keys in the information property list file.

Overview

After you create a Safari App Extension target in Xcode, you'll need to modify the information property list file, Info.plist. You'll make changes to identify your new Safari App Extension, and specify its capabilities and access limits under the NSExtension key.

The keys under the NSExtension key apply to the Safari App Extension point, com.apple.Safari.extension for macOS, and if used, must be placed as immediate children of the NSExtension key. These keys are supported for Safari 10.0 and later on OS X 10.11.5 and on macOS 10.12 and later.

These entries are included by default:

NSExtensionPointIdentifier

An identifier string to indicate a Safari extension: com.apple.Safari.extension.

NSExtensionPrincipalClass

A string to indicate the class with the principal implementation for your extension, with a value of SafariExtensionHandler, defined in the SafariExtensionHandler.swift file in Swift, and in the SafariExtensionHandler.h and SafariExtensionHandler.m files in Objective-C.

SFSafariContentScript

An array of dictionaries with a single entry, containing a Script key that specifies the script.js file in the template. When your extension is loaded, Safari automatically embeds this script file into every webpage that a user visits and the extension has access to. See Injecting a Script into a Webpage.

SFSafariToolbarItem

A dictionary describing a toolbar item that uses the ToolbarItemIcon.pdf image from the template as the image for the button. See Adjusting Settings for a Toolbar Item.

SFSafariWebsiteAccess

A dictionary with two keys: the Level key to indicate the level of access (set to Some), and the Allowed Domains key which includes an array of strings to limit the web addresses that your extension works with. See Access and Permissions.

Although SFSafariContentScript, SFSafariToolbarItem, and SFSafariWebsiteAccess are all default keys, they're not required because they specify features that may or may not exist in your Safari App Extension. To learn more about feature keys, see Setting Safari App Extension Feature Keys.

Sample Information Property List

The listing below represents the overall structure of a typical NSExtension dictionary. Keep this structure in mind as you configure each element of your app extension.

<dict>
	<key>NSExtensionPointIdentifier</key>
	<string>com.apple.Safari.extension</string>
	<key>NSExtensionPrincipalClass</key>
	<string>SafariExtensionHandler</string>
	 <key>SFSafariToolbarItem</key>
	<dict>
		<key>Action</key>
		<string>Command</string>
		<key>Identifier</key>
		<string>Button</string>
		<key>Image</key>
		<string>ToolbarItemIcon.pdf</string>
		<key>Label</key>
		<string>Your Button</string>
	</dict>
   <key>SFSafariContextMenu</key>
	<array>
		<dict>
			<key>Text</key>
			<string>Search for selected text in MyApplication</string>
			<key>Command</key>
			<string>Search</string>
		</dict>
		<dict>
			<key>Text</key>
			<string>Add entry for selected text in MyApplication</string>
			<key>Command</key>
			<string>Add</string>
		</dict>
	</array>
	<key>SFSafariContentScript</key>
	<array>
		<dict>
			<key>Script</key>
			<string>script.js</string>
		</dict>
	</array>
	<key>SFSafariStyleSheet</key>
	<array>
		<dict>
			<key>Style Sheet</key>
			<string>style.css</string>
		</dict>
	</array>
	<key>SFSafariWebsiteAccess</key>
	<dict>
		<key>Allowed Domains</key>
		<array>
			<string>*.webkit.org</string>
		</array>
		<key>Level</key>
		<string>Some</string>
	</dict>
</dict>