App Extension Keys

App extensions enable you to provide features to other apps in iOS and macOS. Each app extension type defines keys that let you declare to the system information about an app extension's capabilities and intents.

Keys for app extensions follow a particular hierarchical structure, with the NSExtension dictionary at the top. Most app extension types employ an NSExtensionAttributes dictionary as an immediate child of the NSExtension key. Here is a typical structure of the keys for an app extension:

<key>NSExtension</key>
<dict>
  <key>NSExtensionAttributes</key>
  <dict>
    <key>NSExtensionJavaScriptPreprocessingFile</key>
    <string>Action</string>
  </dict>
  <key>NSExtensionPointIdentifier</key>
  <string>com.apple.ui-services</string>
  <key>NSExtensionPrincipalClass</key>
  <string>MyActionRequestHandler</string>
</dict>

The NSExtensionPointIdentifier key uniquely identifies the type of app extension, such as Action or Custom Keyboard. For a complete list of the available values for the extension point identifier key, see NSExtensionPointIdentifier.

For more information about configuring the information property-list file of an app extension, see App Extension Programming Guide.

Key Summary

Table 1 is an alphabetical list of app extension keys, brief descriptions, and availability by platform and version. See later sections in this chapter for detailed information on each of these keys.

Table 1  Summary of app extension keys

Key

Extension point and description

Availability

IsASCIICapable

Custom Keyboard: A Boolean value that specifies whether a custom keyboard supports the UIKeyboardTypeASCIICapable keyboard type trait. See IsASCIICapable for details.

iOS 8 and later

NSExtension

General: A dictionary of keys and values that describe an app extension. See NSExtension for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionActionWantsFullScreenPresentation

Action: A Boolean value that specifies whether the Action extension should be presented in full screen. See NSExtensionActionWantsFullScreenPresentation for details.

iOS 8 and later

NSExtensionActivationDictionaryVersion

Share, Action: An integer that specifies the activation dictionary version to employ. See NSExtensionActivationDictionaryVersion for details.

iOS 9 and later

macOS 10.11 and later

NSExtensionActivationRule

Share, Action: A dictionary that specifies the semantic data types that a Share or Action extension supports. See NSExtensionActivationRule for details.

iOS 8 and later

NSExtensionActivationUsesStrictMatching

Share, Action: See NSExtensionActivationUsesStrictMatching for details.

iOS 9 and later

macOS 10.11 and later

NSExtensionAttributes

General: A dictionary of keys and values that specify aspects of an app extension. See NSExtensionAttributes for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionFileProviderDocumentGroup

Document Picker: A string that specifies the identifier of a shared container that can be accessed by a document picker and its associated file provider. See NSExtensionFileProviderDocumentGroup for details.

iOS 8 and later

NSExtensionJavaScriptPreprocessingFile

Share, Action: A string that specifies the name of a JavaScript file supplied by a Share extension or an Action extension. See NSExtensionJavaScriptPreprocessingFile for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionMainStoryboard

General: A string that specifies the name of the app extension’s main storyboard file, minus the .storyboard filename extension. See NSExtensionMainStoryboard for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionOverridesHostUIAppearance

General: A Boolean value that specifies whether the app extension should ignore appearance updates made by the host app. See NSExtensionOverridesHostUIAppearance for details.

iOS 10 and later

NSExtensionPointIdentifier

General: A string that specifies the extension point that supports an app extension, in reverse-DNS notation. See NSExtensionPointIdentifier for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionPrincipalClass

General: A string that specifies the name of the custom class that implements an app extension’s primary view or functionality. See NSExtensionPrincipalClass for details.

iOS 8 and later

macOS 10.10 and later

NSExtensionServiceAllowsToolbarItem

Action: A Boolean value that specifies whether an Action extension can display a toolbar button in a window’s toolbar. See NSExtensionServiceAllowsToolbarItem for details.

macOS 10.10 and later

NSExtensionServiceRoleType

Action: A string that specifies the type of task an Action extension can perform. See NSExtensionServiceRoleType for details.

macOS 10.10 and later

NSExtensionServiceToolbarIconFile

Action: A string that species the icon file for an OS X Action extension’s toolbar button. See NSExtensionServiceToolbarIconFile for details.

macOS 10.10 and later

NSExtensionServiceToolbarPaletteLabel

