Cocoa Keys

Cocoa and Cocoa Touch are the environments used to define Objective-C based apps that run in OS X and iOS respectively. The keys associated with the Cocoa environments provide support for Interface Builder nib files and provide support for other user-facing features vended by your bundle.

Cocoa keys use the prefix NS to distinguish them from other keys. For information about developing Cocoa Touch apps for iOS, see iOS App Programming Guide. For information about developing Cocoa apps for OS X, see Cocoa Fundamentals Guide.

Key Summary

Table 1 contains an alphabetical listing of Cocoa keys, the corresponding name for that key in the Xcode property list editor, a high-level description of each key, and the platforms on which you use it. Detailed information about each key is available in later sections.

Table 1  Summary of Cocoa keys

Key

Xcode name

Summary

Platforms

GKGameCenterBadgingDisabled

None

Specifies whether your app is badged. See “GKGameCenterBadgingDisabled” for details.

iOS 7.0 and later

GKShowChallengeBanners

None

Specifies whether banners are shown within an app. See “GKShowChallengeBanners”for details.

iOS 7.0 and later

NSAppleScriptEnabled

“Scriptable”

Specifies whether AppleScript is enabled. See “NSAppleScriptEnabled” for details.

OS X

NSBluetoothPeripheralUsageDescription

“Privacy - Bluetooth Peripheral Usage Description”

Specifies the reason for using Bluetooth. See “NSBluetoothPeripheralUsageDescription” for details.

iOS 6.0 and later

NSCalendarsUsageDescription

“Privacy - Calendars Usage Description”

Specifies the reason for accessing the user’s calendars. See “NSCalendarsUsageDescription” for details.

iOS 6.0 and later

NSCameraUsageDescription

“Privacy - Camera Usage Description”

Specifies the reason for accessing the device’s camera. See “NSLocationUsageDescription” for details.

iOS 7.0 and later

NSContactsUsageDescription

“Privacy - Contacts Usage Description”

Specifies the reason for accessing the user’s contacts. See “NSContactsUsageDescription” for details.

iOS 6.0 and later, OS X v10.8 and later

NSDockTilePlugIn

”Dock Tile Plugin path”

Specifies the name of app’s Dock tile plug-in, if present. See “NSDockTilePlugIn” for details.

OS X

NSHumanReadableCopyright

“Copyright (human-readable)”

(Localizable) Specifies the copyright notice for the bundle. See “NSHumanReadableCopyright” for details.

OS X

NSJavaNeeded

“Cocoa Java application”

Specifies whether the program requires a running Java VM. See “NSJavaNeeded” for details.

OS X

NSJavaPath

“Java classpaths”

An array of paths to classes whose components are preceded by NSJavaRoot. See “NSJavaPath” for details.

OS X

NSJavaRoot

“Java root directory”

The root directory containing the java classes. See “NSJavaRoot” for details.

OS X

NSLocationUsageDescription

“Privacy - Location Usage Description”

Specifies the reason for accessing the user’s location information. See “NSLocationUsageDescription” for details.

iOS 6.0 and later, OS X v10.9 and later

NSMainNibFile

“Main nib file base name”

The name of an app’s main nib file. See “NSMainNibFile” for details.

iOS, OS X

NSMicrophoneUsageDescription

“Privacy - Microphone Usage Description”

Specifies the reason for accessing the device’s microphone. See “NSCalendarsUsageDescription” for details.

iOS 7.0 and later

NSMotionUsageDescription

“Privacy - Motion Usage Description”

Specifies the reason for accessing the device’s accelerometer. See “NSMotionUsageDescription” for details.

iOS 7.0 and later

NSPersistentStoreTypeKey

“Core Data persistent store type”

The type of Core Data persistent store associated with a persistent document type. See “NSPersistentStoreTypeKey” for details.

OS X

NSPhotoLibraryUsageDescription

“Privacy - Photo Library Usage Description”

