App Tracking Transparency compliance#

iOS 14 and later 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.

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 project.

   • 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.

Using the asset in Unity versions 2019.1 or later#

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 select 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.

After you have 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 earlier#

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 select 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 select 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.

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.

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."

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. This script needs to be in the Assets/Editor folder of your project, and is as follows:

#if UNITY_IOS
using UnityEditor;
using UnityEditor.Callbacks;
using UnityEditor.iOS.Xcode;
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());
    }
}
#endif

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:

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#

The following example script illustrates a simple permission request implementation:

#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 project for the first time.

Additional resources#

• Learn about iOS 14 reporting in the Unity Ads Monetization dashboard.
• View iOS 14-related changes to programmatic bid responses.
• Review Apple’s documentation on User Privacy, App Privacy, and Data Use.
• Review Apple’s documentation on SKADNetwork details.
• Review Apple’s documentation on Configuring a source app and Configuring an advertised app.