Complying with App Tracking Transparency

iOS 14 and above requires publishers to obtain permission to track the user's device across applications. This device setting is called App Tracking Transparency, or ATT. Unity recommends implementing a custom permission flow.

Publishers should trigger the ATT permission request before initializing any SDKs intended to receive the IDFA setting.

Important: Apple mandates that this request only triggers once per install, though users can edit their preference within the iOS Settings menu at any time.

The following is a common user flow for displaying the ATT permission request:

  1. (Recommended) Configure an ATT context screen that explains the value of opting in to advertiser tracking.

  2. Configure a user tracking description for the system-permission alert that displays when you request authorization. This step is required if you want to request user tracking permission.

  3. Implement the permission flow in your game.

    • Check the device’s authorization status.

    • If the device’s authorization status is unknown, present the ATT context screen and permission request to the end user.

Displaying an ATT context screen

Targeted ads offer a higher return rate than contextual ads. Per Apple's policies, you can only prompt users to opt in to receiving targeted ads once per app install. Therefore, Unity recommends implementing a context screen that explains the benefits of opting in.

Unity’s iOS 14 Support package includes an example context screen Scene, complete with a fully customizable prefab context screen asset. The text is for example only. If you use it in a public application, it will be subject to the same certification guidelines as the rest of your submission. As this is an opportunity to make a case for opting in to targeting ads, Unity recommends customizing the message and images included.

Important: You must use the iOS 14 Support package version 0.3.0 or higher, and Unity version 2018.4.33f1 or higher to use the assets described in this section.

Using the asset in Unity versions 2019.1 or higher

Newer versions of the Unity Editor support sample imports from the Package Manager window.

  1. In the Unity Editor, select Window > Package Manager to open the Package Manager window.

  2. In the Package Manager window, select the iOS 14 Support Advertising Support package.

  3. At the bottom of the package description, find 01 Context Screen in the samples section and click Import Into Project.

  4. In the Project window, select Assets > Samples > iOS 14 Advertising Support > 01 Context Screen Scenes > Context Screen Sample to open the Context Screen Sample Scene.

Once you’ve imported the sample Scene, you can copy and modify it, or copy the prefab for use in one of your existing Scenes.

Using the asset in Unity versions 2019.0 or lower

Older versions of Unity will require you to open the sample as a separate Unity project.

  1. In the Unity Hub, under Projects, select ADD.

  2. Navigate to the com.unity.ads.ios-support folder you downloaded from the package repository, then select SampleProject~ and click Select Folder.

  3. Select a version of Unity to use with the sample project and open it.

  4. In the Unity Editor’s Project window, select Assets > Samples > iOS 14 Advertising Support > 01 Context Screen > Context Screen Sample to open the Context Screen Sample Scene.

To incorporate the asset into your project:

  1. In the sample project directory, copy the Assets/Samples/iOS 14 Advertising Support/01 - Context Screen folder.

  2. Paste the copied folder into your active project’s directory, according to your preferred organizational structure.

  3. Open your active project and confirm that the 01 - Context Screen assets copied.

  4. Open the Context Screen Sample Scene and enter Play mode to confirm the expected behavior.

Expected behavior

The scene will appear empty. When you enter Play mode, the context screen will appear. When you click Next on the context screen, nothing will happen because the native ATT request only occurs on an iOS device.

The ContextScreenManager script (Assets/Samples/iOS 14 Advertising Support/01 - Context Screen/Scripts/ContextScreenManager) ensures that the context screen appears when the Scene starts, and only if the user has not previously received the ATT permission request.

Important: You can implement a custom context screen with your own messaging, look, and feel. If you do use a custom context screen prefab, make sure to assign it to the ContextScreenManager script’s contextScreenPrefab field in the Inspector.

The ContextScreenView script (Assets/Samples/iOS 14 Advertising Support/01 - Context Screen/Scripts/ContentScreenView) triggers Apple’s ATT permission request when the user dismisses the context screen by invoking the SDK’s RequestAuthorizationTracking API.

Displaying an ATT permission request

To comply with Apple’s ATT guidelines, you must provide a description for the request dialog, then implement the permission request in your application.

Important: You must implement the permission request prior to serving ads in your game.

