Ads | Plankton Documentation

Introduction

Plankton's advertising functionality allows you to effortlessly incorporate ads into your Unity games, facilitating game monetization and improving user engagement. In the latest Plankton release, ads can be displayed through two mediation options: AdMob Mediation and AppLovin MAX.

These mediations let you serve ads to your games from multiple sources, so they will maximize your fill rate and increase your monetization by sending ad requests to multiple networks to ensure you find the best available network to serve ads.

Supported Ad Formats:

Banner
Interstitial
Rewarded

Before you begin

Prerequisites

Complete the Plankton setup
For Android
- Set Target API Level to 33 or higher
- Set Minimum Api Level to 21 or higher
For iOS
- Set Target Minimum iOS Version to 15.0 or higher

note

You can change Minimum and Target versions in Unity from Edit > Project Settings > Player > Other Settings

Set up your mediation account

Create and set up an account for each ad mediation you want to use.

AdMob

Set up your game in your AdMob account and create your desired ad units. After finishing the setup, you will have a unique AdMob App ID that is needed later in this guide.

AppLovin MAX

Set up your game in your AppLovin account and create your desired ad units. After finishing the setup, you will have a unique AppLovin SDK Key that is needed later in this guide.

info

You can use both of these mediations together in your game. For example you can show interstitial ads from AdMob, but show rewarded ads from AppLovin MAX.

Be aware that this multi-mediation feature is only applicable for different ad types, so it's not possible to use two mediations for the same ad type.

Confiure Plankton settings

Open plankton settings by going to Edit > Project Settings > Plankton.
Select the checkbox of your ad mediation. Below each mediation, there is an App Id field and several ad networks.
Fill the App Id field with your AdMob App ID or AppLovin SDK Key
Select ad networks that you have enabled in your mediation account. See available ad networks.

Implementation

Now it's time to write a few lines of code. Always import the Plankton package in your scripts.

using Plankton;

Initialize

Before displaying any ads, you must initialize the Plankton.Ad class with your ad unit IDs. For each ad format, you should pass a provider enum (Ad.Provider) along with a unit ID string. Lastly there is a callback parameter which is invoked when the initialization process completes. Make sure that all ads-related actions, such as displaying ads, are executed only after the initialization is done.

Pass the values in the order demonstrated below:

var bannerProvider = Ad.Provider.Admob; // or Ad.Provider.AppLovin
var bannerUnitId = "<YOUR_BANNER_UNIT_ID>";

var interstitialProvider = Ad.Provider.Admob;
var interstitialUnitId = "<YOUR_INTERSTITIAL_UNIT_ID>";

var rewardedProvider = Ad.Provider.Admob;
var rewardedUnitId = "<YOUR_REWARDED_UNIT_ID>";

Ad.Initialize(
    bannerProvider, bannerUnitId, 
    interstitialProvider, interstitialUnitId, 
    rewardedProvider, rewardedUnitId,
    () => {
        Debug.Log("Ad initialization completed!");
    }
);

note

If you don't use an ad format, pass an empty string for its unit id.

info

After calling initialize, Plankton will take care of the loading and preparation of ads, so you don't have to. Just show ads whenever you want. Plankton takes care of the technical details behind the scenes.

Banner ads are rectangular ads that occupy a small portion of an app's layout and are fixed at either the top or bottom of the screen. They stay on screen while users are interacting with the app and refresh automatically after a certain period of time.

To show a banner at the bottom of the screen:

Ad.Banner.ShowAtBottom()

To show a banner at the top of the screen:

Ad.Banner.ShowAtTop()

To hide the currently displayed banner:

Ad.Banner.Hide();

That's all it takes!

info

Only one banner ad can be displayed at a time. For example, if a banner is displayed at the bottom and you call ShowAtTop, the banner at the bottom will be hidden, and a new banner will be displayed at the top.

Interstitial Ads

Interstitial ads are full-screen ads typically displayed at natural transition points or breaks in the game's flow. Users can either interact with the ad or close it to return to the game.

Here's a sample code that shows how to display an interstitial ad:

Ad.Interstitial.Show(
    (displayed) => Debug.Log($"Interstitial Ad result - displayed: {displayed}"), 
    "AD_PLACEMENT"
);

