�1
Mobile Ads Documentation Mobile Ads Documentation 1
Overview 3Setup Ad Networks 3Detect SDKs 3
Troubleshooting 4Showing Ads 5
Showing Banner Ads 5Showing Interstitial Ads 5Showing Reward Ads 6
Events 6Banner Events 6Interstitial Events 6Reward Events 7
Consent 7Setting the Consent Status 7
Testing 8Removing Ad Networks 8
AdMob Setup 9AdColony Setup 11AppLovin Setup 13Chartboost Setup 16IronSource Setup 18MoPub Setup 20UnityAds Setup 22Vungle Setup 24Mediation - Custom Setup 25Mediation - AdMob Setup 27Troubleshooting 30
Google Version Handler Popup 30
�2
Error CS1704 30Gradle Error: Resource Not Found 32Gradle Error: Colliding Attributes 33Build failure - Multiple dex files 35Build failure - DexIndexOverflowException 37
�3
Overview All settings are set using the Mobile Ads Window. The window can be opened by selecting the menu item Window -> Mobile Ads Settings.
Setup Ad Networks
To setup an ad network to be used select the ad network in one or more of the drop-downs on the Mobile Ads Settings window. A different ad network can be used for each ad type (banner, interstitial, and reward) and for each platform (Android and iOS). For step by step instructions on how to setup each ad network please check the specific ad network section in the documentation.
Detect SDKs
The Mobile Ads asset uses Scripting Define Symbols to enable/disable code specific to each ad network so that there are no compilation errors. After you import an ad networks SDK you need to click the Detect SDKs button so that the proper Scripting Define Symbol can be added to the project and the ad network code can be enabled.
If you ever see the above warning it means the asset has not detected the ad network SDK and you should import the SDK then click the Detect SDKs button.
After you click the button wait for Unity to finish compiling:
�4
After it successfully detects the SDK there will be an item in the SDKs list on the Detect SDKs section:
Troubleshooting
If you click the Detect SDKs button and nothing happens and the ad network doesn’t appear in the SDKs list it could be because there are compilation errors in your project. Check the Unity console for any compilation errors, those errors must be resolved before the Detect SDKs button can properly find the SDKs in your project.
�5
Showing Ads
The MobileAdsManager script is used to show ads in your game. Add the MobileAdsManager to a GameObject in your scene:
The MobileAdsManager can be accessed anywhere in you projects scripts using the static Instance property like so: MobileAdsManager.Instance
If the Retry Load If Failed is checked then when an ad fails to load for any reason (no internet connection, no ad fill, etc) the the MobileAdsManager will wait the amount of seconds specified in Retry Wait Time then it will try and load the ad again. If Retry Load If Failed is un-check then when an ad fails to load you will have to manually call one of the load methods.
NOTE: If one of the show methods (ShowInterstitialAd, ShowRewardAd) is called and there is no pre-loaded ad then the MobileAdsManager will attempt to load an ad so the next time the show method is called there will be an ad ready to show.
Showing Banner Ads
To show banner ads call the ShowBannerAd method on the MobileAdsManager Instance:
MobileAdsManager.Instance.ShowBannerAd();
You can hide the banner ad by calling the HideBannerAd method.
Showing Interstitial Ads
To show interstitial Ads call the ShowInterstitialAd method on the MobileAdsManager Instance:
MobileAdsManager.Instance.ShowInterstitialAd();
The ShowInterstitialAd method can be passed a callback method that is invoked when the interstitial ad closes and is no longer displayed on the screen.
The ShowInterstitialAd method returns a boolean indicating if an interstitial ad has been pre-loaded and is going to show. If the method returns false then there was no interstitial ad loaded
�6
so no ad will be displayed to the user. If it returns true then an interstitial ad has been pre-loaded an is about to show.
Showing Reward Ads
To show interstitial Ads call the ShowRewardAd method on the MobileAdsManager Instance:
MobileAdsManager.Instance.ShowRewardAd();
The ShowReward method can be passed two callback methods:
onClosedCallback - Invoked when the reward ad closes and is no longer displayed on the screen.onRewardGrantedCallback - Invoked when the user should be granted a reward for watching the reward ad. This method is a reward id and reward amount.
The onClosedCallback will always be called after a reward ad is shown and is called when the reward ad is no longer displayed on the screen. The onRewardGrantedCallback will only be called if the user watched the ad and should be granted the reward, if the user closed the ad in any way then onRewadGrantedCallback will not be invoked. (onRewadGrantedCallback is always invoked before onClosedCallback).
The ShowReward method returns a boolean indicating if a reward ad has been pre-loaded and is going to show. If the method returns false then there was no reward ad loaded so no ad will be displayed to the user. If it returns true then an reward ad has been pre-loaded an is about to show.
Events
There are a number of ad events you can listen to on the MobileAdsManager script. To listen for one of the events add the following code anywhere in your project and replace OnEvent with the event you wish to listen for:
MobileAdsManager.Instance.OnEvent += YourEventMethod;
Banner Events
OnBannerAdLoading - Invoked when a banner ad starts loading.OnBannerAdLoaded - Invoked when a banner ad has loaded successfully.OnBannerAdFailedToLoad - Invoked when a banner ad fails to load.OnBannerAdShown - Invoked when the banner ad is shown on the screen.OnBannerAdHidden - Invoked when the banner ad is hidden from the screen.
Interstitial EventsOnInterstitialAdLoading - Invoked when an interstitial ad starts loading.OnInterstitialAdLoaded - Invoked when an interstitial ad has successfully loaded.OnInterstitialAdFailedToLoad - Invoked when an interstitial ad failed to load.
�7
OnInterstitialAdShowing - Invoked when an interstitial ad is about to show on the screen.OnInterstitialAdShown - Invoked when an interstitial ad has been displayed on the screen.OnInterstitialAdClosed - Invoked when an interstitial ad has closed and is no longer displayed on the screen.
Reward EventsOnRewardAdLoading - Invoked when an reward ad starts loading.OnRewardAdLoaded - Invoked when an reward ad has successfully loaded.OnRewardAdFailedToLoad - Invoked when an reward ad failed to load.OnRewardAdShowing - Invoked when an reward ad is about to show on the screen.OnRewardAdShown - Invoked when an reward ad has been displayed on the screen.OnRewardAdClosed - Invoked when an reward ad has closed and is no longer displayed on the screen.OnRewardAdGranted - Invoked when a reward ad has been watched and the reward should be granted to the user. This event is passed the reward id and reward amount that is set on the ad networks dashboard.
Consent
Consent can be required before any ads are loaded by setting the Consent Setting on the Mobile Ads Manager. There are three types you can set the consent setting to:
Not Required - Consent is not required for ads to be loaded.
Required Only In EEA - Consent is only required for users in the European Economic Area. When the app starts it first attempts to determine if the user is located in the EEA and if so ads will not be loaded until the consent status has been set to either Personalized or Non-Personalized. If the user location can not be determined for any reason then it errs on the side of caution and requires consent before ads are loaded.
Require All - Consent is required for all users before ads are loaded.
Setting the Consent Status
If consent is required before ads are loaded then the SetConsentStatus method must be called on the MobileAdsManager to set the consent status to either Personalized or Non-Personalized ads.
To set the consent simply call the method like so:
MobileAdsManager.Instance.SetConsentStatus(consentStatus);
The consentStatus parameter is an integer value:
1 - Indicates the user has consented to receive personalized ads0 - Indicates the user should only be shown non-personalized ads.
�8
Testing
You should use the TestScene located in the Scenes folder to test if you have setup your ad networks properly. The test scene can be used to show ads and will print out log messages if there are any errors.
Removing Ad Networks
If you want to remove an ad network from you project first open the Mobile Ads Settings window and expand the SDKs list in the Detected SDKs section then click the Remove [AdNetwork] Scripting Define Symbol button:
Then you are free to delete the ad networks SDK files from your project without causing any compilation errors.
�9
AdMob Setup Link to AdMob Unity SDK: https://github.com/googleads/googleads-mobile-unity/releases
Step1. Download the AdMob Unity SDK by clicking the link about and selecting the latest release:
Step2. Import the GoogleMobileAds.unitypackage into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select AdMob in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the AdMob settings found in the new AdMob Settings box that appears after you selected AdMob in one of the drop-downs.
Step6 [Android only]. Open the AndroidManifest located in the folder Plugins/Android/GoogleMobileAdsPlugin and add the following lines in the application element, replace ADMOB_APP_ID with your App Id:
<meta-data android:name="com.google.android.gms.ads.APPLICATION_ID" android:value="ADMOB_APP_ID"/>
�10
Your AndroidManifest should look something like this:
Step7 [Android Only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
�11
AdColony SetupLink to AdColony Unity SDK: https://github.com/AdColony/AdColony-Unity-Plugin
Step1a. Download the AdColony Unity SDK by clicking the link above and selecting the AdColony.unitypackage in the list of files:
Step1b. Click the Download button to download the unitypackage:
Step2. Import the AdColony SDK into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
�12
Step4. Select AdColony in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the AdColony settings found in the new AdColony Settings box that appears after you selected AdColony in one of the drop-downs.
Step6 [Android Only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
�13
AppLovin Setup Link to AppLovin Unity SDK: https://dash.applovin.com/docs/integration#unity3dIntegration
Step1a. Download the AppLovin Unity SDK by clicking the link above (You have to be logged into your AppLovin account).
Step1b. Click the Download button:
Step2. Import the AppLovin SDK into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:Step4. Select AppLovin in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the AppLovin settings found in the new AppLovin Settings box that appears after you selected AppLovin in one of the drop-downs.
Step6a [Android only]. Download the Google Player Services Resolver plugin by clicking this link: https://github.com/googlesamples/unity-jar-resolver and clicking the play-services-resolver.x.x.x.x.unitypackage in the list of files:
�14
Step6b. [Android only]. Click the Download button and import the unitypackage.
Step6c [Android only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
Step7 [Android only]. Open the AndroidManifest located in the folder Plugins/Android and replace YOUR_SDK_KEY with your AppLovin SDK key and replace YOUR_PACKAGE_NAME with your projects package name found in Player Settings:
Step8 [Android only]. If you get the following build error when making a build for Android: “DeploymentOperationFailedException: No activity in the manifest with action MAIN and category LAUNCHER.” Then add the following lines to the AndroidManifest:
<activity android:name="com.unity3d.player.UnityPlayerActivity"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter></activity>
�15
Your AndroidManifest should look like this:
�16
Chartboost SetupLink to Chartboost Unity SDK: https://answers.chartboost.com/en-us/articles/download
Step1. Download the Chartboost Unity SDK from the page link to above.
Step2. Import the Chartboost Unity SDK into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select Chartboost in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the Chartboost settings found in the new Chartboost Settings box that appears after you selected Chartboost in one of the drop-downs.
Step6a [Android only]. The Play Services Resolver that comes with the Chartboost SDK doesn’t work properly so we are going to delete it and import it manually. First delete the PlayServicesResolver folder:
Step6a [Android only]. Download the Google Player Services Resolver plugin by clicking this link: https://github.com/googlesamples/unity-jar-resolver and clicking the play-services-resolver.x.x.x.x.unitypackage in the list of files:
�17
Step6b. [Android only]. Click the Download button and import the unitypackage:
Step6c [Android only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
�18
IronSource Setup Link to IronSource Unity SDK: https://developers.ironsrc.com/ironsource-mobile/unity/unity-plugin/
Step1. Download the IronSource Unity SDK from the link above.
Step2. Import the IronSource SDK into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select IronSource in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the IronSource settings found in the new IronSource Settings box that appears after you selected IronSource in one of the drop-downs.
Step5a [Android only]. Download the Google Player Services Resolver plugin by clicking this link: https://github.com/googlesamples/unity-jar-resolver and clicking the play-services-resolver.x.x.x.x.unitypackage in the list of files:
Step5b. [Android only]. Click the Download button and import the unitypackage:
�19
Step5c [Android only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
Step6. [Android only] Open the AndroidManifest located in the folder Plugins/Android/IronSource and remove everything in the application element except for the three IronSource activities. Your AndroidManifest should look something like this:
�20
MoPub SetupLink to MoPub Unity SDK: https://github.com/mopub/mopub-unity-sdk/releases
Step1. Download the latest MoPub Unity SDK by clicking the link above then clicking on MoPubUnity.unitypackage:
Step2. Import the MoPubUnity.unitypackage into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select MoPub in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the MoPub settings found in the new MoPub Settings box that appears after you selected MoPub in one of the drop-downs.
�21
Step6 [Android only]. Make sure the play services resolver that comes with the GoogleMobileAds plugin has executed by selecting the menu item Assets -> Play Services Resolver -> Android Resolver -> Resolve.
�22
UnityAds Setup
Step1. Enable Ads in the Services window:
Step2. *** IMPORTANT *** Make sure “Enable built-in Ads Extension” is disabled or it will collide with the Monetization plugin you will import in the next step. To do so expand the Advanced section and un-check the field if it is checked:
�23
Step2. Open the Asset Store window and Download/Import the Unity Monetization asset:
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select UnityAds in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the UnityAds settings found in the new UnityAds Settings box that appears after you selected UnityAds in one of the drop-downs.
�24
Vungle Setup Link to Vungle Unity SDK: https://dashboard.vungle.com/sdk
Step1. Download the Vungle Unity SDK from the link above by selecting one of the “Download Unity Plugin” links beside the Unity logo.
Step2. Import the Vungle Unity SDK into your project.
Step3. Click the Detect SDKs button on the Mobile Ads Settings window:
Step4. Select Vungle in one or more of the drop-downs on the Mobile Ads Settings window.
Step5. Fill in the Vungle settings found in the new Vungle Settings box that appears after you selected Vungle in one of the drop-downs.
�25
Mediation - Custom Setup Custom mediation is for when you want to use more that one ad network for an ad type to better increase the chances or an ad to be loaded and shown to the user.
The way custom mediation works in the Mobile Ads asset is when an ad needs to be loaded it starts with the ad network at the top of the priority list. If that ad network fails to load an ad it tries the next ad network in the list and continues down the list until an ad network successfully loads an ad. When an ad is shown it uses the ad from the ad network that successfully loaded. When it needs to load another ad it starts at the top of the list again and repeats the cycle.
To enable custom mediation select it in one or more of the drop-downs on the Mobile Ads Settings window:
Notice you can still select individual ad networks for other ad types in-case you only want to use mediation for certain types of ads.
When you select custom mediation a new section will appear called Mediation- Custom Settings. Expand it and you can select the ad networks you would like to use for each ad type/platform.
The networks drop-down is a multi-select drop-down so you can select multiple ad networks:
�26
After you have selected all the ad networks you want to use you can drag them in the Priority Queue to set which ones get priority. When an ad needs to be loaded it will start with the ad network at the top of this list and work its way down until an ad network successfully loads an ad.
When you select an ad network in one of the custom mediation drop-downs the ad networks settings section will appear:
At this point you should follow the setup guides above for each individual ad network you selected. Once you setup each ad network you are good to go, the MobileAdsManager will know to use custom mediation when showing ads.
�27
Mediation - AdMob Setup
Step1. AdMob mediation can be setup by selecting Mediation - AdMob in one or more of the drop-downs on the Mobile Ads Settings window.
Two new sections will appear at the bottom of the window: Mediation - AdMob Settings and AdMob Settings.
Step2. Follow the steps in the AdMob Setup section of this documentation to setup AdMob.
Step3. In the Mediation - AdMob Settings section, select the ad networks you plan on using with AdMob mediation.
You will need to download/import the AdMob Mediation Adapter SDK for each of the ad networks you selected.
Step4. Click the links below for the ad networks that you selected.
AdColony: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsAdColonyMediation
AppLovin: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsAppLovinMediation
Chartboost: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsChartboostMediation
IronSource: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsIronSourceMediation
MoPub: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsMoPubMediation
UnityAds: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsUnityAdsMediation
Vungle: https://bintray.com/google/mobile-ads-adapters-unity/GoogleMobileAdsVungleMediation
�28
Step5. On the page the link takes you to, click on the Files menu item:
Step6. Select the file with the highest version number to download:
Step8. Import the adapters unitypackage into your project.
�29
Step9. Click the Detect SDKs button on the Mobile Ads Settings window:
Step10. Setup the AdMob mediation settings on you AdMob account by following the steps on the google site for each ad network you selected
AdColony: https://developers.google.com/admob/unity/mediation/adcolony
AppLovin: https://developers.google.com/admob/unity/mediation/applovin
Chartboost: https://developers.google.com/admob/unity/mediation/chartboost
IronSource: https://developers.google.com/admob/unity/mediation/ironsource
MoPub: https://developers.google.com/admob/unity/mediation/mopub
UnityAds: https://developers.google.com/admob/unity/mediation/unity
Vungle: https://developers.google.com/admob/unity/mediation/vungle
�30
Troubleshooting Here are some common errors you may run into when adding ad networks to the project and making builds.
Google Version Handler Popup
If you ever get a popup that looks like this:
It just means that more than one play-services-reslover has been added to the project and the older version one should be removed so click Yes.
Error CS1704
If you get an compilation error in the Unity console that says:
“error CS1704: An assembly with the same name `Google.JarResolver' has already been imported. Consider removing one of the references or sign the assembly”
Then there might be duplicated play services resolver plugins. Open the folder PlayServicesResolver/Editor and delete any duplicated files that have similar names (Try and delete the one that has a lower version than the other or the one that has no version):
Check next page for example screenshot.
�31
If you are ever in doubt about which ones you should delete you can just delete the whole PlayServicesResolver folder and download/import the play-services-resolver plugin from Google by following the steps below:
Step1. Download the Google Player Services Resolver plugin by clicking this link: https://github.com/googlesamples/unity-jar-resolver and clicking the play-services-resolver.x.x.x.x.unitypackage in the list of files:
Step2. Click the Download button and import the unitypackage:
�32
Gradle Error: Resource Not Found
When making an Android build you could get a popup that says “Resource ‘@integer/google_play_services_version’ not found in AndroidManifest.xml”:
If you get this popup you need to search all AndroidManifests for this line:
<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
It will most likely be in the AndroidManifest that comes with the ad network SDK mentioned in build progress bar when the popup appeared. For example in the above screenshot, under the blue progress bar, is says “Task IronSource:generateReleaseBuildConfig”. So the above line will most likely be in the Plugins/Android/IronSource/AndroidManifest.xml file.
Once you locate the line you should remove it and add it to the Plugins/Android/AndroidManifest.xml file. If that AndroidManifest.xml file does not exist then create one and add the following text to it:
<?xml version="1.0" encoding="utf-8"?><manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.bbg.testads" > <application> <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /> </application></manifest>
�33
Gradle Error: Colliding Attributes
When making an Android you could get a popup that says “The attribute ___ collides with another value”:
This usually means there are two AndroidManifest.xml files that contains the same activity element. This is because AndroidManifests that come with the MoPub and IronSource contain a bunch of activity elements for other ad networks since then support mediation.
To fix this error, follow the steps below if you have MoPub and/or IronSource included in your project:
MoPub
Open the AndroidManifest located in the folder MoPub/Plugins/Android/MoPub.plugin and delete everything except for the MoPub SDK activities.
Check the next page for a screenshot of what you MoPub AndroidManifest should look like.
IronSource
Open the AndroidManifest located in the folder Plugins/Android/IronSource and delete everything except for the IronSource activities.
Check the next page for a screenshot of what you IronSource AndroidManifest should look like.
�34
MoPub:
IronSource:
�35
Build failure - Multiple dex files
When making an Android build you could get a popup that contains the text Multiple dex files.
If you get this popup it means there are duplicated jar files somewhere in the project. Currently all but one of the ad network SDKs that use google jars utilize the play services resolver which takes care of duplicates for us. Vungle includes it’s required jar files in its SDK manually. So if you are getting this error then try deleting the following jar files from the Plugins/Android/Vungle_lib/libs folder:
�36
If you haven’t included Vungle or after deleting those files you are still getting the “Multiple dex files” error then there must be other duplicated jar files in your project. You will have to search for these duplicated jar files and delete one of them. Easiest way to do this is go through every Plugins/Android folder you have in your project and search for files with similar names. For example, in Vungle libs folder there was a file called “common-1.1.0” so I search for common and found that there is already a similar jar included:
�37
Build failure - DexIndexOverflowException
When making and Android build you could get a popup that says “DexIndexOverflowException: Cannot merge new index 65618 into a non-jumbo instruction!”
You will get this error after import a bunch of ad network SDKs. Generally, it means there are to many jar files included in the project and the build system cant handle it.
To fix this you will need to enable multi-dex in your project, to do so follow the steps below:
Step1. Open Build Settings and make sure the Build System is set to Gradle.
Step1. Open Player Settings, expand Publishing Settings, and enable Custom Gradle Template.
Step3. Open the mainTemplate.gradle that was created and can be found in Assets/Plugins/Android.
�38
Step4. In the android / defaultConfig section add the line multiDexEnabled true:
Step5. Open Player Settings and set your Minimum API Level to 21 or higher.