Specifies the reason for accessing the user’s photo library. See “NSPhotoLibraryUsageDescription” for details.

iOS 6.0 and later

NSPrefPaneIconFile

“Preference Pane icon file”

The name of an image file resource used to represent a preference pane in the System Preferences app. See “NSPrefPaneIconFile” for details.

OS X

NSPrefPaneIconLabel

“Preference Pane icon label”

The name of a preference pane displayed beneath the preference pane icon in the System Preferences app. See “NSPrefPaneIconLabel” for details.

OS X

NSPrincipalClass

“Principal class”

The name of the bundle’s main class. See “NSPrincipalClass” for details.

OS X

NSRemindersUsageDescription

“Privacy - Reminders Usage Description”

Specifies the reason for accessing the user’s reminders. See “NSRemindersUsageDescription” for details.

iOS 6.0 and later

NSServices

“Services”

An array of dictionaries specifying the services provided by an app. See “NSServices” for details.

OS X

NSSupportsAutomaticTermination

None

Specifies whether the app may be killed to reclaim memory. See “NSSupportsAutomaticTermination” for details.

OS X v10.7 and later

NSSupportsSuddenTermination

None

Specifies whether the app may be killed to allow for faster shut down or log out operations. See “NSSupportsSuddenTermination” for details.

OS X

NSUbiquitousDisplaySet

None

Specifies the mobile document data that the app can view. See “NSUbiquitousDisplaySet” for details.

iOS, OS X

NSUserNotificationAlertStyle

None

Specifies whether the notification style should be banner, alert, or none. The default value is banner, which is the recommended style. See “NSUserNotificationAlertStyle” for details.

OS X

UTExportedTypeDeclarations

“Exported Type UTIs”

An array of dictionaries specifying the UTI-based types supported (and owned) by the app. See “UTExportedTypeDeclarations” for details.

iOS 5.0 and later, OS X v10.7 and later

UTImportedTypeDeclarations

“Imported Type UTIs”

An array of dictionaries specifying the UTI-based types supported (but not owned) by the app. See “UTImportedTypeDeclarations” for details.

iOS, OS X

GKGameCenterBadgingDisabled

GKGameCenterBadgingDisabled (Boolean - iOS). This key determines if badges are added to your turn based app icon. Set the value of this key to YES to opt out of badging. Defaults to NO.

GKShowChallengeBanners

GKShowChallengeBanners (Boolean - iOS). This key determines if challenge banners are displayed within an app. Set the value of this key to YES to show challenge banners in the app. Set the value to NO to suppress challenge-related banners.

NSAppleScriptEnabled

NSAppleScriptEnabled (Boolean or String - OS X). This key identifies whether the app is scriptable. Set the value of this key to true (when typed as Boolean) or “YES” (when typed as String) if your app supports AppleScript.

NSBluetoothPeripheralUsageDescription

NSBluetoothPeripheralUsageDescription (String - iOS) describes the reason that the app uses Bluetooth. When the system prompts the user to allow usage, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSCalendarsUsageDescription

NSCalendarsUsageDescription (String - iOS) describes the reason that the app accesses the user’s calendars. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSCameraUsageDescription

NSCameraUsageDescription (String - iOS) describes the reason that the app accesses the device’s camera. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSContactsUsageDescription

NSContactsUsageDescription (String - iOS) describes the reason that the app accesses the user’s contacts. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSDockTilePlugIn

NSDockTilePlugIn (String - OS X). This key contains the name of a plug-in bundle with the .docktileplugin filename extension and residing in the app’s Contents/PlugIns directory. The bundle must contain the Dock tile plug-in for the app. For information about creating a Dock tile plug-in, see Dock Tile Programming Guide.

NSHumanReadableCopyright

NSHumanReadableCopyright (String - OS X). This key contains a string with the copyright notice for the bundle; for example, © 2008, My Company. You can load this string and display it in an About dialog box. This key can be localized by including it in your InfoPlist.strings files. This key replaces the obsolete CFBundleGetInfoString key.

