Knowledge base

Integration guide for Android (Java)

Overview

This guide covers basic integration for implementing Unity Ads in your native Android game.

  • If you are an iOS developer using Objective-C, click here.
  • If you are a Unity developer using C#, click here.
  • Click here for the Android (Java) API reference.

Note: If you only intend to implement video, interstitial, and banner ads for your monetization strategy, Unity recommends using the UnityAds API for a simpler integration experience. However, if you plan to implement Personalized Placements, you must integrate Unity Ads with the UnityMonetization API. For more information, please see the Integration for Personalized Placements section.

In this guide:

Basic ads implementation

Creating a Project on the Unity Developer Dashboard

If you don't have a Unity Developer (UDN) account yet, create one here. When you have an account, follow these steps to create a Unity Project:

  1. Log in to the Developer Dashboard, and navigate to the Operate tab.
  2. Select Projects from the left navigation bar.
  3. Click the NEW PROJECT button in the top right corner.

Locate your Project’s Game ID by selecting your Project, then selecting Monetization > Platforms from the left navigation bar. Copy the Apple App Store Game ID, as you will need it to activate the Unity Ads service in your game.

Creating a Placement

Placements are triggered events within your game that display monetization content. Manage Placements from the Operate tab of the Developer Dashboard by selecting your Project, then selecting Monetization > Placements from the left navigation bar.

Click the ADD PLACEMENT button to bring up the Placement creation prompt. Name your Placement and select its type:

  • Select Non-rewarded to show basic interstitial ads or promotional content. Non-rewarded Placements allow players to skip the ad after a specified period of time.
  • Select Rewarded to allow players to opt-in to viewing ads in exchange for incentives. Rewarded Placements do not allow the player to skip the ad.
  • Select Banner to create a dedicated Banner ad Placement.

Every Unity Ads-enabled project has a (non-rewarded) ‘video’ and (rewarded) ‘rewardedVideo’ Placement by default. Feel free to use one of these for your first implementation if they suit your needs, or create your own.

Importing the Unity Ads framework

Download the Unity Ads framework here, specifically unity-ads.aar.

Using Android Studio

  1. Create or open your existing Android project in Android Studio.
  2. Add a new module and import the unity-ads.aar file. Name the module "unity-ads", for example.
  3. Right-click on the module in the project view, then select Open Module Settings > app, and add "unity-ads" module as a dependency.
  4. Add the following imports to your java Activity file:
import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

Without Android Studio

If you can't use the .aar packages with your build system, Unity also provides the same resources in a ZIP file (unity-ads.zip in GitHub releases). Follow these steps to use Unity Ads:

  1. Include classes.jar in your build.
  2. Manually merge the manifest from AndroidManifest.xml. Make sure you include both AdUnitActivity and AdUnitSoftwareActivity activities. You also need to add the INTERNET and ACCESS_NETWORK_STATE permissions.
  3. If you are using ProGuard, add all lines from proguard.txt to your ProGuard configuration.

Initializing the Unity Ads SDK

To initialize the SDK, you must reference your Project’s Game ID for the appropriate platform. You can locate the ID on the Operate tab of the Developer Dashboard by selecting the Project, then selecting Settings > Project Settings from the left navigation bar (see the Dashboard guide section on Project Settings for details).

In your game script, you’ll need to implement an IUnityAdsListener interface that handles ad callbacks. The initialize method to initialize the SDK requires this listener as a parameter. Initialize the SDK early in your game’s run-time life cycle, before you need to show ads. For example:

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class InitializeAdsScript extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, myAdsListener, testMode);
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        @Override
        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement functionality for a user finishing an ad.
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

For the initialize function, the myActivity parameter is the current Android Activity. The unityGameID variable is the Unity Game ID for you Project, found in the developer dashboard. The myAdsListener variable is the listener for IUnityMonetizationListener callbacks. The true boolean indicates that the game is in test mode, and will only show test ads.

Note: You must implement each of the callback methods in the listener interface, even if they are empty functions for now. You will populate them with the appropriate logic where needed in the following sections. For more information on each listener callback method, see documentation on IUnityAdsListener API.

