ios14 - Unity-Technologies/unity-ads GitHub Wiki

/* Title: iOS 14 technical integration guide Sort: 100 */

The following guide will help you implement changes in your project to support iOS 14 functionality. These updates will ensure that your monetization efforts continue with minimal disruption.

1. Upgrade your Unity Ads SDK.
   
   • (Made with Unity only) Install the iOS 14 Support package.
2. Update ad network IDs for your project’s properties list.
3. Implement an ATT context screen and permission request.

For more information about Unity’s preparation for these changes, please visit the iOS 14 resource center.

Unity advises that all Unity publishers integrate Unity Ads 3.5.1 or higher into their apps for iOS 14. Apps using older versions of Unity Ads will not be able to accurately report users’ App Tracking Transparency (ATT) status to advertisers, which may impact performance.

Unity always recommends using the most recent verified Unity Ads release, as it will continue to update the SDK as quickly and effectively as possible throughout the iOS 14 rollout.

Install the latest version of Unity Ads through the Unity Package Manager, by following these steps:

1. In the Unity Editor, select Window > Package Manager to open the Package Manager.
2. Select the Advertisement package from the list, then select the most recent verified version.
3. Click the Install or Update button.

If your iOS application is made with Unity, installing the iOS 14 support package provides utilities for Apple's SKAdNetwork and AppTrackingTransparency frameworks by aggregating proper ad network IDs and providing access to relevant Apple developer APIs. It also provides a convenient and customizable context screen, which allows you to encourage users to opt-in to ad tracking on their iOS device.

There are two ways to install the Unity iOS 14 Support package, depending on the version of Unity you use.

If you use Unity version 2018.1 or greater, follow these steps:

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 Advertising Support package, then click Install.

If you use any other version of Unity, follow these steps:

1. Download the iOS 14 Support package repo to your hard drive.
2. In the Unity Editor, select Window > Package Manager to open the Package Manager window.
3. Select the + button, then Add package from disk...
4. Navigate to your local copy of the package repo and select the package JSON (..\com.unity.ads.ios-support-master\com.unity.ads.ios-support\package.json), then click Open to install the package.

If successful, the iOS 14 Support package will appear in the Package Manager list. For more information, see documentation on installing packages.

The package provides access to the following Apple developer APIs:

The information property list (Info.plist) file is a resource that contains key-value pairs to identify and configure iOS apps. You will need it to implement ad network ID and ATT requirements. When you build your Unity project to iOS with the Advertising and iOS 14 Advertising Support packages installed, the process generates a plist file in the build’s root directory.

Download the Unity Ads framework here.

1. Drag-and-drop the framework into your Unity Project folder, and copy it.
2. In your ViewController header (.h), import Unity Ads and set the Unity Ads delegate:

#import <UIKit/UIKit.h>
#import <UnityAds/UnityAds.h>
@interface ViewController : UIViewController <UnityAdsInitializationDelegate, UnityAdsDelegate>
@end

Games targeting users running iOS 14 or above must implement advertiser network IDs in the Info.plist file. Including an array of verified network IDs enables ad sources to properly attribute their ad spend via Apple’s SKAdNetwork framework.

When implemented with Unity Ads version 3.5.1 or higher, these IDs allow Unity and other trusted ad sources to confidently bid on publisher inventory. To help publishers save time and energy, Unity provides an updated list of advertiser IDs across the industry to include in their plist files and avoid missing out on potential revenue.

When you build your application in the Unity Editor, the iOS 14 Support package automatically adds an updated list of advertising sources to your game's Info.plist file:

1. Build your project for iOS.
2. Check the resulting Info.plist file to ensure that your SKAdNetworkItems are as expected. If necessary, manually add any additional SKAdNetworkIdentifier dictionaries to the array.

If you also have the Unity Advertisement package installed, then this will happen without any action needed by you. However, if you aren't using the Unity Advertising package, then you'll need to follow these steps:

1. Create a new file anywhere in the Assets folder of your Unity project and name it SKAdNetworks with no extension.
2. Open the file with a text editor and paste the SKAdNetwork URL https://skan.mz.unity3d.com/v3/partner/skadnetworks.plist.json into your file, then save it. Unity will periodically update the list at this address to make sure the ad network IDs in your project updates each time you build your application.

To include network IDs in your Xcode project:

1. In the Xcode project navigator, select Info.plist.
2. Click the add button (+) beside any key in the property list editor to create a new property key.
3. Enter the key name SKAdNetworkItems.
4. For the value type, select Array.
5. For each network ID you want to include, add a key-value pair to the array where the key is SKAdNetworkIdentifier and the value is the network ID string. Unity maintains a complete list of recommended network IDs that provides these key-value pairs.

For more information on editing the property list, see the Xcode documentation.

The Monetize dashboard has a feature that detects whether your live game is missing any recommended network IDs. This can save you time and effort cross-referencing your project’s plist settings against the updated list of IDs.

1. With your project selected, select Project Settings in the left navigation menu.
2. Scroll to the Missing SKAdNetwork IDs setting, then click Copy missing SKAdNetwork IDs.
3. Open your project’s Info.plist file in a text or code editor.
4. In the plist file, locate the SKAdNetworkItems key and paste the XML you copied from the dashboard into the array. For example:

<key>SKAdNetworkItems</key>
<array>
  <! -- paste copied XML dictionaries here-->  
</array>

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.

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.

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.

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.

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.

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.

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:

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());
    }
}

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
    }
} 

Please 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.
    }];
}

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

• Learn about iOS 14 reporting in the 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 apps for SKADNetwork