NSJavaNeeded

NSJavaNeeded (Boolean or String - OS X). This key specifies whether the Java VM must be loaded and started up prior to executing the bundle code. This key is required only for Cocoa Java apps to tell the system to launch the Java environment. If you are writing a pure Java app, do not include this key.

You can also specify a string type with the value “YES” instead of a Boolean value if desired.

Deprecated in OS X v10.5.

NSJavaPath

NSJavaPath (Array - OS X). This key contains an array of paths. Each path points to a Java class. The path can be either an absolute path or a relative path from the location specified by the key “NSJavaRoot.” The development environment (or, specifically, its jamfiles) automatically maintains the values in the array.

Deprecated in OS X v10.5.

NSJavaRoot

NSJavaRoot (String - OS X). This key contains a string identifying a directory. This directory represents the root directory of the app’s Java class files.

NSLocationUsageDescription

NSLocationUsageDescription (String - iOS) describes the reason that the app accesses the user’s location information. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSMainNibFile

NSMainNibFile (String - iOS, OS X). This key contains a string with the name of the app’s main nib file (minus the .nib extension). A nib file is an Interface Builder archive containing the description of a user interface along with any connections between the objects of that interface. The main nib file is automatically loaded when an app is launched.

This key is mutually exclusive with the “UIMainStoryboardFile” key. You should include one of the keys in your Info.plist file but not both.

NSMicrophoneUsageDescription

NSMicrophoneUsageDescription (String - iOS) describes the reason that the app accesses the device’s microphone. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSMotionUsageDescription

NSMotionUsageDescription (String - iOS) describes the reason that the app accesses the device’s accelerometer. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 7.0 and later.

NSPersistentStoreTypeKey

NSPersistentStoreTypeKey (String - OS X). This key contains a string that specifies the type of Core Data persistent store associated with a document type (see “CFBundleDocumentTypes”).

NSPhotoLibraryUsageDescription

NSPhotoLibraryUsageDescription (String - iOS) describes the reason that the app accesses the user’s photo library. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSPrefPaneIconFile

NSPrefPaneIconFile (String - OS X). This key contains a string with the name of an image file (including extension) containing the preference pane’s icon. This key should only be used by preference pane bundles. The image file should contain an icon 32 by 32 pixels in size. If this key is omitted, the System Preferences app looks for the image file using the CFBundleIconFile key instead.

NSPrefPaneIconLabel

NSPrefPaneIconLabel (String - OS X). This key contains a string with the name of a preference pane. This string is displayed below the preference pane’s icon in the System Preferences app. You can split long names onto two lines by including a newline character (‘\n’) in the string. If this key is omitted, the System Preferences app gets the name from the CFBundleName key.

This key can be localized and included in the InfoPlist.strings files of a bundle.

NSPrincipalClass

NSPrincipalClass (String - OS X). This key contains a string with the name of a bundle’s principal class. This key is used to identify the entry point for dynamically loaded code, such as plug-ins and other dynamically-loaded bundles. The principal class of a bundle typically controls all other classes in the bundle and mediates between those classes and any classes outside the bundle. The class identified by this value can be retrieved using the principalClass method of NSBundle. For Cocoa apps, the value for this key is NSApplication by default.

NSRemindersUsageDescription

NSRemindersUsageDescription (String - iOS) describes the reason that the app accesses the user’s reminders. When the system prompts the user to allow access, this string is displayed as part of the dialog box.

This key is supported in iOS 6.0 and later.

NSServices

NSServices (Array - OS X). This key contains an array of dictionaries specifying the services provided by the app. Table 2 lists the keys for specifying a service:

Table 2  Keys for NSServices dictionaries

Key

Xcode name

Type

Description

Platforms

NSPortName

“Incoming service port name”

