App Tracking Transparency compliance

Implement ATT compliance. Add a tracking description, show a context screen, and request user consent before initializing ad tracking.

Read time 5 minutes

Last updated 15 days ago

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. The recommended best practice is to implement 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:

(Recommended) Configure an ATT context screen that explains the value of opting in to advertiser tracking.
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.
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.

Important

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

Using the asset in Unity versions 2019.1 or later

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

In the Unity Editor, select Window > Package Manager to open the Package Manager window.
In the Package Manager window, select the iOS 14 Support Advertising Support package.
At the bottom of the package description, find 01 Context Screen in the samples section and select Import Into Project.
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.

In the Unity Hub, under Projects, select ADD.
Navigate to the
```
com.unity.ads.ios-support
```
folder you downloaded from the package repository, then select
```
SampleProject~
```
and select Select Folder.
Select a version of Unity to use with the sample project and open it.
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:

In the sample project directory, copy the

Assets/Samples/iOS 14 Advertising Support/01 - Context Screen

folder.

Paste the copied folder into your active project's directory, according to your preferred organizational structure.
Open your active project and confirm that the
```
01 - Context Screen
```
assets copied.
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.

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:

In your Xcode project navigator, open the
```
Info.plist
```
file.
Select the add button (+) beside any key in the property list editor to create a new property key.
Enter the key name
```
NSUserTrackingUsageDescription
```
.
Select a string value type.
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. This script needs to be in the

Assets/Editor

folder of your project, and is as follows:


#if UNITY_IOSusing 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

Note

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

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.

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

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.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Unity Ads Monetization

iOS API reference - Swift

iOS API reference - Objective-C

Unity Ads Monetization

App Tracking Transparency compliance

Displaying an ATT context screen

Using the asset in Unity versions 2019.1 or later

Using the asset in Unity versions 2019.0 or earlier

Expected behavior

Displaying an ATT permission request

Configuring a user tracking description

Implementing an ATT permission request in Unity

Implementing an ATT permission request in Xcode

Testing your permission request

Additional resources