Action: A string that specifies the toolbar item title that gets displayed in the toolbar customization dialog for an Action extension. See NSExtensionServiceToolbarPaletteLabel for details.

macOS 10.10 and later

PHSupportedMediaTypes

Photo Editing: An array that specifies the types of assets a Photo Editing extension can edit. See PHSupportedMediaTypes for details.

iOS 8 and later

PrefersRightToLeft

Custom Keyboard: A Boolean value that specifies whether a custom keyboard is for a right-to-left language. See PrefersRightToLeft for details.

iOS 8 and later

PrimaryLanguage

Custom Keyboard: A string conforming to BCP 47 - Tags for Identifying Languages, that specifies the primary language for custom keyboard. See PrimaryLanguage for details.

iOS 8 and later

RequestsOpenAccess

Custom Keyboard: A Boolean value that specifies whether a custom keyboard wants to use a shared container and wants network access. See RequestsOpenAccess for details.

iOS 8 and later

SFSafariContentScript

Safari: An array used to add content scripts to the extension. Each value in the array is a dictionary, providing the filename for a content script. See SFSafariContentScript for details.

Safari 10 in macOS 10.11.5 and later

SFSafariContextMenu

Safari: An array used to add items to Safari’s context menu. See SFSafariContextMenufor details.

Safari 10 in macOS 10.11.5 and later

SFSafariStyleSheet

Safari: An array used to add style sheets to the extension. Each value in the array is a dictionary, providing the filename for a content script. See SFSafariStyleSheet for details.

Safari 10 in macOS 10.11.5 and later

SFSafariToolbarItem

Safari: A dictionary used to add a toolbar item to Safari windows. See SFSafariToolbarItem for details.

Safari 10 in macOS 10.11.5 and later

SFSafariWebsiteAccess

Safari: An optional dictionary that specifies which webpages the Safari app extension can access, if any. See SFSafariWebsiteAccess for details.

Safari 10 in macOS 10.11.5 and later

UIDocumentPickerModes

Document Picker: An array that specifies the supported document picker modes. See UIDocumentPickerModes for details.

iOS 8 and later

UIDocumentPickerSupportedFileTypes

Document Picker: An array that specifies the supported Uniform Type Identifiers (UTIs) for a document picker. See UIDocumentPickerSupportedFileTypes for details.

iOS 8 and later

General App Extension Keys

The keys in this section pertain to all app extensions.

NSExtension

Dictionary - iOS, macOS. Keys and values that describe an app extension. Any other app extension key used for an app extension must be placed within this dictionary.

The supported direct children of this key are the NSExtensionAttributes, NSExtensionMainStoryboard, NSExtensionPointIdentifier, and NSExtensionPrincipalClass keys.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionAttributes

Dictionary - iOS, macOS. Keys and values that specify aspects of an app extension. This key, if used, must be placed as an immediate child of the NSExtension key.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionMainStoryboard

String - iOS, macOS. Specifies the name of the app extension’s main storyboard file, minus the .storyboard filename extension. This key, if used, must be placed as an immediate child of the NSExtension key.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionOverridesHostUIAppearance

Boolean - iOS. Specifies whether the app extension can ignore appearance changes that the host app makes. To ignore appearance changes made by the host app, you must include this key as an immediate child of the NSExtension key and give it the value YES.

This key is supported in iOS 10 and later.

NSExtensionPointIdentifier

String - iOS, macOS. Specifies the extension point that supports an app extension, in reverse-DNS notation. This key is required for every app extension, and must be placed as an immediate child of the NSExtension key. Each Xcode app extension template is preconfigured with the appropriate extension point identifier key. Valid values are shown in Table 2.

Table 2  Values for the NSExtensionPointIdentifier key

Extension point

Platforms

Extension point identifier

Action (UI)

iOS, macOS

com.apple.ui-services

Action (non-UI)

iOS

com.apple.services

Broadcast Upload, Broadcast Upload UI, Broadcast UI

tvOS

com.apple.broadcast-services

Custom Keyboard

iOS

com.apple.keyboard-service

Document Picker

iOS

com.apple.fileprovider-ui

File Provider

iOS

com.apple.fileprovider-nonui

File Provider Actions

iOS

com.apple.fileprovider-actionsui

Finder Sync