String

This key specifies the name of the port your app monitors for incoming service requests. Its value depends on how the service provider app is registered. In most cases, this is the app name. For more information, see Services Implementation Guide.

OS X

NSMessage

“Instance method name”

String

This key specifies the name of the instance method to invoke for the service. In Objective-C, the instance method must be of the form messageName:userData:error:. In Java, the instance method must be of the form messageName(NSPasteBoard,String).

OS X

NSSendFileTypes

None

Array

This key specifies an array of strings. Each string should contain a UTI defining a supported file type. Only UTI types are allowed; pasteboard types are not permitted. To specify pasteboard types, continue to use the NSSendTypes key.

By assigning a value to this key, your service declares that it can operate on files whose type conforms to one or more of the given file types. Your service will receive a pasteboard from which you can read file URLs.

Available in OS X v10.6 and later. For information on UTIs, see Uniform Type Identifiers Overview.

OS X

NSSendTypes

“Send Types”

Array

This key specifies an optional array of data type names that can be read by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSReturnTypes key, or both.

In OS X v10.5 and earlier, this key is required. In OS X v10.6 and later, you should use the NSSendFileTypes key instead.

OS X

NSServiceDescription

None

String

This key specifies a description of your service that is suitable for presentation to users. This description string may be long to give users adequate information about your service.

To localize the menu item text, create a ServicesMenu.strings file for each localization in your bundle. This strings file should contain this key along with the translated description string as its value. For more information about creating strings files, see Resource Programming Guide.

Available in OS X v10.6 and later.

OS X

NSRequiredContext

None

Dictionary or Array

This key specifies a dictionary with the conditions under which your service is made available to the user. Alternatively, you can specify an array of dictionaries, each of which contains a set of conditions for enabling your service.

See the discussion after this table for information about specifying the value of this key. Available in OS X v10.6 and later.

OS X

NSRestricted

None

Boolean

Specifying a value of true for this key prevents the service from being invoked by a sandboxed app. You should set the value to true if your service performs privileged or potentially dangerous operations that would allow a sandboxed app to escape its containment. For example, you should set it to true if your service executes arbitrary files or text strings as scripts, reads or writes any file specified by a path, or retrieves the contents of an arbitrary URL from the network on behalf of the client of the service.

The default value for this key is false. Available in OS X v10.7 and later.

OS X

NSReturnTypes

“Return Types”

Array

This key specifies an array of data type names that can be returned by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSSendTypes key, or both.

OS X

NSMenuItem

“Menu”

Dictionary

This key contains a dictionary that specifies the text to add to the Services menu. The only key in the dictionary is called default and its value is the menu item text.

In OS X v10.5 and earlier, menu items must be unique. You can ensure a unique name by combining the app name with the command name and separating them with a slash character “/”. This effectively creates a submenu for your services. For example, Mail/Send would appear in the Services menu as a menu named Mail with an item named Send.

Submenus are not supported (or necessary) in OS X v10.6 and later. If you specify a slash character in OS X v10.6 and later, the slash and any text preceding it are discarded. Instead, services with the same name are disambiguated by adding the app name in parenthesis after the menu item text.

To localize the menu item text, create a ServicesMenu.strings file for each localization in your bundle. This strings file should contain the default key along with the translated menu item text as its value. For more information about creating strings files, see Resource Programming Guide.

OS X

NSKeyEquivalent

“Menu key equivalent”

Dictionary

This key is optional and contains a dictionary with the keyboard equivalent used to invoke the service menu command. Similar to NSMenuItem, the only key in the dictionary is called default and its value is a single character. Users invoke this keyboard equivalent by pressing the Command modifier key along with the character. The character is case sensitive, so you can assign different commands to the uppercase and lowercase versions of a character. To specify the uppercase character, the user must press the Shift key in addition to the other keys.

OS X

NSUserData

“User Data”

String

This key is an optional string that contains a value of your choice.

