Knowledge base

AR ads integration

Example of a Unity AR ad

Overview

AR (Augmented Reality) ads offer players a fully immersive and interactive experience by incorporating digital content directly into their physical world. Players have the opportunity to make new and memorable experiences and can feel a sense of ownership by creating their own narrative. To integrate AR Ads into your Project, follow the steps detailed below:

  1. Download and install the latest SDK from the Asset Store.
  2. Configure your Project to access device camera permission settings.
  3. Create a Placement and associated script to receive and display AR content.
  4. Contact the Unity Ads team to enable AR ads for your Project.

Requirements

Before implementing AR ads in your Unity Project, you must meet the following requirements:

Warning: Games directed at children under 13 are currently not eligible to enable AR ads.

Configuring a Unity Project

This section details setting your Project up for Unity integration. If your game already uses AR functionality, skip to the Implementation section.

Setting camera permissions

AR ads require access to the device’s camera. When configured, the Unity Ads SDK can handle this permission query.

iOS

  1. In the Unity Editor, select Edit > Project** Settings > Player**.
  2. Select the iOS icon in the platform tab menu and scroll to the Other Settings section.
  3. Find the Camera Usage Description field and enter a description of why the game needs to access the device’s camera. Unity recommends "For AR ads display". For more information on this setting, see the iOS Player Settings documentation.

Android

  1. To download the Google AR core library:

    • Access the Maven repository here.
    • Click the most current version
    • Select the .aar button listed under Files.
  2. Place the .aar file in your Project’s Assets/Plugins/Android directory.

  3. Contact Unity requesting a custom Android Manifest (AndroidManifest.xml) with the modifications required for AR ads to work in your Project, and a project.properties file that enables loading the Android Manifest.
  4. Unzip the provided UnityAdsARConfigManifest.zip file, and place the resulting folder in your Project’s Assets/Plugins/Android directory.

Important: Google requires end-users to explicitly grant camera permissions. By default, Unity AR ads-enabled games on Android request that permission when the game starts. If you choose to postpone the permissions query, you may do so by changing the unityplayer.SkipPermissionsDialog value in the Android Manifest to true. However, this setting controls all of your game’s permission queries, not just the camera. While Unity Ads will handle the camera query, you must ensure that any other permission requests (for example, accessing the microphone) occur prior to accessing the relevant component. If one of your Project’s plugins does not support this, you may experience crashes. Unity recommends thoroughly testing your implementation if you enable this option.

Configuring a Non-Unity game

This section details setting your game up for iOS or Android integration. If your game already uses AR functionality, skip to the Implementation section.

Setting camera permissions

AR ads requires access to the device’s camera. Once configured, the Unity Ads SDK can handle this permission query.

iOS

Add the Privacy - Camera Usage Description key to your game's Property List (Info.plist). For example, you can set the string value to "AR ads would like to access the camera".

Configuring the Camera Usage Description key in the Properties List

Android

  1. Add the following to your game’s Android Manifest (see the AndroidManifest.xml file included in UnityAdsARConfigManifest.zip for reference):
// Manifest level
<uses-permission android:name="android.permission.CAMERA" />
// Application level
<meta-data android:name="com.google.ar.core" android:value="optional" />
  1. Add the ARCore library as a dependency in your game’s build configuration file (build.gradle):
dependencies {
    ...
    implementation 'com.google.ar:core:1.4.0'
}

If you get an error when trying to build, ensure that your Project's build configuration file references Google's Maven repository:

allprojects {
    repositories {
        google ()
        …
    }
}

Implementation

Implementing a dedicated Placement

Implement a Placement that is dedicated for AR content. The Dashboard does not currently support enabling AR content. Instead, configure a Placement that you will not use for other content, using an easily identifiable Placement ID (Unity recommends ‘arPlacement’). In the final setup step, you will contact Unity to enable AR content for that Placement.

Modifying your Placement script

In the script for the dedicated AR Placement, configure your Placement logic as follows:

  • Check for available AR content to fill your dedicated AR Placement.
    • If yes, show content from the AR Placement.
    • If no, show ad or Promo content from another Placement.

See the following code examples.

