integration guide android

Unity Ads is a monetization tool that allows you to display video trailers of other games to your users, earn money with each view, and reward users with a virtual item. To monetize your users with Unity Ads, the product must be integrated into your game. This document will guide you through that process.

Note: These instructions are meant for non-unity integrations, if you are using Unity please refer to Unity Specific instructions here

Unity Ads Integration consists of the following parts:

• Integrating Unity Ads to your Android game
• Configuring Unity Ads on the Unity Ads Admin Panel

Integrating Unity Ads to your Android Game

Note: If you have not done so already, download the Unity Ads SDK from GitHub.

The process of integrating Unity Ads to your Android game is fairly straightforward and does not require heavy integration. The process of using Unity Ads in your applications is described below in outlined steps:

• Import the unity-ads library project into your application
• Initialize the SDK with your game ID
• Verify that there are campaigns available to the user
• Show Unity Ads to user
• Wait for the user to complete watching the video and (optionally) reward an item to the user

The actual code-level integration is described in the sections below. Should you have any problems integrating the product, log a ticket with us by emailing [email protected].

Add the Unity Ads SDK to Your Project (Android Studio)

Download unity-ads.aar from SDK repository. This package contains all binaries and configuration files for Unity Ads SDK.

You start importing Unity Ads by selecting 'File' > 'New' > 'New Module' and choosing 'Import .JAR/.AAR Package'. Select the downloaded aar file from your computer and import the file.

Now you need to add the imported Unity Ads module as a dependency to your own module. Right click your app module, select 'Open Module Settings' and open 'Dependencies' tab. Add a new dependency as 'Module Dependency' and select Unity Ads module.

Add the Unity Ads SDK to Your Project (Eclipse)

The SDK contains a directory called unity-ads, which is the SDK Eclipse project itself.

You can import the project into any Eclipse workspace, but make sure there is no existing unity-ads project in your workspace. If one exists, it is possibly referencing an older Unity Ads SDK. You should either delete it or change your workspace.

To import the SDK library project, go to Eclipse's 'File' > 'Import' menu, and select 'General' / 'Existing Projects into Workspace'

Browse to select the root of your SDK folder. The SDK should appear in the list as 'unity-ads'

You should unselect the 'Copy projects into workspace', this is useful if you expect to update the SDK in-place in the future and have your workspace's library project update accordingly.

After importing the library project, your application needs to be linked to the SDK library project. View the properties for the project, and navigate to the 'Android' tab. In the lower part of the dialog, click 'Add' and choose the 'unity-ads' project from the workspace

When using Unity Ads SDK as a library project, you shouldn't need to worry about merging AndroidManifest.xml changes or Proguard settings. If you run into problems, make sure manifestmerger.enabled is set to true in project.properties

Integrate Unity Ads to Your Codebase

Initialize Unity Ads

The functionality of Unity Ads is offered through the UnityAds class. When initialising UnityAds, you need to pass it: the parent Activity (in most cases the current class), your game ID, and an UnityAdsListener.

UnityAds.init((Activity)this, "11001", (UnityAdsListener)this);

Debug and test mode for testing UnityAds

You can turn on debug mode on get a more verbose print of what happens in UnityAds while integration. You will need to recompile the SDK in order to get debug mode working properly as the production libs do not include debug print code at all. The test mode will ensure a limitless supply of test ads for integration test purposes. NOTE: Remember to remove both debug and test mode and do a final smoke test before compilation & submitting to Store

UnityAds.setDebugMode(true);
UnityAds.setTestMode(true);

Integrate With the Activity Lifecycle

The Unity Ads SDK needs to be notified of changes in the activity lifecycle so it can keep track of the current activity. This can be easily achieved by calling the changeActivity(Activity) method in your onResume method.

Example:

@Override
public void onResume()
{
	super.onResume();
	UnityAds.changeActivity(this);
}