This method takes two arguments:

Callback: A method invoked after the ad is closed or if it fails to show. The displayed parameter (boolean) indicates whether the ad was successfully displayed or not.
Placement(optional): A short string that specifies where the ad is being displayed (e.g. "end_of_level").

What is a placement?

A placement is a short string specifying the location of the ad being displayed. Placements are usually used for data analysis or user attribution purposes.

Common interstitial ad placements include:

When a player reaches the end of a level: for example end_of_level

Common rewarded ad placements include:

When a player watches an ad to get free coins: for example free_coins
When a player watches an ad to unlock a bonus item: for example unlock_bonus

tip

Interstitial ads should be displayed during natural pauses in the flow of an app. Between levels of a game is a good example, or after the user completes a task.

Rewarded Ads

Rewarded ads are full-screen ads that allow you to reward users with in-app items, such as virtual currency or bonus items, for interacting with video ads, playable ads, and surveys.

Here's how you can display a rewarded ad:

Ad.Rewarded.Show(
    (displayed, rewardEarned) => Debug.Log($"Rewarded Ad result - displayed: {displayed}, reward earned: {rewardEarned}"), 
    "AD_PLACEMENT"
);

This method takes two arguments:

Callback: A method invoked after the ad is shown or if it fails to show. The callback receives two boolean parameters:
- displayed: Indicates whether the ad was successfully displayed or not.
- rewarded: Indicates whether the user earned the reward or not.
Placement(optional): A short string specifying where the ad is displayed (e.g. "free_coins" or "unlock_bonus").

Check if an ad is ready to show

To ensure the ad is loaded before showing interstitial and rewarded ads, you can call Ad.IsLoaded.

bool isInterstitialLoaded = Ad.IsLoaded(Ad.Type.Interstitial)

bool isRewardedLoaded = Ad.IsLoaded(Ad.Type.Rewarded)

tip

Plankton loads and prepares interstitial and rewarded ads automatically. Before attempting to display the ad, it's best to check if the ad is loaded as the loading process can take a few seconds.

Test and debug

Both AdMob and AppLovin provide their own debugging tools which can be used at runtime to test and debug the advertisement feature.

Admob Ad Inspector

AdMob's Ad Inspector is an in-app overlay that enables authorized devices to perform real-time analysis of test ad requests directly within a mobile app.

To display it in your game, make the following call:

Ad.OpenAdMobDebugger();

You can read more about AdMob's Ad Inspector.

AppLovin Mediation Debugger

AppLovin's Mediation Debugger is a suite of testing tools that help you integrate and launch faster with MAX. You can use them to confirm the validity of network integrations. This ensures that you can successfully load and show ads, among other things.

To display it in your game, make the following call:

Ad.OpenAppLovinMaxDebugger();

Available Ad networks

AdMob mediation

Android
- AppLovin
- Chartboost
- DT Exchange (Fyber)
- ironSource
- Liftoff (Vungle)
- Meta (Facebook)
- Mintegral
- Pangle
- Premium Ads
- Unity Ads
iOS
- AppLovin
- ironSource
- Liftoff (Vungle)
- Meta (Facebook)
- Mintegral
- Pangle
- Premium Ads
- Unity Ads

AppLovin MAX mediation

Android
- AdMob
- DT Exchange (Fyber)
- ironSource
- Liftoff (Vungle)
- Meta (Facebook)
- Mintegral
- Pangle
- Premium Ads
- Unity Ads
iOS
- AdMob
- Google Ad Manager
- ironSource
- Liftoff (Vungle)
- Meta (Facebook)
- Mintegral
- Pangle
- Premium Ads
- Unity Ads

Need other networks?

If you need other ad networks that are missing in our list, please let us know at our Discord server or via Email.

Impression-Level Revenue Data (ILRD)

What is ILRD?

Impression-Level Revenue Data (ILRD) refers to granular revenue data associated with individual ad impressions. This data provides detailed insights into how much revenue each ad impression generates.

Use Case and Benefits:

Accurate Revenue Tracking: Gain visibility into your revenue streams on a per-impression basis.
Enhanced Analytics: Understand the performance of different ad placements, networks, and formats.
Attribution: Share ILRD with analytics and attribution providers like AppsFlyer or Tenjin for advanced reporting and user-level attribution.

