Unity Ads integration guide

This guide gives you step-by-step instructions on how to set Unity Ads live as an ad network on Unity LevelPlay.

For the Unity Ads network, the auto-setup tool is available to use once you complete step 1 below. The auto-setup tool will create an app and bidder placement and retrieve placement details from Unity Ads—so you don’t need to switch between the LevelPlay and Unity Ads platforms. Alternatively, you can complete the whole setup manually. 

Before you start Make sure you have correctly integrated rewarded video, interstitial or banner ads into your app.
  • Unity Ads supports Android operating systems version 4.4 (API level 19) and up
  • Unity Ads SDK 4.7.1+ requires minimum compile SDK version 33, and minimum Kotlin version 1.7.0+

Step 1.  Set up Unity Ads

Complete the following steps before setting up Unity Ads:

  1. Create a Unity ID
  2. Sign up for Unity Gaming Services. Select Get started for free

Important! Once you have completed  step 1, you can skip to step 4 and use the auto bidder setup tool to get up and running with Unity Ads bidder on Unity LevelPlay. If you’d rather continue with a manual setup, continue with step 2.

Step 2. Create a project on Unity Ads

Follow these steps to create your app on Unity Ads:

Create an app

  1. On the Unity Monetization Dashboard, select Projects. For more information about navigating the dashboard, see Introduction to the Unity Dashboard
  2. Select Organization, then Projects
  3. Click Create project

  1. Enter a project name and COPPA designation
  2. Select Create project

To monetize your project, you’ll need to enable Unity Ads in the dashboard. Select Get started from the Monetization dashboard > secondary navigation menu.

When you initialize Unity Ads for your project, you must select a mediation provider. Select I plan to use Mediation. Then, under Choose your Mediation Partner, select Unity LevelPlay.

Create an ad unit 

Use an Ad Unit to surface an event in your game that triggers ad content:

  1. From the left navigation menu, select Monetization > Ad Units
  2. Select Add Ad Unit to bring up the creation modal
  3. Enter an Ad Unit name, then select a platform (iOS or Android) and ad format (Rewarded, Interstitial, or Banner).
  4. Select Create to save your Ad Unit

Add a placement

Once your project is created, navigate to Monetization > Placements and take note of the Game ID for both platforms.

To create a new placement, click the Add Placement button.

Note: While Unity Ads automatically creates “default” placements when first creating your project, we recommend creating new unique placements for each AdMob mediation configuration.

Step 3. Retrieve your credentials

You’ll need to retrieve the following details from the Unity Ads platform to complete setup on LevelPlay:

  • API Key
  • Organization core ID
  • Key ID
  • Secret key

Navigate to Set up > API Management and take note of the API Key.

Then, navigate to Organization settings and take note of the Oorganization core ID.

To retrieve your Key ID and Secret key navigate to Monetization, then API Management. Click on the Create LevelPlay Service Account button, and a modal will appear with your key ID and secret key. Make sure to save your secret key, as you won’t be able to retrieve it again once you close the modal. 

Step 4. Configure Unity Ads on LevelPlay 

Once you have all of these parameters, log in to your LevelPlay account.

  • Go to ‘Monetize‘ ➣ ‘SDK Networks‘ ➣ ‘Available Networks‘.

  • Select Unity Ads from the list of available ad networks 
  • Input the Unity Ads API Key and Organizational Core ID in the relevant fields
  • To activate the auto-setup feature, toggle on the Unity Ads auto-setup tool. This will enable you to automatically create an app and bidder placement on the Unity Ads platform and allow LevelPlay to retrieve placement details from Unity Ads
  • Once you’ve toggled on the auto-setup tool, enter the key ID and secret key (from step 3). Then, click Save

Note: If you toggle the auto-setup tool on, you can still configure Unity Ads bidding manually on LevelPlay

Step 5: Set up Unity Ads on the app level

Traditional waterfall setup 

  • Choose the app you want to integrate from the list on the left side of the SDK Networks page
  • In the ad unit row, click Setup and enter the Game ID and Placement ID under the relevant ad unit settings

  • You will then see Unity Ads as Active for Mediation on your Setup Dashboard.

Bidder setup

There are two ways to set up the Unity Ads bidder on LevelPlay:

  1. Auto-setup – Automatically create a new app and placements on the Unity Monetize dashboard and populate all the necessary settings on LevelPlay
  2. Manual – Manually enter the necessary app details on the LevelPlay and Unity Ads platforms

Auto-setup

  • Select the app where you’d like to run interstitial, rewarded video, or banner ads from Unity Ads. Then click the define icon in the Unity Ads row

  • Click the Add bidder button to automatically create new app and bidding placements on the Unity Ads platform, and import the Game ID and Placement IDs. If there is a Game ID already attached to the app, you will be able to use the auto-setup tool if there is at least 1 placement without the Placement ID parameter value. In this case, a new bidding placement will be created (for the Game ID insert)  