Unity developers (C#)

The following example uses the Monetization API (recommended) to retrieve a PlacementContent object and show an AR ad:

using UnityEngine;
using UnityEngine.Monetization;

public class ARTest : MonoBehaviour {
    private PlacementContent MyPlacementContent;

    void Start () {
        Monetization.Initialize ("1234567", false);
        Monetization.onPlacementContentReady += PlacementContentReady;
    }

    public void ShowAd () {
        if (MyPlacementContent != null) {
            ShowAdPlacementContent ad = MyPlacementContent as ShowAdPlacementContent;
            ad.Show (myAdCallbackHandler); // See note on callback handlers, below
        }
    }

    public void PlacementContentReady (object sender, PlacementContentReadyEventArgs e) {
        Debug.LogFormat ("PlacementID: {0}, Object: {1}", e.placementId, e.placementContent.GetType ());
        if (e.placementId == "arPlacement") {
            MyPlacementContent = e.placementContent;
        }
    }
}

Note: For more information on implementing a callback handler, see documentation on C# Ads integration.

Alternatively, the following example uses the Advertisement API to show an AR ad:

if (Advertisement.IsReady ("arPlacement")) {
   ShowOptions so = new ShowOptions ();
   so.resultCallback = MyARAdCallbackHandler;
   Advertisement.Show ("arPlacement", so);
} else if (Advertisement.IsReady ()) {
   ShowOptions so = new ShowOptions ();
   so.resultCallback = MyAdCallbackHandler; 
   // Replace MyAdCallbackHandler with the one you are already using
   Advertisement.Show (so);
}

Note: If your script already decides between multiple Placements, ensure that the dedicated AR Placement handling executes first.

Rebuild your game. Your game should now be ready to receive AR content upon enabling it.

iOS developers (Objective-C)

The following example uses the UnityMonetization API (recommended) to retrieve a UMONPlacementContent object and show an AR ad. The code should be implemented as a delegate class for the UMONShowAdDelegate delegate.

-(void) showAdIfReady: {
    UMONShowAdPlacementContent * arPlacement = (UMONShowAdPlacementContent *) [UnityMonetization getPlacementContent: @"arPlacement"];
    if ([arPlacement isReady]) {
        [arPlacement show: self withDelegate: self];
    } else {
        UMONShowAdPlacementContent * interstitialPlacement = (UMONShowAdPlacementContent *) [UnityMonetization getPlacementContent: @"video"];
        if ([interstitialPlacement isReady]) {
            [interstitialPlacement show: self withDelegate: self];
        }
    }
}

Alternatively, the following example uses the UnityAds) API to show an AR ad:

if ([UnityAds isReady: @"arPlacement"]) {
    [UnityAds show: self placementId: @"arPlacement"];
} else if ([UnityAds isReady: @"video"]) {
    [UnityAds show: self placementId: @"video"];
}

Note: If your script already decides between multiple Placements, ensure that the dedicated AR Placement handling executes first.

Rebuild your game. Your game should now be ready to receive AR content upon enabling it.

Android developers (Java)

The following example uses the UnityMonetization API (recommended) to retrieve a PlacementContent object and show an AR ad:

protected void showAdIfReady() {
    PlacementContent arPlacement = UnityMonetization.getPlacementContent ("arPlacement");

    if (arPlacement instanceof ShowAdPlacementContent && arPlacement.isReady ()) {
        ((ShowAdPlacementContent) arPlacement).show (thisActivity, new ShowAdListenerAdapter () {
            @Override
            public void onAdStarted (String placementId) {
                Log.d ("UnityAds", "Starting AR ad!");
            }

            @Override
            public void onAdFinished (String placementId, UnityAds.FinishState withState) {
                Log.d ("UnityAds", "Finished an AR ad with state - " + withState);
            }
        });
    } else {
        PlacementContent interstitialPlacement = UnityMonetization.getPlacementContent ("video");


        if (interstitialPlacement instanceof ShowAdPlacementContent && interstitialPlacement.isReady ()) {
            ((ShowAdPlacementContent) interstitialPlacement).show (thisActivity, new ShowAdListenerAdapter () {
                @Override
                public void onAdStarted (String placementId) {
                    Log.d ("UnityAds", "Starting an interstitial ad!");
                }

                @Override
                public void onAdFinished (String placementId, UnityAds.FinishState withState) {
                    Log.d ("UnityAds", "Finished an interstitial ad with state - " + withState);
                }
            });
        }
    }
}

Alternatively, the following example uses the UnityAds API to show an AR ad:

String arPlacementId = "arPlacement";
String interstitialPlacementId = "video";

if (UnityAds.isReady (arPlacementId)) {
    UnityAds.show (self, arPlacementId);
} else if (UnityAds.isReady (interstitialPlacementId)) { 
    UnityAds.show (self, interstitialPlacementId);
}

Note: If your script already decides between multiple Placements, ensure that the dedicated AR Placement handling executes first.

Rebuild your game. Your game should now be ready to receive AR content upon enabling it.

(Optional) Adjust surface tracking

Depending on the user's behavior while engaged with AR ad content, your game's surface tracking may be off. This can result in objects floating in mid-air or inside surfaces. As such, we recommend adding a custom handler for AR ads. For example (C#):

void MyARAdCallbackHandler (ShowResult result) {
   Debug.Log ("AR ad successfully finished with result " + result.ToString ());
   // Implement any custom logic related to returning from an AR ad.
}

Enabling AR content through Unity

Contact Unity Ads to enable AR content, providing the following information:

  • Your Project ID
  • The ID for the dedicated Placement to display AR content

Testing

Please note that because AR content is loaded directly from our servers, AR ads only work in production mode, not test mode. The AR campaigns for integration testing may not reflect the final quality of the AR content.

For testing purposes, use the following Game ID and Placement ID combinations:

Platform Game ID Placement ID
iOS 1767349 arPlacement
Android 2085042 arPlacement

Remember to revert the test Game ID and Placement IDs to real production IDs before publishing your game.

Still need help? Get in touch!
Last updated on 16th Nov 2018