macOS

com.apple.FinderSync

Message Filter

iOS

com.apple.identitylookup.message-filter

Photo Editing

iOS

com.apple.photo-editing

Share

iOS, macOS

com.apple.share-services

Today

iOS, macOS

com.apple.widget-extension

TV Services

tvOS

com.apple.tv-services

Watch App

iOS, watchOS

com.apple.watchkit

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionPrincipalClass

String - iOS, macOS. Specifies the name of the custom class that implements an app extension’s primary view or functionality. This key, if used, must be placed as an immediate child of the NSExtension key.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

Action Extension Keys

The keys in this section pertain to app extensions employing the Action extension point. These keys, if used, must be placed as immediate children of the NSExtensionAttributes key, unless noted otherwise.

NSExtensionActionWantsFullScreenPresentation

Boolean - iOS. Specifies whether an iOS Action extension should be presented in full screen. This key, if used, must be placed as an immediate child of the NSExtension key.

If the value of this key is YES, the modal presentation style of the extension’s view controller is UIModalPresentationFullScreen; otherwise, the modal presentation style is UIModalPresentationFormSheet.

This key is supported in iOS 8 and later.

NSExtensionActivationRule

Dictionary - iOS, macOS. Also supported in a Share extension. Specifies the semantic data types that an app extension supports. Each key in the dictionary represents a data type, such as image, video, or web URL. Add a key to this dictionary, and provide a nonzero value, if your app extension can handle files of the corresponding data type.

Table 3 lists the keys that you can include in the dictionary associated with the NSExtensionActivationRule dictionary. The value for each key is an integer that specifies the maximum number of files of the corresponding data type that your extension can handle.

Table 3  Keys for the NSExtensionActivationRule dictionary

Key

Description

NSExtensionActivationSupportsAttachmentsWithMaxCount

Include this key to indicate to the system and to other apps that your app supports a maximum number of attachments.

NSExtensionActivationSupportsAttachmentsWithMinCount

Include this key to indicate to the system and to other apps that your app supports a minimum number of attachments.

NSExtensionActivationSupportsFileWithMaxCount

Include this key to indicate to the system and to other apps that your app supports files in general.

NSExtensionActivationSupportsImageWithMaxCount

Include this key to indicate to the system and to other apps that your app supports image files.

NSExtensionActivationSupportsMovieWithMaxCount

Include this key to indicate to the system and to other apps that your app supports movie files.

NSExtensionActivationSupportsText

Include this key to indicate to the system and to other apps that your app supports text.

NSExtensionActivationSupportsWebURLWithMaxCount

Include this key to indicate to the system and to other apps that your app supports web URLs.

NSExtensionActivationSupportsWebPageWithMaxCount

Include this key to indicate to the system and to other apps that your app supports web pages.

If these predefined keys cannot express the activation rule you need, you can provide an entry to the NSExtensionActivationRule dictionary that is a string representing a predicate. The system evaluates the predicate against dictionary representations of NSItemProvider objects. (To learn more about creating a predicate statement for an activation rule, see Declaring Supported Data Types for a Share or Action Extension.)

The NSExtensionActivationRule dictionary can also contain the NSExtensionActivationDictionaryVersion and NSExtensionActivationUsesStrictMatching keys.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionActivationDictionaryVersion

Number - iOS, macOS. Also supported in a Share extension. Specifies the activation dictionary version for an app extension. This key appears within a NSExtensionActivationRule dictionary.

In iOS 9 and macOS 10.11, this key impacts only one thing: the matching between the set of asset types provided by a host app in an item provider, on the one hand, and the set of asset types handled by an Action or Share extension, on the other. The value of this key can be either 1 or 2, which indicates activation dictionary version 1 or 2. Specifically, the value of the key determines the conditions under which an app extension is eligible to appear in an activity view controller, as follows:

  • Activation dictionary version 1 Only when the app extension handles all of the asset types being offered by a host app item provider

  • Activation dictionary version 2 When the app extension handles at least one of the asset types being offered by a host app item provider

For example, say an item provider in a host app is offering an image asset and a text asset, and a Share extension is capable of handling only text assets. If the app extension’s Info.plist file does not have this key, or has this key and its value is set to 1, the extension will not appear in the activity view controller when the user taps the Action button in the host app. However, if the app extension’s Info.plist file has this key and its value is 2, the extension will appear.