info

If you use AppsFlyer or Tenjin through Plankton, ILRD data is automatically sent to these platforms. You don’t need to do any extra work.

For GameAnalytics, you can subscribe to ILRD data so that Plankton will automatically forward this information to GameAnalytics.

Listening to ILRD Data

Plankton makes it easy to capture ILRD data from both AdMob and AppLovin MAX.

AdMob

You can subscribe to AdMob ILRD by adding a delegate to OnAdMobImpressionRevenue event. The result parameter is an object of the class AdMobImpressionRevenue.

Ad.OnAdMobImpressionRevenue += result => 
{
    if (result != null)
    {
        Debug.Log($"{logName} OnAdMobImpressionRevenue: adType={result.adType}, networkName={result.networkName}, adUnitId={result.adUnitId}, currencyCode={result.currencyCode}, precision={result.precision}, revenue={result.revenue}, adMobSdkVersion={result.adMobSdkVersion}, responseId={result.responseId}");
    }
};

AppLovin MAX

You can subscribe to AppLovin MAX ILRD by adding a delegate to OnAppLovinMaxImpressionRevenue event. The result parameter is an object of the class AppLovinMaxImpressionRevenue.

Ad.OnAppLovinMaxImpressionRevenue += result => 
{
    if (result != null)
    {
        Debug.Log($"{logName} OnAppLovinMaxImpressionRevenue: adType={result.adType}, networkName={result.networkName}, adUnitId={result.adUnitId}, country={result.country}, precision={result.precision}, creativeId={result.creativeId}, revenue={result.revenue}, appLovinSdkVersion={result.appLovinSdkVersion}, placement={result.placement}");
    }
};

API Refrences

Defined Types

In this section, we will discuss the enumerated types, variables, and classes associated with this feature:

Enums

Ad.Provider

Values	Description
Admob	You can use Admob mediation as an ad mediation SDK in your game.
AppLovin	You can use AppLovin Max as an ad mediation SDK in your game.

Ad.Type

Values	Description
Null	Specifies no ads.
Interstitial	Specifies full-screen ads that appear at natural breaks or transition points within an app.
Rewarded	Specifies ads that offer users a reward, such as in-app currency or extra content, in exchange for engaging with the ad.
Banner	Specifies small, rectangular ads displayed at the bottom of an app's interface.

AdMobImpressionPrecision : int

Values	Description
Undefined = 0	When there are no sources of data available for AdMob to calculate a revenue value.
Estimated = 1	An ad value estimated from aggregated data
PublisherProvided = 2	The manual CPM you entered for your waterfall ad source instance in a mediation group.
Exact = 3	The precise value paid for the ad. This is only available for the AdMob Network and your bidding ad sources. If AdMob cannot provide a precise value for the bidding ad source, the precision will be estimated.

Classes

Ad.AdMobImpressionRevenue

Field Name	Field Type	Default Value	Field Description
adUnitId	string	string.Empty	The unique identifier for the ad
adType	string	string.Empty	The type of ad (e.g. banner, interstitial, rewarded)
currencyCode	string	string.Empty	The currency in which the revenue is reported (e.g. "USD")
networkName	string	string.Empty	The name of the ad network that served the ad.
revenue	long	0	The revenue amount generated by the impression
responseId	string	string.Empty	AdMob's response ID.
adMobSdkVersion	string	string.Empty	The version of the AdMob SDK
precision	AdMobImpressionPrecision	.Undefined	The level of precision in the revenue value

Ad.AppLovinMaxImpressionRevenue

Field Name	Field Type	Default Value	Field Description
adUnitId	string	string.Empty	ID of the MAX Ad Unit from which the revenue was generated.
adType	string	string.Empty	The type of ad (e.g. BANNER, INTER, REWARD)
country	string	string.Empty	The two-letter country code of the impression
placement	string	string.Empty	The Ad Placement Name where the user generated impressions and revenue.
networkName	string	string.Empty	The Ad Network that generated the impression.
revenue	long	0	The revenue generated by the user, in USD, expressed with six-decimal precision.
creativeId	string	string.Empty	The unique identifier of the creative.
appLovinSdkVersion	string	string.Empty	The version of the AppLovin SDK
precision	string	string.Empty	The level of precision in the revenue value

