Advertising: Scripting

This section provides a guide to work with the Advertising module scripting API.

You can access the Advertising module API via the Advertising class under the EasyMobile namespace.

Working with Consent

Module Consent

The following snippet shows how you grant, revoke or read the module-level consent of the Advertising module.

// Grants the module-level consent for the Advertising module.
Advertising.GrantDataPrivacyConsent();

// Revokes the module-level consent of the Advertising module.
Advertising.RevokeDataPrivacyConsent();

// Reads the current module-level consent of the Advertising module.
ConsentStatus moduleConsent = Advertising.DataPrivacyConsent;

Vendor Consent

The following snippet shows how you grant, revoke or read the vendor-level consent of an individual network in the Advertising module.

In this example we use AdMob for demonstration purpose, the same code can be used for any other network.

// Grants the vendor-level consent for AdMob.
Advertising.GrantDataPrivacyConsent(AdNetwork.AdMob);

// Revokes the vendor-level consent of AdMob.
Advertising.RevokeDataPrivacyConsent(AdNetwork.AdMob);

// Reads the current vendor-level consent of AdMob.
ConsentStatus admobConsent = Advertising.GetDataPrivacyConsent(AdNetwork.AdMob);

Working with Banner Ads

To show a banner ad you need to specify its position using the BannerAdPosition enum. The banner will be displayed once it is loaded.

// Show banner ad
Advertising.ShowBannerAd(BannerAdPosition.Bottom);

To hide the current banner ad (it can be shown again later):

// Hide banner ad
Advertising.HideBannerAd();

To destroy the current banner ad (a new one will be created on the next banner ad showing):

// Destroy banner ad
Advertising.DestroyBannerAd();

Working with Interstitial Ads

The method to show an interstial ad requires it to be already loaded. Therefore you should check for the ad's availability before showing it.

// Check if interstitial ad is ready
bool isReady = Advertising.IsInterstitialAdReady();

// Show it if it's ready
if (isReady)
{
    Advertising.ShowInterstitialAd();
}

An InterstitialAdCompleted event will be fired whenever an interstitial ad is closed. You can listen to this event to take appropriate actions, e.g. resume the game.

// Subscribe to the event
void OnEnable()
{
    Advertising.InterstitialAdCompleted += InterstitialAdCompletedHandler;
}  

// The event handler
void InterstitialAdCompletedHandler(InterstitialAdNetwork network, AdPlacement placement)
{
    Debug.Log("Interstitial ad has been closed.");
}

// Unsubscribe
void OnDisable()
{
    Advertising.InterstitialAdCompleted -= InterstitialAdCompletedHandler;
}

Working with Rewarded Ads

The method to show a rewarded ad requires it to be already loaded. Therefore you should check for the ad's availability before showing it.

// Check if rewarded ad is ready
bool isReady = Advertising.IsRewardedAdReady();

// Show it if it's ready
if (isReady)
{
    Advertising.ShowRewardedAd();
}

A RewardedAdCompleted event will be fired whenever a rewarded ad has completed. You should listen to this event to reward the user for watching the ad. Otherwise, a RewardedAdSkipped event will be fired if the ad is skipped before finishing (and the user therefore is not entitled to the reward).

// Subscribe to rewarded ad events
void OnEnable()
{
    Advertising.RewardedAdCompleted += RewardedAdCompletedHandler;
    Advertising.RewardedAdSkipped += RewardedAdSkippedHandler;
}

// Unsubscribe events
void OnDisable()
{
    Advertising.RewardedAdCompleted -= RewardedAdCompletedHandler;
    Advertising.RewardedAdSkipped -= RewardedAdSkippedHandler;
}

// Event handler called when a rewarded ad has completed
void RewardedAdCompletedHandler(RewardedAdNetwork network, AdPlacement placement)
{
    Debug.Log("Rewarded ad has completed. The user should be rewarded now.");
}

// Event handler called when a rewarded ad has been skipped
void RewardedAdSkippedHandler(RewardedAdNetwork network, AdPlacement placement)
{
    Debug.Log("Rewarded ad was skipped. The user should NOT be rewarded.");
}

