Ad Events

Overview

Use this event to track when players interact with ads within your game and monitor your ad performance.

The ad event consists of 8 fields:

Field	Description	Type	Possible Values	Required
category	Event category	string	ads	Y
ad_sdk_name	Name of the ad provider	string	admob, fyber, applovin, ironsource, [any string] Lowercase with no spaces or underscores	Y
ad_placement	Placement/identifier of the ad within the game	string	end_of_game, after_level, [any string] Max 64 characters	Y
ad_type	Type of ad	string	video | rewarded_video | playable | interstitial | offer_wall | banner	Y
ad_action	The action made in relation to the ad	string	clicked | show | failed_show | reward_received	Y
ad_fail_show_reason	The reason why the ad failed to show	string	unknown |offline | no_fill | internal_error | invalid_request | unable_to_precache	N
ad_duration	The duration in milliseconds that the ad was shown for	long	3500 (in milliseconds = 3.5 seconds)	N
ad_first	The field can be added if this is the first ad to be shown for the user	boolean	TRUE	N

There are three ways in which AD's can be tracked:

Example A: A player is shown an interstitial ad Example B: A player clicks on a rewarded ad Example C: An ad is failed to be shown to a player

The below table shows examples of how different fields can be used to track these:

Field	Example A	Example B	Example C
category	ads	ads	ads
ad_sdk_name	admob	fyber	ironsource
ad_placement	end_of_level	ad_for_coins	during_level
ad_type	interstitial	rewarded_video	banner
ad_action	show	clicked	failed_show
ad_fail_show_reason	–	–	no_fill
ad_duration	5000	6000	–
ad_first	true	–	-

Implementation

The purpose of this section is to describe how ad events should be sent in GameAnalytics.

We illustrate the generation of these events with examples from our Unity SDK. The examples can be implemented in any other official GameAnalytics SDK by using the equivalent methods.

The ad event should be called when specific events happen related to the implemented ad SDKs.

Below we’ve shown code examples (Unity C#) of how to implement the event calls for rewarded, interstitial and banner ads. Within these examples we’ve referenced the AdMob SDK – other networks will differ in their naming and structure, but the same process still applies.

Rewarded Ads

When a Rewarded Video Ad fails to load

If the ad fails to load we can track the latest event when the OnAdFailedToLoad delegate is called:

public void HandleRewardedAdFailedToLoad(object sender, AdErrorEventArgs args) {

// keep track of the latest error (optional, only needed if you want to track errors for "FailedShow" ad event)
latestRewardedVideoError = args.Message;

}

When showing a Rewarded Video Ad

When you want to show an ad, it will either be available or unavailable. Call the ad event when the ad is unavailable. Do not call the ad event when the ad is shown, as one should call it later when the ad is closed.

if (this.rewardedAd.IsLoaded()) {
this.rewardedAd.Show();
}
else
{

// send ad event, for tracking a potential error
// the getLatestAdError method is describer later
GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.RewardedVideo, "admob", "<AD_PLACEMENT_OR_UNIT_ID>", getLatestAdError(this.latestRewardedVideoError));

// OR .. if you don't want to track errors
GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.RewardedVideo, "admob", "<AD_PLACEMENT_OR_UNIT_ID>");

}

Tracking errors

To track errors we recommend that you define the below method to map the error message stored earlier in the latestRewardedVideoError variable:

private GAAdError getLatestAdError(String error)
{
GAAdError result = GAAdError.Unknown;

    // ! Implement a switch statement to map ad network errors to known GAAdError types.
    // possible value:
    // GAAdError.Unknown
    // GAAdError.Offline
    // GAAdError.NoFill
    // GAAdError.InternalError
    // GAAdError.InvalidRequest
    // GAAdError.UnableToPrecached

    return result;

}

Track time spent watching a Rewarded Video Ad

To track the time spent by the player when watching a Rewarded Ad, you can start a timer and keep track of the current rewarded video ad when the “OnAdOpening” delegate is called.

The following example is a method for how you can handle this:

public void HandleRewardedAdOpening(object sender, EventArgs args){
// keep track of current rewarded video ad
currentRewardedVideoPlacement = "";
// start timer for this ad identifier
GameAnalytics.StartTimer(currentRewardedVideoPlacement);
}

