Unity Mediation Integration (v8.5.1 & below)

Getting Started

This documentation will help you integrate ConsoliAds Mediation Unity plugin to get instant access to the best ad networks around the globe for optimized mobile ad analytics and earnings.

Before you proceed to integrate, make sure you have:

• Registered at ConsoliAds portal
• Logged in to the ConsoliAds dashboard ConsoliAds portal

Create an App

NOTE: You can skip this step if you’ve already created your app on ConsoliAds dashboard

1. From the left side bar, navigate to Apps-> New App

2. Simply import your Live app or manually enter the required information and proceed to ‘Finish’ to instantly create your app

Download & Import SDK

1. Download the latest ConsoliAds Mediation plugin for your required Unity version from https://portal.consoliads.com/download/unity

Note: Use ‘Recommended Mediation Unity Plugin with 7 Ad Networks’ for faster and easier integration yet ensuring maximum revenues

2. Open your Unity Project and import the downloaded plugin; ignore any warnings that may appear

Add Prefab to your Scene

1. In your project explorer, go to “Assets\ConsoliAds\Prefab” or search for “ConsoliAds”

2.  Drag and drop ConsoliAds prefab into your scene

3. In your scene hierarchy tab, select the ConsoliAds prefab and you should be able to see ConsoliAds inspector view

Fill up Inspector Information

Fields marked with * are mandatory in order for the inspector to successfully sync with the server

1. User signature(*) is essential to identify the user according to his role and rights provided on the ConsoliAds dashboard in order to configure settings of the specific app from the Unity inspector

a. The user signature can be obtained by going to your Personal Info by clicking on your name in the right corner of the top bar on your dashboard.

b. Copy the required user signature for the inspector view

2. App Name(*) is the name of your app being developed

3. Platform(*) (Google, Apple, Amazon) is used by ConsoliAds ONLY to fetch the information of your app according to the given platform from the ConsoliAds dashboard.

4. Bundle Identifier(*) is your application’s unique package name such as com.x.y

5. More Apps URL is a link to all your apps available on the relevant App Store which may be used in the app to promote your other apps. This URL is fetched from Brand details on the ConsoliAds dashboard.

6. Rate Us URL is a link to get an effective rating from your user which may be used in the app. This URL is fetched from App details on the ConsoliAds dashboard

7. Support Email is the email that you may want to use in your app to help users to contact your support. This email is also fetched from Brand details on the ConsoliAds dashboard.

8. Dev Mode(*) when turned ON simulates the development environment and prevents developers from changing Live app settings. Complete app development should be done with ‘Dev Mode’ ON. When an app is ready to be published, ‘Dev Mode’ MUST BE turned OFF. (NOTE: Don’t forget to see ‘More About Dev Mode’ section before making the final build)

9. Scenes Array(*) defines ad placeholders in your app where you intend to show ads such as Main Menu, Selection Scene, On Success etc. Ad placeholders are created for all ad formats supported by ConsoliAds

a. Size; expand ‘Scenes Array’ to enter ‘Size’ (figure: point 3) i.e. the number of placeholders you intend to create for your app. ‘Scene Array’ elements will be populated according to your given size.

b. Element #; Every element of the list represents a placeholder which requires the following information:
i.Placeholder Name
ii.Details for Interstitial and Video, Rewarded Video, Native, Banner and Icon ads that are required on the given placeholder. You can also further change these details from the dashboard even when the app goes Live.

10. Ad ID List are the Ad IDs required for the ad networks that are not automatically available with ConsoliAds but require API integration. These ad networks include Admob, Chartboost and Facebook

Configure Server

1. Configure Server button performs a two way sync of your app’s Dev Placeholders on the dashboard that makes use of your given app information. The sync works as follows:

a. If the placeholders list size and names are same, the developer will be able to pull ad network specific configurations from the dashboard

b. If the placeholders list size is set to 0, you can pull all the Live Placeholders configuration from the dashboard. This is very important and useful for developers when updating to newer versions of ConsoliAds plugin in order to fetch settings from the dashboard

2. Ad ID List: Ad IDs in ConsoliAds are treated as ownership of the managers. Hence, IDs are pulled from the dashboard irregardless of the ones provided in the inspector.

NOTE: Configure Server DOES NOT change any Live configurations of the app. The settings have to be ‘Move To Live’ before the app goes Live on the app store

Ready to Code

Plugin Initialization

ConsoliAds mediation needs to be explicitly initialized, using the following code, once the prefab is active:

ConsoliAds.Instance.initialize(bool userConsent);