Click Save to approve and accept all configurations. If you close the module without saving, the assets will be created on the Unity Ads platform without importing the data onto the LevelPlay platform.

Important: The status of Unity Ads bidder instances will be the same as the status of the ironSource Ads bidder, by ad unit. For example, if you’re not using the ironSource Ads bidder for rewarded videos, it will not be automatically activated for the Unity Ads network. To activate the Unity Ads bidding instance for rewarded videos, click on the Unity Ads row and toggle on the ad unit. 

Manual setup

  • Select the app where you’d like to run interstitial or rewarded video ads from Unity Ads
  • Select Unity Ads from the Setup list of Ad Networks, click on the define icon, and insert the Game ID and Placement ID in the relevant fields
  • Click Save

Now you’ll see Unity Ads as active for the ad units of choice in your account.

Step 4. Add the Unity Ads Adapter to Your Build

Unity LevelPlay supports both Gradle dependencies and manual download mechanisms.

Gradle

  1. Make sure the following Maven URL exist in your build.gradle script of your app module (should appear only once for all the adapters).
    repositories {
    maven {
    url "https://android-sdk.is.com/"
    }
    }
  2. Add the adapter’s Maven name to your build.gradle script of your app module.
    implementation 'com.ironsource.adapters:unityadsadapter:4.3.35'
    implementation 'com.unity3d.ads:unity-ads:4.9.3'

Manual Download

    1. Download the Unity Ads Adapter and SDK:
      This will add the Unity Ads Adapter and SDK to your build. You can find the latest Unity Ads files here.
    2. Add the Unity Ads Adapter to your Project:
      After you download the Adapter; drop the UnityAdsAdapter jar into the libs folder in your Android Project.

Unity integration with Supersonic Mediation - 08

  1. Make sure to add the following to your Gradle build file under the dependencies section:
    implementation 'com.ironsource.adapters:unityadsadapter:4.3.35'
    implementation 'com.unity3d.ads:unity-ads:4.9.3'

Step 5. Update AndroidManifest.xml

As of Unity Ads Android adapter version 4.3.4+ (Android SDK Version 6.17.0), UnityAds adapter will be released as AAR. Only if you intend to keep your Jar integration, please add the manifest.

Manifest Permissions:

<uses-permission android:name="android.permission.INTERNET" /> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Manifest Activities
Add the following activities inside the manifest tag and the <application> tag:

<activity
    android:name="com.unity3d.services.ads.adunit.AdUnitActivity"
    android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen"
    android:hardwareAccelerated="true"
    android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
<activity
    android:name="com.unity3d.services.ads.adunit.AdUnitTransparentActivity"
    android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen"
    android:hardwareAccelerated="true"
    android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
<activity
    android:name="com.unity3d.services.ads.adunit.AdUnitTransparentSoftwareActivity"
    android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen"
    android:hardwareAccelerated="false"
    android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
<activity
    android:name="com.unity3d.services.ads.adunit.AdUnitSoftwareActivity"
    android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen"
    android:hardwareAccelerated="false"
    android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
When upgrading to Unity Ads adapter 2.1.0 from an older adapter version, make sure to remove the AAR from your project as well as the compile project (‘:unity-ads’) code in your dependencies section.

For ProGuard Users Only 

If you are using ProGuard with the Unity Ads adapter, you must add the following code to your ProGuard configuration (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt):

# Keep filenames and line numbers for stack traces
-keepattributes SourceFile,LineNumberTable
# Keep JavascriptInterface for WebView bridge
-keepattributes JavascriptInterface
# Sometimes keepattributes is not enough to keep annotations
-keep class android.webkit.JavascriptInterface {
   *;
}
# Keep all classes in Unity Ads package
-keep class com.unity3d.ads.** {
   *;
}
# Keep all classes in Unity Services package
-keep class com.unity3d.services.** {
   *;
}
-dontwarn com.google.ar.core.**
-dontwarn com.unity3d.services.**
-dontwarn com.ironsource.adapters.unityads.**

Step 6. Unity Ads Additional Settings

User-level COPPA

Unity LevelPlay lets publishers communicate Unity Ads User-level COPPA settings directly to the Unity Ads network. This feature is enabled using ironSource SDK 7.1.12+, Unity Ads Android Adapter 4.3.15+.

Use the following syntax, to set UnityAds user.nonBehavioral flag with the parameter True:

 IronSource.setMetaData("UnityAds_coppa","true");

Use the following syntax, to set UnityAds user.nonBehavioral flag with the parameter False:

 IronSource.setMetaData("UnityAds_coppa","false");

Done!
You are now all set to deliver Unity Ads ads within your application!


What’s Next?

To leverage additional ad networks through ironSource Mediation, integrate the adapters and follow our integration guides