Configuring a user tracking description

Apple requires a description for the ATT permission request. You can set the description with the NSUserTrackingUsageDescription key in the Info.plist file. To provide a message that informs the user why you are requesting permission to use device tracking data:

  1. In your Xcode project navigator, open the Info.plist file.

  2. Click the add button (+) beside any key in the property list editor to create a new property key.

  3. Enter the key name NSUserTrackingUsageDescription.

  4. Select a string value type.

  5. Enter the app tracking transparency message in the value field. Some examples include:

    • "We will use your data to provide a better and personalized ad experience."
    • "We try to show ads for apps and products that will be most interesting to you based on the apps you use, the device you are on, and the country you are in."
    • "We try to show ads for apps and products that will be most interesting to you based on the apps you use."

Important: Apple provides specific app store guidelines that define acceptable use and messaging for all end-user facing privacy-related features. Unity does not provide legal advice. Therefore, the information on this page is not a substitute for seeking your own legal counsel to determine the legal requirements of your business and processes, and how to address them.

Unity developers can optionally create a post-build step that automatically adds the user tracking description to the file rather than manually configure it each time you generate a build:

Copy
using UnityEditor;
using UnityEditor.Callbacks;
#if UNITY_IOS
using UnityEditor.iOS.Xcode;
#endif
using System.IO;
 
public class PostBuildStep {
    // Set the IDFA request description:
    const string k_TrackingDescription = "Your data will be used to provide you a better and personalized ad experience.";
 
    [PostProcessBuild(0)]
    public static void OnPostProcessBuild(BuildTarget buildTarget, string pathToXcode) {
        if (buildTarget == BuildTarget.iOS) {
            AddPListValues(pathToXcode);
        }
    }
 
    // Implement a function to read and write values to the plist file:
    static void AddPListValues(string pathToXcode) {
        // Retrieve the plist file from the Xcode project directory:
        string plistPath = pathToXcode + "/Info.plist";
        PlistDocument plistObj = new PlistDocument();
 
 
        // Read the values from the plist file:
        plistObj.ReadFromString(File.ReadAllText(plistPath));
 
        // Set values from the root object:
        PlistElementDict plistRoot = plistObj.root;
 
        // Set the description key-value in the plist:
        plistRoot.SetString("NSUserTrackingUsageDescription", k_TrackingDescription);
 
        // Save changes to the plist:
        File.WriteAllText(plistPath, plistObj.WriteToString());
    }
}

Implementing an ATT permission request in Unity

The iOS 14 Support package provides access to Apple APIs for checking the device’s permission status and displaying the request if the status is undetermined.

The following script illustrates a simple permission request implementation using a UNITY_IOS pre-compile definition to ensure the code only executes if running on iOS devices:

Copy
using UnityEngine;
#if UNITY_IOS
// Include the IosSupport namespace if running on iOS:
using Unity.Advertisement.IosSupport;
#endif
 
public class AttPermissionRequest : MonoBehaviour {
    void Awake() {
#if UNITY_IOS
        // Check the user's consent status.
        // If the status is undetermined, display the request request:
        if(ATTrackingStatusBinding.GetAuthorizationTrackingStatus() == ATTrackingStatusBinding.AuthorizationTrackingStatus.NOT_DETERMINED) {
            ATTrackingStatusBinding.RequestAuthorizationTracking();
        }
#endif
    }

Implementing an ATT permission request in Xcode

Note: Refer to the Apple developer documentation for more information about permission request implementation.

The following example script illustrates a simple permission request implementation:

Copy
#import <AppTrackingTransparency/AppTrackingTransparency.h>
 
- (void)requestTrackingAuthorization {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        // Tracking authorization completed. Start loading ads here.
    }];
}

Testing your permission request

To test your implementation, build your project for iOS then open it in Xcode. If you open the Info.plist file (by default, this is located in the root folder of your application's bundle), you should see the NSUserTrackingUsageDescription description you added in the post-build step.

Next, build and launch the app on a test device. The ATT permission request should display when launching the game for the first time.

Note: Per Apple requirements, if you dismiss the request and launch the app a second time, the request won’t trigger. If you want to test the implementation again, you will need to uninstall and reinstall the app.​

Additional resources