Working with Rewarded Interstitial Ads

The method to show a rewarded interstitial ad requires it to be already loaded. Therefore you should check for the ad's availability before showing it.

// Check if rewarded ad is ready
bool isReady = Advertising.IsRewardedInterstitialAdReady();

// Show it if it's ready
if (isReady)
{
    Advertising.ShowRewardedInterstitialAd();
}

A RewardedInterstitialAdCompleted event will be fired whenever a rewarded interstitial ad has completed. You should listen to this event to reward the user for watching the ad. Otherwise, a RewardedInterstitialAdSkipped event will be fired if the ad is skipped before finishing (and the user therefore is not entitled to the reward).

// Subscribe to interstitial rewarded ad events
void OnEnable()
{
    Advertising.RewardedInterstitialAdCompleted += RewardedInterstitialAdCompletedHandler;
    Advertising.RewardedInterstitialAdSkipped += RewardedInterstitialAdSkippedHandler;
}

// Unsubscribe events
void OnDisable()
{
    Advertising.RewardedInterstitialAdCompleted -= RewardedInterstitialAdCompletedHandler;
    Advertising.RewardedInterstitialAdSkipped -= RewardedInterstitialAdSkippedHandler;
}

// Event handler called when an interstitial rewarded ad has completed
void RewardedInterstitialAdCompletedHandler(RewardedInterstitialAdNetwork network, AdPlacement placement)
{
    Debug.Log("Rewarded interstitial ad has completed. The user should be rewarded now.");
}

// Event handler called when an interstitial rewarded ad has been skipped
void RewardedInterstitialAdSkippedHandler(RewardedInterstitialAdNetwork network, AdPlacement placement)
{
    Debug.Log("Rewarded interstitial ad was skipped. The user should NOT be rewarded.");
}

Removing Ads

Removing Ads without Updating Consent

In some cases you need to remove/stop showing ads in your game, e.g. when the user purchases the "Remove Ads" product. To remove ads:

// Remove ads permanently
Advertising.RemoveAds();

The RemoveAds method will destroy the banner ad if one is being shown, and prevent future ads from being loaded and shown except rewarded ads, since they are unobtrusive and only shown at the user discretion.

Note that the RemoveAds method uses Unity's PlayerPrefs to store the ad removal status with no encryption/scrambling.

An AdsRemoved event will be fired after ads have been removed. You can listen to this event and take appropriate actions, e.g update the UI.

// Subscribe to the event
void OnEnable()
{
    Advertising.AdsRemoved += AdsRemovedHandler;
}

// The event handler
void AdsRemovedHandler()
{
    Debug.Log("Ads were removed.");

    // Unsubscribe
    Advertising.AdsRemoved -= AdsRemovedHandler;
}

You can also check at any time if ads were removed or not.

// Determine if ads were removed
bool isRemoved = Advertising.IsAdRemoved();

Removing Ads and Revoke Consents

Because rewarded ads are still available after removing ads (for good reason!), it may be desirable in some cases to also revoke all consent granted to the Advertising module as well as the individual network. For example, you may offer "Remove Ads" as an in-app purchase that the user can buy to remove intrusive ads (i.e. banner and interstitial ads) and stop the app from collecting their personal data for advertising purpose. In such case, you can call the RemoveAds and pass true to its revokeConsents parameter. This parameter is optional and default to false.

// Remove ads permanently and also revoke the consent
// of the Advertising module and all ad networks so that
// they stop collecting user data.
Advertising.RemoveAds(true);    // revokeConsents passed as true

Re-enabling Ads after Removal

Finally, you can also revoke the ad removing status and allow ads to be shown again.

// Revoke ad removing status and allow showing ads again
Advertising.ResetRemoveAds();

Manual Ad Loading

With the Automatic Ad Loading feature, you normally don't need to worry about loading ads. However, if you want to disable this feature and control the loading process yourself, you can do so with manual ad loading in script.

It is advisable to load an ad as far in advance of showing it as possible to allow ample time for the ad to be loaded.

To load an interstitial ad:

// Load the default interstitial ad.
Advertising.LoadInterstitialAd();