userConsent: TRUE if user agrees to share his data and opts for personalized ads, FALSE otherwise. This flag is used for GDPR and CCPA compliance.

NOTE: userConsent cannot be modified once ConsoliAds is initialized

Show Interstitial/Video Ad

Add the following lines of code to show an interstitial ad in your app:

ConsoliAds.Instance.ShowInterstitial(int sceneIndex);

sceneIndex: index of the placeholder from the ‘Scenes Array’ in the ConsoliAds prefab

e.g. if MainMenu is your first placeholder and you wish to show Interstitial on it, then your code will look like:

ConsoliAds.Instance.ShowInterstitial(0);

NOTE: the respective placeholder must have an ad network added, else no ad will be displayed

Show Rewarded Video Ad

Load Rewarded Ad

Showing rewarded video requires loading it beforehand. Use the following to load a rewarded ad:

ConsoliAds.Instance.LoadRewarded(int sceneIndex);

It is highly recommended to call LoadRewarded(sceneIndex) as early as possible e.g. in the Start() method of a script to allow videos to be pre-loaded.

Availability of Rewarded Ad

Despite having the ad load called, rewarded video availability should be explicitly checked. Check rewarded video ad availability by using following method:

ConsoliAds.Instance.IsRewardedVideoAvailable (int sceneIndex);

Return value (boolean):

• True if the ad is available
• False if the ad is not available

Show Rewarded Video

ConsoliAds.Instance.ShowRewardedVideo(int sceneIndex);

sceneIndex: index of the placeholder from the ‘Scenes Array’ in the ConsoliAds prefab
e.g. if MainMenu is your first placeholder and you wish to show rewarded video on it, then your code will look like:

ConsoliAds.Instance.ShowRewardedVideo(0);

NOTE: the respective placeholder must have an ad network added, else no ad will be displayed

Reward Users

In order to reward your user, a callback needs to be implemented with your lines of code to incentivize the user. ConsoliAds mediation implements a single callback irregardless of any ad network used.

In the Start() method of your script use the following code to attach your functions with ConsoliAds Rewarded Video Completed callback:

ConsoliAds.onRewardedVideoAdCompletedEvent +=
onRewardedVideoCompleted;

Provide the following definition of the method to reward your users:

public void onRewardedVideoCompleted()
{
    // Write your code to reward your user here
}

Show Banner Ad

Before adding lines of code to show banner, please be sure that you have specified banner ‘Ad Type’ and ‘Size’ from the ConsoliAds prefab inspector as shown

To show banner ad you need to first create a ConsoliAdsBannerView object which can be initialized as:

ConsoliAdsBannerView consoliAdsBannerView = new ConsoliAdsBannerView();

Now use the following code to display the banner:

ConsoliAds.Instance.ShowBanner(int sceneIndex , consoliAdsBannerView  );

To hide Banner, use the following:

ConsoliAds.Instance.HideBanner(consoliAdsBannerView );

Show Native Ad

When integrating Native ads please keep the following prerequisites in mind:

• Prefab of native ad must be dragged inside the canvas.
• Main Camera must be tagged with MainCamera.
• In the prefab of native ad pos Z value is “0”. You only need to set x and y of the prefab.
• Press ctrl+S to save the settings of prefab and do not click on the Apply button in Unity.

Use the following steps to directly integrate native ad using prefab:

3. Drag the ‘ConsoliAdsNative’ prefab into your scene (figure: point 1).

4. Add ‘Scene Index’ to show native Ad (figure: point 4). ‘Scene Index’ is the index of a scene that you have added on the dashboard.

5. ‘ConsoliAdsNative’ prefab has its own script and automatically shows the ad when prefab initiates.

NOTE: You can change the height and width of the native ad as per your need

Native ads mediation is supported for following ad networks:

Facebook, Admob, ConsoliAds ,Applovin ,StartApp,Mopub ,Mintegral

Show Icon Ad

While integrating Icon ads, please keep the following prerequisites in mind:

• Prefab of icon ad must be dragged inside the canvas.
• Main Camera must be tagged with MainCamera.
• In the prefab of native ad pos Z value is “0”. You only need to set x and y of the prefab.
• Press ctrl+S to save the settings of prefab and do not click on the Apply button in Unity.

Use the following steps to directly integrate native ad using prefab:

1. Drag the ‘ConsoliAdsIconAd’ prefab into your scene (figure: point 1).

2. Add ‘Scene Index’ to show Icon ad (figure: point 4). ‘Scene Index’ is the index of a scene that you have added in the dashboard.