OS X

NSTimeout

“Timeout value (in milliseconds)”

String

This key is an optional numerical string that indicates the number of milliseconds Services should wait for a response from the app providing a service when a response is required.

OS X

In OS X v10.6 and later, the NSRequiredContext key may contain a dictionary or an array of dictionaries describing the conditions under which the service appears in the Services menu. If you specify a single dictionary, all of the conditions in that dictionary must be met for the service to appear. If you specify an array of dictionaries, all of the conditions in only one of those dictionaries must be met for the service to appear. Each dictionary may contain one or more of the keys listed in Table 3. All keys in the dictionary are optional.

Table 3  Contents of the NSRequiredContext dictionary

Key

Xcode name

Type

Description

Platform

NSApplicationIdentifier

None

String or Array

The value of this key is a string or an array of strings, each of which contains the bundle ID (CFBundleIdentifier key) of an app. Your service appears only if the bundle ID of the current app matches one of the specified values.

OS X

NSTextScript

None

String or Array

The value of this key is a string or an array of strings, each of which contains a standard four-letter script tag, such as Latn or Cyrl. Your service appears only if the dominant script of the selected text matches one of the specified script values.

OS X

NSTextLanguage

None

String or Array

The value of this key is a string or an array of strings, each of which contains a BCP-47 tag indicating the language of the desired text. Your service appears if the overall language of the selected text matches one of the specified values.

Matching is performed using a prefix-matching scheme. For example, specifying the value en matches text whose full BCP-47 code is en-US, en-GB, or en-AU.

OS X

NSWordLimit

None

Number

The value of this key is an integer indicating the maximum number of selected words on which the service can operate. For example, a service to look up a stock by ticker symbol might have a value of 1 because ticker symbols cannot contain spaces.

OS X

NSTextContext

None

String or Array

The value of this key is a string or an array of strings, each of which contains one of the following values: URL, Date, Address, Email, or FilePath. The service is displayed only if the selected text contains data of a corresponding type. For example, if the selected text contained an http-based link, the service would be displayed if the value of this key were set to URL.

Note that all of the selected text is provided to the service-vending app, not just the parts found to contain the given data types.

OS X

For additional information about implementing services in your app, see Services Implementation Guide.

NSSupportsAutomaticTermination

NSSupportsAutomaticTermination (Boolean - OS X). This key contains a boolean that indicates whether the app supports automatic termination in OS X v10.7 and later. Automatic termination allows an app that is running to be terminated automatically by the system when certain conditions apply. Primarily, the app can be terminated when it is hidden or does not have any visible windows and is not currently being used. The system may terminate such an app in order to reclaim the memory used by the app.

An app may programmatically disable and reenable automatic termination support using the disableAutomaticTermination and enableAutomaticTermination methods of NSProcessInfo. The app might do this to prevent being terminated during a critical operation.

NSSupportsSuddenTermination

NSSupportsSuddenTermination (Boolean - OS X). This key contains a boolean that indicates whether the system may kill the app outright in order to log out or shut down more quickly. You use this key to specify whether the app can be killed immediately after launch. The app can still enable or disable sudden termination at runtime using the methods of the NSProcessInfo class. The default value of this key is NO.

NSUbiquitousDisplaySet

NSUbiquitousDisplaySet (String - iOS, OS X) contains the identifier string that you configured in iTunesConnect for managing your app’s storage. The assigned display set determines from which mobile data folder (in the user’s mobile account) the app retrieves its data files.

If you create multiple apps, you can use the same display set for your apps or assign different display sets to each. For example, if you create a lite version of your app, in addition to a full-featured version, you might use the same display set for both versions because they create and use the same basic data files. Each app should recognize the file types stored in its mobile data folder and be able to open them.

NSUserNotificationAlertStyle

NSUserNotificationAlertStyle (String - OS X) specifies the notification style the app should use. The default value, banner, is recommended; most apps should not need to use the alert style.