This key is supported in iOS 9 and later and in macOS 10.11 and later.

See also NSExtensionActivationUsesStrictMatching.

NSExtensionActivationUsesStrictMatching

Boolean - iOS, macOS. Specifies whether you want to use strict or fuzzy matching when determining the asset types an app extension can handle. This key appears within a NSExtensionActivationRule dictionary.

If you need strict matching, set this key to YES (that is, 1). For example, if you need strict matching and your app extension runs in iOS 9 and later, setting NSExtensionActivationDictionaryVersion to 2 and NSExtensionActivationUsesStrictMatching to 1 helps you future-proof your code in case new versions are added.

This key is supported in iOS 9 and later and in macOS 10.11 and later.

See also NSExtensionActivationDictionaryVersion.

NSExtensionJavaScriptPreprocessingFile

String - iOS, macOS. Also supported in a Share extension. Specifies the name of a JavaScript file supplied by a Share extension. If you provide a JavaScript file, Safari runs the functions in the file when your Share extension starts and stops. You might want to include a JavaScript file in your Share extension if you want to get information from a webpage to display in your extension, or update a webpage when your extension completes its task.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionServiceAllowsToolbarItem

Boolean - macOS. Specifies whether an Action extension can display a toolbar button in a window’s toolbar. When a toolbar allows extension items, an enabled Action extension can appear in the toolbar customization dialog.

This key is supported in macOS 10.10 and later.

NSExtensionServiceRoleType

String - macOS. specifies the type of task an Action extension can perform. The available values for this key are shown in Table 4.

Table 4  Values for the NSExtensionServiceRoleType key

Value

Description

NSExtensionServiceRoleTypeEditor

Indicates an Action extension that supports user editing and returns edited content to the host app.

NSExtensionServiceRoleTypeViewer

Indicates an Action extension that supports viewing of content but not editing.

This key is supported in macOS 10.10 and later.

NSExtensionServiceToolbarIconFile

String - macOS. Species the icon file for an OS X Action extension’s toolbar button. If this key is not present, the toolbar button uses the icon specified by the app extension’s CFBundleIconFile key.

This key is supported in macOS 10.10 and later.

NSExtensionServiceToolbarPaletteLabel

String - macOS. Specifies the toolbar item title that gets displayed in the toolbar customization dialog for an Action extension. If this key is not present, the toolbar customization dialog displays the title specified by the app extension’s CFBundleDisplayName key.

This key is supported in macOS 10.10 and later.

Custom Keyboard Extension Keys

The keys in this section pertain to app extensions employing the Custom Keyboard extension point (iOS only). These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

IsASCIICapable

Boolean - iOS. Specifies whether a custom keyboard supports the UIKeyboardTypeASCIICapable keyboard type trait.

This key is supported in iOS 8 and later.

PrefersRightToLeft

Boolean - iOS. Specifies whether a custom keyboard is for a right-to-left language.

This key is supported in iOS 8 and later.

PrimaryLanguage

String - iOS. Specifies the primary language for a custom keyboard, using a string that conforms to BCP 47 - Tags for Identifying Languages. The system uses this value to indicate the keyboard language in Settings and in the system globe key.

This key is supported in iOS 8 and later.

RequestsOpenAccess

Boolean - iOS. Specifies whether a custom keyboard wants access to such resources as a shared container (shared with the containing app) and network access. Default value is NO. If you set this key’s value to YES, your keyboard gains a variety of capabilities:

  • Network access, supporting server-side processing of keystrokes

  • Shared container access with the keyboard’s containing app, supporting features such as an editing interface for the keyboard’s custom autocorrect lexicon

  • Access to Location Services and the Address Book database, with user approval

  • Via containing app, ability to participate in Game Center and In-App Purchase

  • Ability to to work with managed apps, if custom keyboard supports mobile device management (MDM)

This key is supported in iOS 8 and later.

Document Picker and File Provider Extension Keys

The keys in this section pertain to app extensions employing the Document Picker or File Provider extension points (iOS only). These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

NSExtensionFileProviderDocumentGroup

String - iOS. Specifies the identifier of a shared container that can be accessed by a Document Picker and its associated File Provider.

This key is supported in iOS 8 and later.

NSExtensionFileProviderActions