Interstitial display ads

To display a full-screen interstitial ad using the Advertisements API, simply initialize the SDK and use the Show function with the desired Placement ID.

Interstitial ads example

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class ShowInterstitialAds extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = “interstitial”;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, myAdsListener, testMode);
    }

    // Implement a function to display an ad if the Placement is ready:
    @Override
    public void DisplayInterstitialAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        @Override
        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement functionality for a user finishing an ad.
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

In this example, you can invoke DisplayInterstitialAd from anywhere in your game you wish to show an interstitial ad.

Rewarded video ads

Rewarding players for watching ads increases user engagement, resulting in higher revenue. For example, games may reward players with in-game currency, consumables, additional lives, or experience-multipliers. For more information on how to effectively design your rewarded ads, see documentation on Ads best practices.

To reward players for completing a video ad, use the onUnityAdsFinish listener callback method’s FinishState result to check if the user finished watching the ad and should be rewarded.

Rewarded video example

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;

public class ShowRewardedAds extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = “rewarded”;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, myAdsListener, testMode);
    }

    // Implement a function to display an ad if the Placement is ready:
    @Override
    public void DisplayRewardedVideoAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement conditional logic for each ad completion status:
           if (result == FinishState.COMPLETED) {
              // Reward the user for watching the ad to completion.
           } else if (result == FinishState.SKIPPED) {
              // Do not reward the user for skipping the ad.
           } else if (result == FinishState.ERROR) {
              // Log an error.
           }
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

Rewarded video ad buttons

Using a button to allow the player to opt in to watching an ad is a common implementation for rewarded video ads. Use the example code below to create a rewarded ads button. The ads button displays an ad when pressed, as long as ads are available. To configure the button in the Unity Editor:

  1. Select Game Object > UI > Button to add a button to your Scene.
  2. Select the button you added to your Scene, then add a script component to it using the Inspector (Add Component > New Script). Name the script RewardedAdsButton to match the class name.
  3. Open the script and add the following code:
import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;
import android.view.View;
import android.widget.Button;

public class RewardedAdsButton extends AppCompatActivity implements View.OnClickListener, IUnityAdsListener {

    private String unityGameID = "1234567";
    private Boolean testMode = true;
    private String placementId = “rewardedButton”;
    private Button rewardedAdsButton;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.activity_main);
        // Declare a new listener:
        final UnityAdsListener myAdsListener = new UnityAdsListener ();
        // Initialize the SDK:
        UnityAds.initialize (this, unityGameID, myAdsListener, testMode);
    }

    // Find the button in the view hierarchy and set its click function to show ads:
    final Button interstitialButton = (Button) findViewById (R.id.unityads_example_interstitial_button);
    interstitialButton.setOnClickListener (new View.OnClickListener () {
        @Override
        public void onClick (View v) {
            UnityAds.show (self, rewardedButton);
        }
    });

    // Implement a function to display an ad if the Placement is ready: 
    @Override
    public void DisplayRewardedAd () {
        if (UnityAds.isReady (placementId)) {
            UnityAds.show (placementId);
        }
    }

    // Implement the IUnityAdsListener interface methods:
    private class UnityAdsListener implements IUnityAdsListener {

        public void onUnityAdsReady (String placementId) {
            // Implement functionality for an ad being ready to show.
        }

        @Override
        public void onUnityAdsStart (String placementId) {
            // Implement functionality for a user starting to watch an ad.
        }

        @Override
        public void onUnityAdsFinish (String placementId, UnityAds.FinishState finishState) {
            // Implement conditional logic for each ad completion status:
           if (result == FinishState.COMPLETED) {
              // Reward the user for watching the ad to completion.
           } else if (result == FinishState.SKIPPED) {
              // Do not reward the user for skipping the ad.
           } else if (result == FinishState.ERROR) {
              // Log an error.
           }
        }

        @Override
        public void onUnityAdsError (UnityAds.UnityAdsError error, String message) {
            // Implement functionality for a Unity Ads service error occurring.
        }
    }
}