// when application goes to background (during the display of a rewarded video ad) then the timer needs to stop.
// therefore we need to call code in Unity method OnApplicationPause.
void OnApplicationPause(bool paused) {
    if(paused){
        if(currentRewardedVideoPlacement != null){
            GameAnalytics.PauseTimer(currentRewardedVideoPlacement);
        }
    }
    else{
        if(currentRewardedVideoPlacement != null){
            GameAnalytics.ResumeTimer(currentRewardedVideoPlacement);
        }
    }
}

Tracking rewards from Rewarded Video Ads

To track rewards provided by watching Rewarded Ads, call an ad event in the delegate method where rewards are registered.

Within AdMob, this delegate is called “OnUserEarnedReward”, and the below example is a method for how you can handle this use case:

public void HandleUserEarnedReward(object sender, Reward args) {
// send ad event - reward recieved
GameAnalytics.NewAdEvent(GAAdAction.RewardReceived, GAAdType.RewardedVideo, "admob", "");
}

Tracking a successfully shown Rewarded Video Ad

To track a Rewarded Ad when it has finished being shown:

For AdMob this delegate is called “OnAdClosed” and the below example is a method for how you can handle this use case:

public void HandleRewardedAdClosed(object sender, EventArgs args) {
if(currentRewardedVideoPlacement != null)
{
long elapsedTime = GameAnalytics.StopTimer(currentRewardedVideoPlacement);
// send ad event for tracking elapsedTime
GameAnalytics.NewAdEvent(GAAdAction.Show, GAAdType.RewardedVideo, "admob", "", elapsedTime);
currentRewardedVideoPlacement = null;

        // OR if you do not wish to track time

        // send ad event without tracking elapsedTime
        GameAnalytics.NewAdEvent(GAAdAction.Show, GAAdType.RewardedVideo, "admob", "");
    }

}

Interstitial Ads

When a Static Interstitial Ad fails to load

If the Interstitial Ad fails to load, we can track the latest event when the “OnAdFailedToLoad” delegate is called.

The below example is a method for how you can handle this:

public void HandleInterstitialFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
// keep track of latest error (optional, only needed if you want to track errors for "FailedShow" ad event)
latestInterstitialError = args.Message;
}

When a Static Interstitial Ad is unavailable

When you want to show the Interstitial Ad, the ad will either be available or unavailable.

Call the below ad event, when the ad is unavailable.

if (this.interstitial.IsLoaded()) {
this.interstitial.Show();
}
else
{
// send ad event, for tracking a potential error
// the getLatestAdError method is describer earlier
GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.Interstitial, "admob", "", getLatestAdError(this.latestRewardedVideoError));

    // OR..  if you don't want to track errors
    GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.Interstitial, "admob", "");

}

Track when a Static Interstitial Ad is shown

For Static Interstitial Ads, we can track an event at the time the ad is shown.

Here is an example method for how you can handle this:

public void HandleInterstitialOpened(object sender, EventArgs args) {
// send ad event
GameAnalytics.NewAdEvent(GAAdAction.Show, GAAdType.Interstitial,"admob", "");
}

Track when an Interstitial Ad is clicked on (and the player leaves the game)

Send an ad event when the delegate “OnAdLeavingApplication” is called.

Here is an example method for how you can handle this:

public void HandleInterstitialLeftApplication(object sender, EventArgs args) {
// send ad event - ad click
GameAnalytics.NewAdEvent(GAAdAction.Clicked, GAAdType.Interstitial,"admob", "");
}

Banner Ads

When a Banner Ad fails to load

If the Banner Ad fails to load, we can track the latest event when the “OnAdFailed” delegate is called.

Here is an example method for how you can handle this:

public void HandleAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
// send ad events
GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.Banner, "admob", "", getLatestAdError(args.Message));
// OR .. if you don't want to track errors
GameAnalytics.NewAdEvent(GAAdAction.FailedShow, GAAdType.Banner, "admob", "");
}

When a user clicks on a Banner Ad

With AdMob, the Banner Ad click is registered on the “OnAdOpening” delegate callback. You can send an ad event at the same time.

Here is an example method for how you can handle this:

public void HandleAdOpened(object sender, EventArgs args) {
// send ad event
GameAnalytics.NewAdEvent(GAAdAction.Clicked, GAAdType.Banner, "admob", "");
}