UTExportedTypeDeclarations

UTExportedTypeDeclarations (Array - iOS, OS X) declares the uniform type identifiers (UTIs) owned and exported by the app. You use this key to declare your app’s custom data formats and associate them with UTIs. Exporting a list of UTIs is the preferred way to register your custom file types; however, Launch Services recognizes this key and its contents only in OS X v10.5 and later. This key is ignored on versions of OS X prior to version 10.5.

The value for the UTExportedTypeDeclarations key is an array of dictionaries. Each dictionary contains a set of key-value pairs identifying the attributes of the type declaration. Table 4 lists the keys you can include in this dictionary along with the typical values they contain. These keys can also be included in array of dictionaries associated with the “UTImportedTypeDeclarations” key.

Table 4  UTI property list keys

Key

Xcode name

Type

Description

Platforms

UTTypeConformsTo

“Conforms to UTIs”

Array

(Required) Contains an array of strings. Each string identifies a UTI to which this type conforms. These keys represent the parent categories to which your custom file format belongs. For example, a JPEG file type conforms to the public.image and public.data types. For a list of high-level types, see Uniform Type Identifiers Overview.

iOS, OS X

UTTypeDescription

“Description”

String

A user-readable description of this type. The string associated with this key may be localized in your bundle’s InfoPlist.strings files.

iOS, OS X

UTTypeIconFile

“Icon file name”

String

The name of the bundle icon resource to associate with this UTI. You should include this key only for types that your app exports. This file should have a .icns filename extension. You can create this file using the Icon Composer app that comes with Xcode Tools.

OS X

UTTypeIdentifier

“Identifier”

String

(Required) The UTI you want to assign to the type. This string uses the reverse-DNS format, whereby more generic types come first. For example, a custom format for your company would have the form com.<yourcompany>.<type>.<subtype>.

iOS, OS X

UTTypeReferenceURL

“Reference URL”

String

The URL for a reference document that describes this type.

OS X

UTTypeSize64IconFile

None

String

The name of the 64 x 64 pixel icon resource file (located in the app’s bundle) to associate with this UTI. You should include this key only for types that your app exports.

iOS

UTTypeSize320IconFile

None

String

The name of the 320 x 320 pixel icon resource file (located in the app’s bundle) to associate with this UTI. You should include this key only for types that your app exports.

iOS

UTTypeTagSpecification

“Equivalent Types”

Dictionary

(Required) A dictionary defining one or more equivalent type identifiers. The key-value pairs listed in this dictionary identify the filename extensions, MIME types, OSType codes, and pasteboard types that correspond to this type. For example, to specify filename extensions, you would use the key public.filename-extension and associate it with an array of strings containing the actual extensions. For more information about the keys for this dictionary, see Uniform Type Identifiers Overview.

iOS, OS X

The way you specify icon files in OS X and iOS is different because of the supported file formats on each platform. In iOS, each icon resource file is typically a PNG file that contains only one image. Therefore, it is necessary to specify different image files for different icon sizes. However, when specifying icons in OS X, you use an icon file (with extension .icns), which is capable of storing the icon at several different resolutions.

This key is supported in iOS 3.2 and later and OS X v10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.

UTImportedTypeDeclarations

UTImportedTypeDeclarations (Array - iOS, OS X) declares the uniform type identifiers (UTIs) inherently supported (but not owned) by the app. You use this key to declare any supported types that your app recognizes and wants to ensure are recognized by Launch Services, regardless of whether the app that owns them is present. For example, you could use this key to specify a file format that is defined by another company but which your program can read and export.

The value for this key is an array of dictionaries and uses the same keys as those for the “UTExportedTypeDeclarations” key. For a list of these keys, see Table 4.

This key is supported in iOS 3.2 and later and OS X v10.5 and later. For more information about UTIs and their use, see Uniform Type Identifiers Overview.