In most cases, this is sufficient, but if you are seeing sporadic behaviour in your application when launching Unity Ads, we recommend that you call changeActivity(this) in the onCreate() method of the Activity as well.

The UnityAdsListener Interface

The Unity Ads SDK notifies your game of important events through the UnityAdsListener interface, which you must pass to UnityAds upon initialization. You can also configure alternate listeners via the setListener(UnityAdsListener) method. The most important methods of the interface are onFetchCompleted and onFetchFailed which notify your game of the availability of ads for the current user.

When you initialize UnityAds with call to init -method, it will automatically check for inventory asynchronously. When this check is complete, it will call either the onFetchCompleted method if there are campaigns available, or onFetchFailed if there was no inventory available (or inventory could not be retrieved for example due to limited connectivity). You should not promote any offers or try to show the ads to the user prior to receiving the onFetchCompleted information.

The interface also provides information about user interaction with the Unity Ads, via the following method:

• onShow() – Called when the Unity Ads is shown to the user
• onHide() – Called when the Unity Ads is closed by the user
• onVideoStarted() – Called when video playback is initiated by the user
• onVideoCompleted(String itemKey, boolean skipped) – Called when the video playback is completed. This step also notifies you that the user should be rewarded.

Note: Item keys have been deprecated, and will be removed in SDK 2.0

Showing Unity Ads

Once Unity Ads SDK has been initialized, you can show Unity Ads ads to the user. You need to verify that the ad unit is ready and there is inventory for the current user with the canShow method. Afterwards you can simply call the show method that will show the ad to the user. By default the default zone configuration is used.

if ( UnityAds.canShow() )
{
	UnityAds.show();
}

Using Ad Placement (Zones)

This functionality allows different configurations for different ads setup in the Unity Ads Admin Panel. Typical example would be a game that shows both: incentivized (watch video get 100 coins) and interstitial ads. Usually ad skipping is disabled for incentivized ads and enabled for interstitial ads.

  public boolean setZone(String zoneId)

If the zone ID is not valid, the return value of setZone will be false.

The return values of setZone and canShow should both return true before attempting to show an ad. This is advised since the canShow method does not currently validate the set zone ID.

For example:

if ( UnityAds.setZone("rewardedVideo") && UnityAds.canShow() )
{
	UnityAds.show();
}

The zoneId is defined in the Unity Ads Admin Panel when defining an Ad-placement.

You can also get the currently active zone with getZone method, which returns the currently active zoneId as a String.

Note: Current functionality for the SDK requires you to implement the API using one of two use cases:

1. Never call the setZone method, and use the default zone instead. During initialization, the default zone is assigned as the current zone.

2. Call the setZone method each time you call canShow, or before you call show in order to set the current zone.

Note: The way this API works is that you either don't call setZone at all and use the default ad placement settings everywhere, or you explicitly call setZone always before calling show.

Item keys have been deprecated, and will be removed in SDK 2.0

Please use Zones to track specific ad placements

You can pass an optional parameter for Unity Ads by passing the show method a Map object that defines the requested properties.

• UnityAds.UNITY_ADS_OPTION_GAMERSID_KEY –

HashMap<String,Object> properties = new HashMap<String,Object>();
properties.put(UnityAds.UNITY_ADS_OPTION_GAMERSID_KEY, "gamerSid");
UnityAds.show(properties);

Rewarding the User

If you are not rewarding your users for videos you can safely ignore this section.

Once the user has completed watching the video, they should be provided with the promised reward. We also provide a boolean flag that specifies if the user has skipped the advertisement.

Note: The item key functionality is no longer supported.
It will be deprecated in a future SDK release.

Once the user has completed watching the video, you can provide a promised reward.

When the video is completed, the onVideoCompleted(String itemKey, boolean skipped) listener method is called.

If skipped is false, the player has watched an ad, and should be rewarded.

Integration Support

Should you have any problems integrating the product, log a ticket with us by emailing [email protected].