TN3183: Adding required reason API entries to your privacy manifest

Declare the APIs that can potentially fingerprint devices in your app or third-party SDK in a privacy manifest.

Overview

When you build an app or third-party SDK that uses any required reason API, perform these steps in your privacy manifest (PrivacyInfo.xcprivacy):

Add the NSPrivacyAccessedAPITypes key and set its value to the dictionary.
For each required reason API your app or third-party SDK uses, add a dictionary as a value for the NSPrivacyAccessedAPITypes key. The dictionary includes the category of the reason API and a list of reasons for using this API. For more information, see Add an accessed API type and reasons dictionary.

See Privacy manifest files and Describing use of required reason API for more information about the privacy manifest and these keys.

This document describes how to add the NSPrivacyAccessedAPIType, NSPrivacyAccessedAPITypeReasons, and NSPrivacyAccessedAPITypes keys to your privacy manifest in Xcode. If you work outside of Xcode, review this document to learn about the expected structure of each key.

Select an accessed API category

A privacy accessed API category identifies the category of required reason APIs your app or third-party SDK uses. Set the value of the NSPrivacyAccessedAPIType key to a privacy accessed API category. For more information, see Describing use of required reason API.

The possible values of a privacy accessed API category are:

NSPrivacyAccessedAPICategoryActiveKeyboards
NSPrivacyAccessedAPICategoryDiskSpace
NSPrivacyAccessedAPICategoryFileTimestamp
NSPrivacyAccessedAPICategorySystemBootTime
NSPrivacyAccessedAPICategoryUserDefaults

Add an accessed API type key

The NSPrivacyAccessedAPIType key uses the following format:

<key>NSPrivacyAccessedAPIType</key>
<string>NS_PRIVACY_ACCESSED_API_CATEGORY_VALUE</string>

The NS_PRIVACY_ACCESSED_API_CATEGORY_VALUE string represents a privacy accessed API category. For more information, see Select an accessed API category.

To add the NSPrivacyAccessedAPIType key to a privacy accessed API type and reasons dictionary:

Select the dictionary in the property list editor.
Click the disclosure triangle to the left of the dictionary to reveal it.
Click the Add button (+) beside the dictionary to add a new item.
In the pop-up menu that appears, choose NSPrivacyAccessedAPIType.
Confirm the value is String in the Type column.
Select a privacy accessed API category from the pop-up menu in the Value column. For possible values, see Select an accessed API category.
Confirm that the value exactly matches the category of required reason API that your app or third-party SDK uses.

Add an accessed API type reasons key

The NSPrivacyAccessedAPITypeReasons key uses the following format:

<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
    <string>NS_PRIVACY_ACCESSED_API_TYPE_REASON_VALUE</string>
    ...
</array>

Each NS_PRIVACY_ACCESSED_API_TYPE_REASON_VALUE string in the array identifies a reason why your app or third-party SDK uses a required reason API. All the values in the array are associated with a NSPrivacyAccessedAPIType key you provide when you create a privacy accessed API type and reasons dictionary.

To add the NSPrivacyAccessedAPITypeReasons key to a privacy accessed API type and reasons dictionary:

Select the dictionary in the property list editor.
Click the disclosure triangle to the left of the dictionary to reveal it.
Confirm the dictionary contains a NSPrivacyAccessedAPIType key with a value as described in Select an accessed API category.
Click the Add button (+) beside the dictionary to add a new item.
In the pop-up menu that appears, choose NSPrivacyAccessedAPITypeReasons.
Confirm the value is Array in the Type column.
Click the disclosure triangle to the left of NSPrivacyAccessedAPITypeReasons to reveal it.
Click the Add button (+) beside NSPrivacyAccessedAPITypeReasons to add a reason.
Choose a reason from the pop-up menu in the Value column. For possible values, see Describing use of required reason API.
Confirm that the value exactly matches a reason for the NSPrivacyAccessedAPIType key you use in step 3.

Add an accessed API type and reasons dictionary

A privacy accessed API type and reasons dictionary includes a category of required reason APIs and a list of related reasons. The dictionary contains exactly two keys: NSPrivacyAccessedAPIType and NSPrivacyAccessedAPITypeReasons. It uses the following format:

<dict>
    <!— Add an accessed API type key. -->
    <key>NSPrivacyAccessedAPIType</key>
    <string>NS_PRIVACY_ACCESSED_API_CATEGORY_VALUE</string>

    <!— Add an accessed API type reasons key. -->
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>NS_PRIVACY_ACCESSED_API_TYPE_REASON_VALUE</string>
        ...
    </array>
</dict>

To add a privacy accessed API type and reasons dictionary to the NSPrivacyAccessedAPITypes key in your privacy manifest:

Select PrivacyInfo.xcprivacy in the Project navigator.
Find the NSPrivacyAccessedAPITypes key in the property list editor.
Click the disclosure triangle to the left of NSPrivacyAccessedAPITypes to reveal it.
Click the Add button (+) beside NSPrivacyAccessedAPITypes to insert a new item.
Confirm the value is Dictionary in the Type column.
To add the NSPrivacyAccessedAPIType key to the dictionary, see Add an accessed API type key.
To add the NSPrivacyAccessedAPITypeReasons key to the dictionary, see Add an accessed API type reasons key.

Add the accessed API types key

The NSPrivacyAccessedAPITypes key is an array of privacy accessed API type and reasons dictionaries. For more information, see Add an accessed API type and reasons dictionary. The key uses the following format:

<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NS_PRIVACY_ACCESSED_API_CATEGORY_VALUE</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
            <string>NS_PRIVACY_ACCESSED_API_TYPE_REASON_VALUE</string>
            ...
        </array>
    </dict>
    ...
</array>

To add the NSPrivacyAccessedAPITypes key to your privacy manifest:

Select PrivacyInfo.xcprivacy in the Project navigator.
Click the Add button (+) beside the App Privacy Configuration key in the property list editor.
In the pop-up menu that appears, choose NSPrivacyAccessedAPITypes.
Confirm the value is Array in the Type column.
To add a privacy accessed API type and reasons dictionary to the array, see Add an accessed API type and reasons dictionary.

The following example declares disk space required reason API usage in an app named Sample:

Repeat step 5 for each additional required reason API your app or third-party SDK uses. The example below additionally declares user defaults required reason API usage in Sample:

Revision History

2024-12-17 First published.