Placement configuration

Banner ads require a specific type of dedicated banner Placement. To create a Banner Placement:

  1. Select your Project from the Operate tab of the developer dashboard.
  2. Select Monetization > Placements from the left navigation bar.
  3. Click ADD PLACEMENT, then select Banner at the creation prompt.

Script implementation

In your game script, import the UnityBanners API, then implement an IUnityBannerListener interface to provide callbacks to the SDK. Use the loadBanner and destroy functions to show or hide the banner. The following script sample is an example implementation for displaying banner ads:

import com.unity3d.ads.IUnityAdsListener;
import com.unity3d.ads.UnityAds;
import com.unity3d.services.banners.UnityBanners;
import com.unity3d.services.banners.view.BannerPosition;
import android.view.View;

public class UnityBannerExample extends Activity {
    private String unityGameId = “1234567”;
    private Boolean testMode = true;
    private String placementId = “banner”;
    private View bannerView;

    @Override
    protected void onCreate (Bundle savedInstanceState) {
        super.onCreate (savedInstanceState);
        setContentView (R.layout.unityads_example_layout);
        final Activity myActivity = this;
        // Declare a new banner listener, and set it as the active banner listener:
        final IUnityBannerListener myBannerListener = new UnityBannerListener ();
        UnityBanners.setBannerListener (myBannerListener);
        // Initialize the Ads SDK:
        UnityAds.initialize (this, unityGameID, myAdsListener, testMode);
    }

    // Implement a function to display or destroy a banner ad: 
    @Override
    public void ToggleBannerAd () {
        // If no banner exists, show one; otherwise remove the existing one:
        if (bannerView == null) {
            // Optionally specify the banner’s anchor position:
            UnityBanners.setBannerPosition (BannerPosition.BOTTOM_CENTER);
            // Request ad content for your Placement, and load the banner:
            UnityBanners.loadBanner (myActivity, "banner");
        } else {
            UnityBanners.destroy ();
        }
    }

    // Implement the banner listener interface methods:
    private class UnityBannerListener implements IUnityBannerListener {

        @Override
        public void onUnityBannerLoaded (String placementId, View view) {
            // When the banner content loads, add it to the view hierarchy:
            bannerView = view;
            ((ViewGroup) findViewById (R.id.unityads_example_layout_root)).addView (view);
        }

        @Override
        public void onUnityBannerUnloaded (String placementId) {
            // When the banner’s no longer in use, remove it from the view hierarchy:
            bannerView = null;
        }

        @Override
        public void onUnityBannerShow (String placementId) {
            // Called when the banner is first visible to the user.
        }

        @Override
        public void onUnityBannerClick (String placementId) {
            // Called when the banner is clicked.
        }

        @Override
        public void onUnityBannerHide (String placementId) {
            // Called when the banner is hidden from the user.
        }

        @Override
        public void onUnityBannerError (String message) {
            // Called when an error occurred, and the banner failed to load or show. 
        }
    }
}

Banner ads are fully compatible with other ad formats. You may use the UnityBanners API with the UnityAds implementations documented above to achieve the best combination of ad content for your game.

By default, banner ads display anchored on the bottom-center of the screen, supporting 320 x 50 or 728 x 90 pixel resolution. To specify a custom banner achor, use the UnityBanners.setBannerPosition method. For example:

UnityBanners.setBannerPosition (BannerPosition.TOP_CENTER);

Back to top

Testing

Prior to publishing your game, enable test mode by following these steps:

  1. From the Operate tab of the Developer Dashboard, select your Project.
  2. Select Monetization > Platforms from the left navigation bar.
  3. Select the desired platform, then select the SETTINGS tab.
  4. Scroll down to the TEST MODE section and toggle override client test mode, then select the Force test mode ON radio button.

Run your project and test your ads implementation.

Note: You must enable test mode before testing ads integration, to avoid getting flagged for fraud.

Still need help? Get in touch!
Last updated on 24th May 2020