App capability declarations (Windows Store apps)

Applies to Windows and Windows Phone

Apps that need programmatic access to user resources such as Pictures or devices such as a camera, must declare the appropriate capability. An app requests access by declaring capabilities in its package manifest. You can declare most capabilities by using the Manifest Designer in Microsoft Visual Studio or you can add them manually to the package manifest as described in How to specify capabilities in a package manifest.

When you submit your app to the Store, it is checked to ensure that the declared capabilities match the description of the app. Declaring a large number of capabilities or declaring certain capabilities that users may be sensitive about may increase the level of scrutiny of your app when you submit it to the Store. When customers get your app from the Store, they are notified of all the capabilities that the app declares.

There are two types of Store accounts: company accounts and individual accounts. Apps that apply the special use capabilities described below require a company account to submit them to the Store. For more information about company accounts, see Account types, locations, and fees.

Here we look at protected resources and the capabilities required to access them.

General use capabilities

General use capabilities apply to most common app scenarios.

Music

The musicLibrary capability provides programmatic access to the user's Music, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in jukebox apps that need to access the entire Music library.

The file picker provides a robust UI mechanism that enables users to open files for use with an app. Declare the musicLibrary capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically.

Pictures

The picturesLibrary capability provides programmatic access to the user's Pictures, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in photo playback apps that need to access the entire Pictures library.

The file picker provides a robust UI mechanism that enables users to open files for use with an app. Declare the picturesLibrary capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically.

Videos

The videosLibrary capability provides programmatic access to the user's Videos, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in movie playback apps that need access to the entire Videos library.

The file picker provides a robust UI mechanism that enables users to open files for use with an app. Declare the videosLibrary capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically.

Removable storage

The removableStorage capability provides programmatic access to files on removable storage, such as USB keys and external hard drives, filtered to the file type associations declared in the package manifest. For example, if a DOC reader app declared a .doc file type association, it can open .doc files on the removable storage device, but not other types of files. Be careful when declaring this capability, because users may include a variety of info in their removable storage devices, and will expect the app to provide a valid justification for programmatic access to the removable storage for the entire file type.

Users will expect your app to handle any file associations that you declare. Therefore, do not declare file associations that your app cannot handle responsibly. The file picker provides a robust UI mechanism that enables users to open files for use with an app.

Declare the removableStorage capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker.

Internet and public networks

There are two capabilities that provide different levels of acess to the internet and public networks. These capabilities grant different access depending on if the app is running on Windows or Windows Phone.

CapabilityWindows behaviorWindows Phone behavior
internetClientCan receive incoming data from the internet. Cannot act as a server. No local network access. Full local and internet access and can act as a server. Inbound access to critical ports is always blocked.
internetClientClientServerCan receive incoming data from the internet. Can act as a server. No local network access. Full local and internet access and can act as a server. Inbound access to critical ports is always blocked

 

On Windows, most apps that have a web service component will use internetClient. Apps that enable peer-to-peer (P2P) scenarios where the app needs to listen for incoming network connections should use internetClientServer. The internetClientServer capability includes the access that the internetClient capability provides, so you don't need to specify internetClient when you specify internetClientServer.

An important certification requirement is to include a link to your Privacy Policy on the Setting pane if you declare these capabilities. Forgetting to do so is currently the most common certification blocker!

Home and work networks

The privateNetworkClientServer capability provides inbound and outbound access to home and work networks through the firewall. This capability is typically used for games that communicate across the local area network (LAN), and for apps that share data across a variety of local devices. If your app specifies musicLibrary, picturesLibrary, or videosLibrary, you don't need to use this capability to access the corresponding library in a Home Group. On Windows, this capability does not provide access to the internet. On Windows Phone, this capability provides the same access as internetClient or internetClientClientServer.

Appointments

Note  Supported starting with the app package manifest for Windows 8.1 Windows Store apps. This capability is also supported for Windows Phone.

The appointments capability provides access to the user’s appointment store. This capability allows read access to appointments obtained from the synced network accounts and to other apps that write to the appointment store. With this capability, your app can create new calendars and write appointments to calendars that it creates.

Contacts

Note  Supported starting with the app package manifest for Windows 8.1 Windows Store apps. This capability is also supported for Windows Phone.

The contacts capability provides access to the aggregated view of the contacts from various contacts stores. This capability gives the app limited access (network permitting rules apply) to contacts that were synced from various networks and the local contact store.

Device capabilities

Device capabilities allow your app to access peripheral and internal devices. Device capabilities are specified with the DeviceCapability element in your app package manifest. This element may require additional child elements and some device capabilities need to be added to the package manifest manually. For more info, see How to specify device capabilities in a package manifest and Schema reference for Windows 8 Windows Store apps or Schema reference for Windows 8.1 and Windows Phone 8.1.

Location

The location capability provides access to location functionality, which you get from dedicated hardware like a GPS sensor in the PC or is derived from available network info. Apps must handle the case where the user has disabled location services from the Settings charm. For an example of how to detect the user’s location, see Detecting geolocation.