Array - iOS. Defines custom actions for a File Provider extension. Your project must contain both a File Provider extension and a File Provider UI extension.

Set this to an array of dictionaries. Each dictionary represents a separate action, and contains the following keys:

Table 5  Keys for the NSExtensionFileProviderActions dictionaries

Key

Type

Description

NSExtensionFileProviderActionIdentifier

String

A unique identifier for the action.

NSExtensionFileProviderActionName

String (Localizable)

The localized name that appears in the context menu.

NSExtensionFileProviderActionActivationRule

Predicate

A predicate that determines whether the action appears in the context menu.

The value must be a valid predicate format string. The system passes the resulting predicate a dictionary with a single fileproviderItems key. The value is an array of NSFileProviderItem objects representing the selected items.

If the action should always appear in the context menu, set the value to TRUEPREDICATE.

These actions appear in the context menu when the user long presses an item while browsing the File Provider's content.

This key is supported in iOS 11 and later.

NSExtensionFileProviderSupportsEnumeration

Boolean - iOS. Determines whether the File Provider can enumerate its content. On iOS 11 and later, set this value to YES to provide content for the Files app and the UIDocumentBrowserViewController class.

This key is supported in iOS 11 and later.

UIDocumentPickerModes

Array - iOS. Specifies the supported document picker modes.The available values for this key are shown in Table 6.

Table 6  Values for the UIDocumentPickerModes key

Value

Description

UIDocumentPickerModeImport

Indicates that the document picker can import files.

UIDocumentPickerModeOpen

Indicates that the document picker can open files.

UIDocumentPickerModeExportToService

Indicates that the document picker can export files.

UIDocumentPickerModeMoveToService

Indicates that the document picker can move files.

This key is supported in iOS 8 and later.

UIDocumentPickerSupportedFileTypes

Array - iOS. Specifies the supported file Uniform Type Identifiers (UTIs) for a document picker. The app extension is included in a document menu only if one of the requested UTIs matches one of the UTIs in this array. The move and export modes of a document picker operate only on files with supported UTIs.

This key is supported in iOS 8 and later.

Message Filter Extension Keys

The keys in this section pertain to app extensions employing the Message Filter extension point (iOS only). These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

IDMessageFilterExtensionNetworkURL

String - iOS. Optional. Specifies the associated server to which a Message Filter app extension may defer a query.

This key is supported in iOS 11 and later.

Notification Content Extension Keys

The keys in this section pertain to app extensions employing the Notification Content extension point (iOS only). These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

UNNotificationExtensionCategory

String or Array - iOS. Required. Specifies the identifier of a category declared by the app using the UNNotificationCategory class.

This key is supported in iOS 10 and later.

UNNotificationExtensionInitialContentSizeRatio

Number - iOS. Required. Represents the initial size of your view controller’s view expressed as a ratio of its height to its width. The system uses this value to set the initial size of the view controller while your extension is loading. (You can change the size of your view controller after your extension loads.)

This key is supported in iOS 10 and later.

UNNotificationExtensionDefaultContentHidden

Boolean - iOS. Optional. When set to YES, the system displays only your custom view controller in the notification interface. When set to NO, the system displays the default notification content in addition to your view controller’s content. Custom action buttons and the Dismiss button are always displayed, regardless of this setting. If you do not specify this key, the default value is set to NO.

This key is supported in iOS 10 and later.

UNNotificationExtensionOverridesDefaultTitle

Boolean - iOS. Optional. When set to YES, the system uses the title property of your view controller as the title of the notification. When set to NO, the system sets the notification's title to the name of your app. If you do not specify this key, the default value is set to NO.

This key is supported in iOS 10 and later.

Photo Editing Extension Keys

The key in this section pertains to app extensions employing the Photo Editing extension point (iOS only). These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

PHSupportedMediaTypes

Array - iOS. Specifies the types of assets a Photo Editing extension can edit. The available values for this key are Image (which is the default value) and Video.

This key is supported in iOS 8 and later.

Safari App Extension Keys

The keys in this section pertain to app extensions employing the Safari app extension point, com.apple.Safari.extension, for macOS. These keys, if used, must be placed as immediate children of the NSExtension key. These keys are supported in Safari 10.0 and later in macOS 10.11.5 and later. For more on Safari App Extensions, see Safari App Extension Programming Guide.