Properties and Delegates

Properties

Name	Type	Default Value	Description
IsOnline	bool	true	Use this to check if the user is online.

Delegates

Name	Type	Default Value	Description
OnAdMobImpressionRevenue	Action<AdMobImpressionRevenue>	null	Set revenue listener (ILRD) for AdMob
OnAppLovinMaxImpressionRevenue	Action<AppLovinMaxImpressionRevenue>	null	Set revenue listener (ILRD) for AppLovin MAX

Methods Summaries

Method	Arguments	Return Type	Description
Initialize	Provider bannerProvider, string bannerZoonId, Provider interstitialProvider, string interstitialZoonId, Provider rewardedProvider, string rewardedZoonId, Action callback	void	You have to initialize “Ad” before trying to show ads. Call this function before any attempt to request ads. The `callback` will be invoked once the feature is initialized.
Banner.ShowAtBottom	string placement = "bottom"	void	Display a banner ad at the bottom of the screen.
Banner.ShowAtTop	string placement = "top"	void	Display a banner ad at the top of the screen.
Banner.Hide	(no arguments)	void	Hide the currently displaying banner ad.
Interstitial.IsLoaded	(no arguments)	bool	This method checks if an interstitial ad is loaded and can be shown.
Interstitial.Show	Action<bool> onResult = null, string placement = "interstitial"	void	Displays an interstitial ad and accepts a callback to determine whether the ad was successfully displayed. The `callback` is invoked after the ad is shown or fails to show, with a boolean `displayed` indicating if the ad was shown. The `placement` parameter is a string specifying the placement of the ad.
Rewarded.IsLoaded	(no arguments)	bool	This method checks if a rewarded ad is loaded and can be shown.
Rewarded.Show	Action<bool, bool> onResult = null, string placement = "rewarded"	void	Displays a rewarded ad and accepts a callback to determine whether the ad was displayed and if a reward was granted to the user. The `callback` is invoked after the ad is shown or fails to show, with a boolean `displayed` indicating if the ad was shown and a boolean `rewardEarned` indicating if the reward was granted. The `placement` parameter is a string specifying the placement of the ad.
OpenAdMobDebugger	(no arguments)	void	It opens Admob Ad Inspector for debugging Admob.
OpenAppLovinMaxDebugger	(no arguments)	void	It opens Applovin Max Mediation Debugger for debugging Applovin Max.
GetAndroidAdId	(no arguments)	string	Returns the Google Ad ID of the device.(Android Only)

Introduction​

Before you begin​

Prerequisites​

Set up your mediation account​

AdMob​

AppLovin MAX​

Confiure Plankton settings​

Implementation​

Initialize​

Banner Ads​

Interstitial Ads​

Rewarded Ads​

Check if an ad is ready to show​

Test and debug​

Admob Ad Inspector​

AppLovin Mediation Debugger​

Available Ad networks​

AdMob mediation​

AppLovin MAX mediation​

Impression-Level Revenue Data (ILRD)​

What is ILRD?​

Listening to ILRD Data​

AdMob​

AppLovin MAX​

API Refrences​

Defined Types​

Enums​

Ad.Provider​

Ad.Type​

AdMobImpressionPrecision : int​

Classes​

Ad.AdMobImpressionRevenue​

Ad.AppLovinMaxImpressionRevenue​

Properties and Delegates​

Properties​

Delegates​

Methods Summaries​

Introduction

Before you begin

Prerequisites

Set up your mediation account

AdMob

AppLovin MAX

Confiure Plankton settings

Implementation

Initialize

Banner Ads

Interstitial Ads

Rewarded Ads

Check if an ad is ready to show

Test and debug

Admob Ad Inspector

AppLovin Mediation Debugger

Available Ad networks

AdMob mediation

AppLovin MAX mediation

Impression-Level Revenue Data (ILRD)

What is ILRD?

Listening to ILRD Data

AdMob

AppLovin MAX

API Refrences

Defined Types

Enums

Ad.Provider

Ad.Type

AdMobImpressionPrecision : int

Classes

Ad.AdMobImpressionRevenue

Ad.AppLovinMaxImpressionRevenue

Properties and Delegates

Properties

Delegates

Methods Summaries