3. ‘ConsoliAdsIconAd’ prefab has its own script and automatically shows the ad when the prefab initiates. You can choose your icon animation style.

NOTE: You can change the size (small, medium, large) of the icon ad as per your need.

Hide All Ads

If you want to hide all ads, except Rewarded Ads, from your entire app, use the following:

ConsoliAds.Instance.hideAllAds();

NOTE: You only need to call this method once in your script to hide all ads from your app

Using More Apps URL and Support Email

• The more apps URL and support email are added against a particular brand
• When an app of the respective brand is configured, the more apps URL and support email are available for use
• To access more apps URL, use:

ConsoliAds.Instance.MoreFunURL()

• To access support email, use:

ConsoliAds.Instance.SupportEmail()

More About Dev Mode

For ConsoliAds native ad following are the required elements:

• Configuring / Syncing any app from inspector won’t affect the live configurations of your app.
• Every time you use Configure Server, the new settings would be pushed to the ‘Dev Placeholders and Ads’ tab on the dashboard.
• If you make your build with ‘Dev Mode’ enabled, the ad configurations from ‘Dev. Placeholder and Ads‘ tab on the dashboard would be used.
• If you make your build with ‘Dev Mode’ disabled, the ad configurations from ‘Live Placeholder and Ads‘ tab on the dashboard would be used.

Applying Dev Settings to Live

In order to see the ‘Dev Mode’ settings on ConsoliAds dashboard, open the ‘Placeholder and Ads‘ tab in the details of your specific app then click ‘Dev. Placeholder & Ads’ as shown below:

Here you will see all the changes you have made from the inspector. Click ‘Apply on Live App’ to apply these configurations to your live app.

Building for Android

Play Services Resolver

You need to download play services resolver for Android integration from the download Jar Resolver button in unity (as shown) or from the following site.

https://github.com/googlesamples/unity-jar-resolver/releases

• Download the zip file of the latest version.
• Unzip the above downloaded zip file and find the unity package of play resolver.
• Import it in your current project. It will automatically start downloading play services files. If it does not start automatically then you need to resolve it yourself. Go to Menu->Assets->Play Services Resolver -> Force Resolve.

Admob Android Manifest

NOTE: You can skip this step if you are not using Admob ad network plugin

Add the following metadata inside the Manifest application tag.

NOTE: ca-app-pub-3940256099942544~3347511713 is a test Application ID. You need to make sure that you add your Admob APPLICATION_ID available from your Admob dashboard.

AndroidX Support (Recommended)

To enable AndroidX support for your app:

• Go to your Play Service Resolver Android Settings and enable Jetifier.
• Your application will be required to have multi dex support when the Jetifier is enabled.

MultiDex Support

For Unity 2018

• In your android build settings on Unity enable Custom Gradle Template
• Add the following attribute in the application tag of your Android Manifest

android:name="androidx.multidex.MultiDexApplication"

• In mainTemplate.gradle add the following in dependencies section

implementation 'androidx.multidex:multidex:2.0.1'

• In mainTemplate.gradle add in defaultConfig

multiDexEnabled true

For Unity 2019

• Unity player setting enable the following

• Custom Main Manifest

• Custom Gradle Template

• Custom Launcher Gradle Template

• Custom Gradle Property Template

• Add the following attribute in the application tag of your Android Manifest:

 android:name="androidx.multidex.MultiDexApplication"

• In gradleTemplate.properties file add the following

android.useAndroidX=true

android.enableJetifier=true

• In the dependencies section of the launcherTemplate file, add the following:

 implementation 'androidx.multidex:multidex:2.0.1'

In the defaultConfig section of the launcherTemplate file, add the following:

 multiDexEnabled true

** Congratulations, You are ready to build your app on to your android mobile device to see all the ad placements showing ads according to your Test Mode **

Building for IOS