Listing 1 represents the overall structure of a typical NSExtension dictionary when you are providing a Safari app extension. Keep this structure in mind as you configure each element of your extension.

Listing 1  Structure for a Safari 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>script.js</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>

In addition to the NSExtension keys, the Info.plist lets you add an NSHumanReadableDescription key for your Safari app extension. When the app extension is installed, the string value of this key appears in Safari Extensions Preferences.

SFSafariContentScript

Array - macOS. An array used to add content scripts to the app extension. Each value in the array is a dictionary, providing the filename for a content script.

This key is supported in macOS 10.11.5 and later.

Content scripts and style sheets have similar functionality. Content scripts (as .js files) are injected, and style sheets (as .css files) are applied to webpages to customize web content. Scripts and styles have the same access privileges as the scripts and styles executed from the webpage’s host. Scripts can also send messages to, and receive messages from, a Safari app extension.

For details on the SFSafariContentScript subkeys, see Creating URL Patterns. Similar subkeys for SFSafariStyleSheet are shown in Table 7. For details on the URL Patterns subkeys for scripts and styles, see URL Patterns for Scripts and Styles.

Table 7  SFSafariContentScript subkeys

Subkey

Type

Description

Script

String

Required. A string that specifies the path to the content script relative to the Resources folder in the extension's bundle; for example: script.js.

Allowed URL Patterns

Array

Optional. An array of URL patterns that describe which pages the script should be injected into.

Excluded URL Patterns

Array

Optional. An array of URL patterns that describe which pages the script cannot be injected into.

URL Patterns for Scripts and Styles

For both SFSafariContentScript and SFSafariStyleSheet, the key’s Allowed URL Patterns and Excluded URL Patterns subkeys work in conjunction with the SFSafariWebsiteAccess key to specify the accessible webpages. First, access is limited by the SFSafariWebsiteAccess values, then the Allowed URL Patterns and Excluded URL Patterns keys are applied. Here’s how these keys work:

  • If you do not specify either key, the file is injected into any website.

  • If you specify the Allowed URL Patterns key, the value for this key is an array of domain patterns. The file is injected only into webpages whose URL matches one of these patterns.

  • If you specify the Excluded URL Patterns key, the value for this key is an array of domain patterns. The file is not injected into any webpages whose URL matches any of these patterns.

If you specify Some access for your app extension, for example, you have access only to the domains matching your provided domain patterns. Items in your Allowed URL Patterns and Excluded URL Patterns create additional restrictions within those domains. Be sure all the items in your Allowed URL Patterns are within a domain you have access to.

Creating URL Patterns

A URL pattern takes the form Scheme://Domain/Path.

  • Scheme can be http or https.

  • Domain is the host domain, such as developer.apple.com or www.example.co.jp.

  • Path is the directory or webpage, such as safari/ or safari/library/navigation/index.html.

A URL pattern can include the asterisk (*) character to match any string. This allows you to specify all pages in a particular domain, for example, without having to create an exhaustive list.

The * character can be used anywhere in the domain or path, but not in the scheme. Here are some examples:

  • http://*/*—Matches all HTTP URLs.

  • http://*.example.com/*—Matches all webpages from example.com.

  • http://subdomain.example.com/*—Matches all webpages from subdomain.example.com.

  • http://www.example.com/thepath/thepage.html—Matches one webpage.

  • https://*/*—Matches all webpages that are delivered over HTTPS.

  • https://secure.example.com/accounts/*—Matches all webpages from the accounts directory of secure.example.com that are delivered over HTTPS.

SFSafariContextMenu

Array - macOS. An array used to add items to Safari’s context menu.

This key is supported in macOS 10.11.5 and later.

The SFSafariContextMenu key lets app your app extension add items to the context menu shown in webpages. For available subkeys, see Listing 1.

Table 8  SFSafariContextMenu subkeys

Subkey

Type

Description

Text

String

Required. A string that specifies the text to display for the context menu item.

Command

String

Required. A string that the context menu item sends when activated.

SFSafariStyleSheet

Array - macOS. An array used to add style sheets to the app extension. Each value in the array is a dictionary, providing the filename for a content script.

This key is supported in macOS 10.11.5 and later.