To load a rewarded ad:

// Load the default rewarded ad.
Advertising.LoadRewardedAd();

Working with Non-Default Ads

Beside the default ads, you can also show ads from non-default networks at non-default placements, thus implementing a more sophisticated ad strategy in your app. Note that each method to load or show ad always has a variant that allows you to specify the target ad network and placement explicitly. For example there're 2 variants of the LoadInterstitialAd method. One takes no argument and loads the default interstitial ad. The other loads an interstitial ad from a specified network at an arbitrary placement.

If you're using the "Load All Defined Placements" auto ad-loading mode, both default and non-default ads are loaded automatically so you never need to worry about loading ads.

If you have AdMob as the default interstitial ad network, you can load and show a non-default interstitial ad like below.

// This method shows an interstitial ad from the default network (i.e. AdMob in this example)
// at the default placement. Default ads are loaded automatically unless Automatic Ad Loading is disabled.
if (Advertising.IsInterstitialAdReady())
    Advertising.ShowInterstitialAd();


// If you're using the "Load All Defined Placements" auto ad-loading mode, non-default ads are loaded automatically too.
// Here we show how you can manually load a non-default interstitial ad, for illustration purpose.
// In practice, you don't need to do this unless the auto ad-loading is disabled or set to "Load Default Ads" mode.
// In this example, we'll load and show an interstitial ad from AdMob at the custom placement Startup.
// (Note that an interstitial ad at the default placement but belongs to a non-default network 
// would also be considered a non-default ad).
// You can, for example, associate this placement with a house ad unit to show cross-promotion ads
// for other apps in your portfolio, thus having a free cross-promotion system!
Advertising.LoadInterstitialAd(InterstitialAdNetwork.AdMob, AdPlacement.Startup);


// Checks if the AdMob interstitial ad at placement Startup is ready and shows it.
if (Advertising.IsInterstitialAdReady(InterstitialAdNetwork.AdMob, AdPlacement.Startup))
    Advertising.ShowInterstitialAd(InterstitialAdNetwork.AdMob, AdPlacement.Startup);


// Likewise, you can check if a non-default rewarded ad is ready and show it like below
// (assume that IronSource is not set as the default network for rewarded ads).
if (Advertising.IsRewardedAdReady(RewardedAdNetwork.IronSource, AdPlacement.HomeScreen))
    Advertising.ShowRewardedAd(RewardedAdNetwork.IronSource, AdPlacement.HomeScreen);

Ad Network Clients

You can access the underlaying clients for the supported ad networks using the corresponding properties of the Advertising class.

// AdColony client.
AdColonyClientImpl adcolonyClient = Advertising.AdColonyClient;

// AdMob client.
AdMobClientImpl admobClient = Advertising.AdMobClient;

// Chartboost client.
ChartboostClientImpl chartboostClient = Advertising.ChartboostClient;

// Facebook Audience Network client.
AudienceNetworkClientImpl fbanClient = Advertising.AudienceNetworkClient;

// Heyzap client.
HeyzapClientImpl heyzapClient = Advertising.HeyzapClient;

// ironSource client.
IronSourceClientImpl ironSrcClient = Advertising.IronSourceClient;

// MoPub client.
MoPubClientImpl mopubClient = Advertising.MoPubClient;

// Tapjoy client.
TapjoyClientImpl tapjoyClient = Advertising.TapjoyClient;

// Unity Ads client.
UnityAdsClientImpl unityAdsClient = Advertising.UnityAdsClient;

From these clients you can access network-specific events, e.g the OnBannerAdClosed event provided by the AdMob. Events like this are specific to a certain ad network and normally not available in other networks which is why they are not exposed in the Advertising class (the Advertising class only exposes a common subset of events that are provided by all ad networks to ensure a consistent behavior across all networks). Note that these network-specific events are only available if the corresponding plugin of that network has been imported to your project. You can use the scripting symbols in the below table to wrap codes that access these event to make sure they only get compiled when the plugin is available. These symbols are defined automatically by Easy Mobile when the corresponding ad plugin is imported, except UNITY_ADS which is defined by Unity when the service is enabled.