• Go to build settings-> player settings-> Other settings-> Target minimum iOS version set it to 8.0
• In your Xcode project, select your target Build Settings and make sure that you have added the following flag in “Other linker Flags”
• -ObjC
• In your Xcode project, select your target Build Settings and:
• Enable module option (c and objective-c)
• Enable Objective-C Exceptions
• In your Xcode project, select your target Build Phases, inside “Link Binaries With Libraries” drop down add these frameworks:
• Webkit.framework
• Add the following key/value pair in the plist:
• Key: gad_preferred_webview
• Value: wkwebview
• If you have made an Xcode build on a Windows PC, you may have to perform the following steps:
• Make sure that the following libraries and frameworks are linked to your project. if they are not automatically included, you need to manually add them.
• Libz.1.2.5.tbd
• Libz.tbd
• Libxml2.tbd
• Libobjc.tbd
• Libsqlite3.tbd
• AddressBook.framework
• AddressBookUI.framework
• SystemConfiguration.framework
• QuartzCore.framework
• MessageUI.framework
• MobileCoreServices.framework
• MediaPlayer.framework
• EventKitUI.framework
• EventKit.framework
• CoreData.framework
• CoreVideo.framework
• CoreMotion.framework
• CoreMedia.framework
• CoreMedia.framework
• CoreText.framework
• CoreGraphics.framework
• AVFoundation.framework
• AVKit.framework
• AudioToolbox.framework
• AdSupport.framework
• Social.framework
• StoreKit.framework
• Webkit.framework

Few Exceptions

• If you are using Admob please make sure to add this key in info plist GADApplicationIdentifier and set its value to your admob AppID
• If you are using Facebook and Mopub please embed the frameworks as following
• Embed the MoPub.xcframework by selecting target”unity-iphone” -> build phases ->Embed Framework
• Embed the FBAudienceNetwork.framework by selecting target”unity-iphone” -> build phases ->Embed Framework

For Unity 2019

Embed the FBAudienceNetwork.framework by selecting target”unity-iphone” -> build phases ->Embed Framework

Embed the MoPub.xcframework by selecting target”unity-iphone” -> build phases ->Embed Framework

** Congratulations, You are ready to build your app on to your iOS mobile device to see all the ad placements showing ads according to your Test Mode **

App settings on Consoliads Dashboard

After successfully integrating your app with ConsoliAds plugin, following app settings can be explored on the ConsoliAds dashboard in the App Details section:

Test Mode

By Default a new application is in Test Mode. In Test Mode only test ads are shown. Test Mode can ONLY be disabled by importing your app’s Live credentials in the Details tab.

Ad Network IDs

If you are using Admob, Facebook Audience Network or Chartboost you need to provide their Ad IDs on the dashboard in your app Ad Networks section.

All other integrated ad networks will automatically go Live once your app’s Test Mode is disabled.

Ad Filters

Apply all ad filters, for the integrated ad networks, with complete ease from the ConsoliAds dashboard in the Ad Filters section of the app details.

Debug Logs

If enabled, debug logs will be shown for your app in respective editors for Android and iOS.

Child Directed

Child Directed enables your application with complete COPPA compliance.

Hide Ads

All ads, except Rewarded Videos, can be completely turned OFF using Hide Ads on the dashboard.

Auto Mediation

Auto Mediation automatically optimizes your ad networks for each region and each ad format pertaining to every placeholder in your app such that you get the best eCPMs.

We highly recommend to use Auto Mediation in order to witness instant revenue increments upto 20%

For Advance Development

Check Interstitial Availability

You can also check for interstitial ad availability for a specific placeholder using the following method.

ConsoliAds.Instance.IsInterstitialAvailable (int sceneIndex);

Return value (boolean):

• True if the ad is available
• False if the ad is not available

More ConsoliAdsBannerView() definitions

ConsoliAdsBannerView object which can also be initialized according to the following function definitions:

• Using custom size

AdSize size = new AdSize (300,250);
ConsoliAdsBannerView consoliAdsBannerView = new ConsoliAdsBannerView( size );

• Using a custom position

AdPosition position = new AdPosition (100 , 200);
ConsoliAdsBannerView consoliAdsBannerView = new ConsoliAdsBannerView( position  );

• Using a custom size and position

AdSize size = new AdSize (300,250);
AdPosition position = new AdPosition (100 , 200);
ConsoliAdsBannerView consoliAdsBannerView = new ConsoliAdsBannerView( size  , position  );

Show/Hide Native Ad programmatically

1. In order to manually manipulate the native ad, remove the script attached with the ‘ConsoliAdsNative’ prefab.
2. Create a game object variable in your script.
3. Attach variable with the prefab that you have attached in your scene.

Show Native Ad Using ConsoliAds:

ConsoliAds.Instance.ShowNativeAd(GameObject nativeGameObject, int sceneIndex);

Hide Native Ad Using ConsoliAds:

ConsoliAds.Instance.HideNative(int sceneIndex);

Show/Hide Icon Ad programmatically

1. In order to manually manipulate the native ad, remove the script attached with the ‘ConsoliAdsIconAd’ prefab.
2. Create a game object variable in your script.
3. Attach variable with the prefab that you have attached in your scene.

Icon Ad Animation:

ConsoliAds supports pre-defined animations of icon ads. You need to pass the following animation type enum in the show call:

• NONE
• SHAKE
• PULSE

Show Icon Ad using ConsoliAds:

ConsoliAds.Instance.ShowIconAd(GameObject iconAdGameObject , int
sceneIndex , IconAnimationType.PULSE );

Hide Icon Ad using ConsoliAds:

ConsoliAds.Instance.DestoryIconAd (GameObject iconAdGameObject,int sceneIndex);

Show Multiple Icon Ads (TODO)

To show multiple Icon Ads, make sure you know all the steps required to display a single Icon Ad. Follow the below mentioned additional steps to display multiple Icon Ads:

• Search ‘ConsoliAdsIconAd’ from assets and drag it into Canvas.
• To duplicate or add multiple icon ads, select ‘ConsoliAdsIconAd’ in the scene and duplicate it by using the key combination command+D (or control+d on windows) as shown in figure: Point 1.
• You can change the X value of prefab (figure: Point 2), by dragging the red arrow horizontally, according to your placement need to show the icon ad.
• You can change the Y value of prefab (figure: Point 2), by dragging the red arrow vertically, according to your placement need to show the icon ad.
• To show IconAd you need to enter the sceneIndex for each IconAd prefab. (figure: Point 4)
• Every prefab has its own script. You just need to add prefab and enter sceneIndex, icon ad will be automatically shown when the prefab initiates.

Show Multiple Icon Ads Programmatically using ConsoliAds

• Create a variable of type GameObject.
• Use this game object as parameter to call:

ConsoliAds.Instance.ShowIconAd(GameObject iconAdGameObject , int sceneIndex , IconAnimationType.PULSE );

Hide Multiple Icon Ads Programmatically using ConsoliAds

• Use the same game object as parameter to call:

ConsoliAds.Instance.DestoryIconAd (GameObject iconAdGameObject_2,int sceneIndex);

Implementing Callback Events

ConsoliAds implements single callback events for all Ad Networks. Following callbacks can be used as per need:

    public static event Action onConsoliAdsInitializationSuccess;

Interstitial Callbacks:

public static event Action onInterstitialAdShownEvent;
public static event Action onInterstitialAdFailedToShowEvent;
public static event Action onInterstitialAdClosedEvent;
public static event Action onInterstitialAdClickedEvent;

Rewarded Video Callbacks:

public static event Action onRewardedVideoAdLoadedEvent;
public static event Action onRewardedVideoAdFailToLoadEvent;
public static event Action onRewardedVideoAdShownEvent;
public static event Action onRewardedVideoAdFailToShowEvent;
public static event Action onRewardedVideoAdCompletedEvent;
public static event Action onRewardedVideoAdClosedEvent;
public static event Action onRewardedVideoAdClickEvent;

Banner Callbacks:

public static event Action onBannerAdShownEvent;
public static event Action onBannerAdFailToShowEvent;
public static event Action onBannerAdClickEvent;
public static event Action onBannerAdRefreshEvent;

Icon Callbacks:

public static event Action onIconAdShownEvent;
public static event Action onIconAdFailedToShowEvent;
public static event Action onIconAdCloseEvent;
public static event Action onIconAdClickEvent;
public static event Action onIconAdRefreshEvent;

Native Callbacks:

public static event Action onNativeAdShownEvent;
public static event Action onNativeAdFailedToShownEvent;
public static event Action onNativeAdClickEvent;

Add Ad Network

1. Log in to your ConsoliAds dashboard and download your required ad network standalone plugin from https://portal.consoliads.com/download/adnetworksdk/unity

2. Double click on the downloaded package

3. A dialog box will appear, select All and click on “Import”.

Few Additional Settings

AdColony

If you have added AdColony, please add following flags for AdColony to work on iOS as well

         

Remove Ad Network

You can simply remove an ad network from your Unity project by using ConsoliAds menu from Unity menu bar.

• Select ConsoliAds from the Unity editor menu bar
• From the uninstall ad network list, select the ad network that you want to remove from your project

More Help Sources of Integration

ConsoliAds Sample Project:

You can download the sample project from https://portal.consoliads.com/download/unity to see complete ConsoliAds integration already implemented for all ad formats.

Youtube Videos:

You can watch short integrations videos on your youtube channel, https://www.youtube.com/watch?v=nExp4zfb0xc, to further explore integrations with ConsoliAds.

ConsoliAds GitHub forum

If you are having any technical issues, you can visit https://github.com/teamconsoliads/sampleapp-unity to view known issues, share problems and suggestions.