Content scripts and style sheets have similar functionality. Content scripts (as .js files) are injected and style sheets (as .css files) are applied to webpages to customize web content. Scripts and styles have the same access privileges as the scripts and styles executed from the webpage’s host. The scripts can also send messages to, and receive messages from, the extension.

For details on the SFSafariContentScript subkeys, see Creating URL Patterns. Similar subkeys for SFSafariStyleSheet are shown in Table 7. For details on the URL Patterns subkeys for scripts and styles, see URL Patterns for Scripts and Styles.

Table 9  SFSafariStyleSheet subkeys

Subkey

Type

Description

Style Sheet

String

Required. A string that specifies the path to the style sheet relative to the Resources folder in the extension's bundle

Allowed URL Patterns

Array

Optional. An array of URL patterns that describe which pages the style sheet should be injected into.

Excluded URL Patterns

Array

Optional. An array of URL patterns that describe which pages the style sheet cannot be injected into.

SFSafariToolbarItem

Dictionary - macOS. A dictionary used to add a toolbar item to Safari windows.

This key is supported in macOS 10.11.5 and later.

The SFSafariToolbarItem dictionary adds a toolbar item to Safari windows. Each app extension can have only one toolbar item. For available subkeys, see SFSafariContentScript.

Table 10  SFSafariToolbarItem subkeys

Subkey

Type

Description

Identifier

String

Required. A string identifier for the toolbar item.

Label

String

Required. A string that is shown in the overflow menu, in the customize palette, and on hover.

Image

String

Required. A string specifying the filename of a scalable PDF image. The image must be transparent. See Toolbar Items.

Action

String

Required. A string specifying the command to send when the toolbar item is clicked. Available actions are Command and Popover.

SFSafariWebsiteAccess

Dictionary - macOS. An optional dictionary that specifies which webpages the Safari app extension can access, if any.

This key is supported in macOS 10.11.5 and later.

The SFSafariWebsiteAccess dictionary specifies the webpages your app extension has access to. Only the webpages you choose have your app extension’s content injected into them, and only those webpages can be manipulated using the SFSafariPageProperties object. For available subkeys, see Safari App Extension Keys.

Table 11  SFSafariWebsiteAccess subkeys

Subkey

Type

Description

Level

String

Required. A string that specifies the extent of the app extension’s website access. Available values are All, None, Some.

Allowed Domains

Array

If Level is Some, the Allowed Domains subkey is required and lists the allowed domains. Each domain in the array is specified as a string.

Use the Level subkey to restrict your extension’s website access. Available values are as follows:

  • None—Your app extension cannot access any webpages.

  • All—Your app extension has access to all webpages.

  • Some—Your app extension can access webpages from a list of domains. If you set your access to Some, and do not specify any domain patterns, your app extension cannot access any webpages.

    Each domain is specified as a string. For example: developer.apple.com or www.example.org.jp. Do not include a scheme (such as http://) in the domain pattern.

    A leading * character matches all subdomains of the allowed domain. For example: *.apple.com matches www.apple.com, developer.apple.com, or any host name in the apple.com domain. Similarly, *.co.jp matches all co.jp domains, and *.jp matches all .jp domains.

Replacing Safari Extensions With Your App Extension

Use the SFSafariExtensionBundleIdentifiersToUninstall key to specify any 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 string is the bundle identifier of a Safari extension that should be removed. The Safari extensions must have been created by the same developer account that was used to create the Safari app extension.

When your app is installed, the Safari app extension is automatically installed and the Safari extensions you identified are removed from Safari. If any of the Safari extensions you listed are enabled when the upgrade occurs, the Safari app extension is enabled automatically.

Share Extension Keys

The keys in this section pertain to app extensions employing the Share extension point. These keys, if used, must be placed as immediate children of the NSExtensionAttributes key.

NSExtensionActivationRule

Dictionary - iOS, macOS. Also supported in an Action extension. Specifies the semantic data types that an app extension supports. For complete information, see NSExtensionActivationRule.

This key is supported in iOS 8 and later and in macOS 10.10 and later.

NSExtensionJavaScriptPreprocessingFile

String - iOS, macOS. Also supported in an Action extension. Specifies the name of a JavaScript file supplied by a Share extension. For complete information, see NSExtensionJavaScriptPreprocessingFile.

This key is supported in iOS 8 and later and in macOS 10.10 and later.