Microphone

The microphone capability provides access to the microphone’s audio feed, which allows the app to record audio from connected microphones. Apps must handle the case where the user has disabled the microphone from the Settings charm. For an example of how to record audio, see How to record audio or video.

Proximity

The proximity capability enables multiple devices in close proximity to communicate with one another. This capability is typically used in casual multi-player games and in apps that exchange information. Devices attempt to use the communication technology that provides the best possible connection, including Bluetooth, WiFi, and the internet. This capability is used only to initiate communication between the devices. For an example of how to use proximity to connect apps, see Quickstart: Connecting apps using tapping or browsing.

Webcam

The webcam capability provides access to the video feed of a built-in camera or external webcam, which allows the app to capture photos and videos. On Windows, apps must handle the case where the user has disabled the camera from the Settings charm. For an example of how to record video, see How to record audio or video.

The webcam capability only grants access to the video stream. In order to grant access to the audio stream as well, the microphone capability must be added.

USB

The usb device capability enables access to APIs in the Windows.Devices.Usb namespace. By using the namespace, you can write an app that talks to a custom USB device. "Custom" in this context means, a peripheral device for which Microsoft does not provide an in-box class driver. This device capability requires child elements. For more info, see Updating the app manifest package for a USB device.

Note  The USB APIs are not supported on Windows Phone.

Human interface device (HID)

The humaninterfacedevice device capability enables access to APIs in the Windows.Devices.HumanInterfaceDevice namespace. This namespace lets your app access devices that support the Human Interface Device (HID) protocol. This device capability requires child elements. For more info, see How to specify device capabilities for HID.

Bluetooth GATT

The bluetooth.genericAttributeProfile device capability enables access to APIs in the Windows.Devices.Bluetooth.GenericAttributeProfile namespace. This namespace lets your app access Bluetooth LE devices through a collection of primary services, included services, characteristics, and descriptors. For more info, see How to specify device capabilities for Bluetooth.

Bluetooth RFCOMM

The bluetooth.rfcomm device capability enables access to APIs in the Windows.Devices.Bluetooth.Rfcomm namespace. This namespace supports the Basic Rate/Extended Data Rate (BR/EDR) transport and also lets your app access a device that implements Serial Port Profile (SPP). This device capability requires child elements. For more info, see How to specify device capabilities for Bluetooth.

Point of Service (POS)

The pointOfService device capability enables access to APIs in the Windows.Devices.PointOfService namespace. This namespace lets your Windows Store app access Point of Service (POS) barcode scanners and magnetic stripe readers. The namespace provides a vendor-neutral interface for accessing POS devices from various manufacturers from a Windows Store app. For more info about these APIs, see the Windows 8.1: new APIs and features.

Note  The Point of Service APIs are not supported on Windows Phone.

Special use capabilities

Special use capabilities are intended for very specific scenarios. Use of these capabilities is highly restricted and subject to additional Store onboarding policy and review. There are cases where such capabilities are necessary and appropriate, such as banking with two-factor authentication, where users provide a smart card with a digital certificate that confirms their identity. Other apps may be designed primarily for enterprise customers and may need access to corporate resources that cannot be accessed without the user’s domain credentials.

Apps that apply the special use capabilities require a company account to submit them to the Store. For more information about company accounts for Windows, see Account types, locations, and fees. For Windows Phone, see Registration info.

Enterprise authentication

Windows domain credentials enable a user to log into remote resources using their credentials, and act as if a user provided their user name and password. The enterpriseAuthentication capability is typically used in line-of-business apps that connect to servers within an enterprise.

You don't need this capability for generic communication across the internet.

The enterpriseAuthentication capability is intended to support common line-of-business apps. Don't declare it in apps that don't need to access corporate resources. The file picker provides a robust UI mechanism that enables users to open files on a network share for use with an app. Declare the enterpriseAuthentication capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker.

Shared User Certificates

The sharedUserCertificates capability enables an app to access software and hardware certificates, such as certificates stored on a smart card. This capability is typically used for financial or enterprise apps that require a smart card for authentication.

Documents

The documentsLibrary capability provides programmatic access to the user's Documents, filtered to the file type associations declared in the package manifest, to support offline access to OneDrive. For example, if a DOC reader app declared a .doc file type association, it can open .doc files in Documents, but not other types of files.

Apps that declare the documentsLibrary capability can't access Documents on Home Group computers. The file picker provides a robust UI mechanism that enables users to open files for use with an app. Declare the documentsLibrary capability only when you cannot use the file picker.

To use the documentsLibrary capability, an app must:

  • Facilitate cross-platform offline access to specific OneDrive content using valid OneDrive URLs or Resource IDs
  • Save open files to the user’s OneDrive automatically while offline

Apps that use the documentsLibrary capability for these two purposes may also optionally use the capability to open embedded content within another document. Only the above uses of the documentsLibrary capability are accepted.

Related topics

Manifest Designer
How to specify capabilities in a package manifest
How to specify device capabilities in a package manifest

 

 

Show:
© 2014 Microsoft. All rights reserved.