App Extension Keys

App extensions enable you to provide features to other apps in iOS and OS X. 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. In Xcode 7, none of these keys has an alternate Xcode name. 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

OS X v10.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

OS X v10.11 and later

NSExtensionActivationRule

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

iOS 8 and later

NSExtensionActivationUsesStrictMatching

Share, Action: See NSExtensionActivationRule for details.

iOS 9 and later

OS X v10.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

OS X v10.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

OS X v10.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

OS X v10.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

OS X v10.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

OS X v10.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.

OS X v10.10 and later

NSExtensionServiceRoleType

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

OS X v10.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.

OS X v10.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.

OS X v10.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

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, OS X. 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 OS X v10.10 and later.

NSExtensionAttributes

Dictionary - iOS, OS X. 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 OS X v10.10 and later.

NSExtensionMainStoryboard

String - iOS, OS X. 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 OS X v10.10 and later.

NSExtensionPointIdentifier

String - iOS, OS X. 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, OS X

com.apple.ui-services

Action (non-UI)

iOS

com.apple.services

Custom Keyboard

iOS

com.apple.keyboard-service

Document Picker

iOS

com.apple.fileprovider-ui

File Provider

iOS

com.apple.fileprovider-nonui

Finder Sync

OS X

com.apple.FinderSync

Photo Editing

iOS

com.apple.photo-editing

Share

iOS, OS X

com.apple.share-services

Today

iOS, OS X

com.apple.widget-extension

Watch App

iOS, watchOS

com.apple.watchkit

This key is supported in iOS 8 and later and in OS X v10.10 and later.

NSExtensionPrincipalClass

String - iOS, OS X. 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 OS X v10.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.

NSExtensionActivationDictionaryVersion

Number - iOS, OS X. Also supported in a Share extension. Specifies the activation dictionary version for an app extension. In iOS 9 and OS X v10.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 OS X v10.11 and later.

See also NSExtensionActivationUsesStrictMatching.

NSExtensionActivationRule

Dictionary - iOS, OS X. 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.)

This key is supported in iOS 8 and later and in OS X v10.10 and later.

NSExtensionActivationUsesStrictMatching

Number - iOS, OS X. Also supported in a Share extension. Specifies the activation dictionary version for the app extension. In iOS 9 and OS X v10.11, this key impacts only the matching between asset types provided by a host app and handled by an Action or Share extension. Depending on the value of this key—either 1 or 2, indicating activation dictionary version 1 or 2—an app extension is eligible to appear in the share sheet:

  • Version 1 Only when it handles all of the asset types being offered by a host app item provider

  • Version 2 When it 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 OS X v10.11 and later.

See also

NSExtensionJavaScriptPreprocessingFile

String - iOS, OS X. 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 OS X v10.10 and later.

NSExtensionServiceAllowsToolbarItem

Boolean - OS X. 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 OS X v10.10 and later.

NSExtensionServiceRoleType

String - OS X. 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 OS X v10.10 and later.

NSExtensionServiceToolbarIconFile

String - OS X. 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 OS X v10.10 and later.

NSExtensionServiceToolbarPaletteLabel

String - OS X. 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 OS X v10.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.

UIDocumentPickerModes

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

Table 5  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.

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.

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, OS X. 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 OS X v10.10 and later.

NSExtensionJavaScriptPreprocessingFile

String - iOS, OS X. 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 OS X v10.10 and later.