Skip to main content

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:

FieldDescriptionTypePossible ValuesRequired
categoryEvent categorystringadsY
ad_sdk_nameName of the ad providerstringadmob, fyber, applovin, ironsource,
[any string] Lowercase with no spaces or underscores
Y
ad_placementPlacement/identifier of the ad within the gamestringend_of_game, after_level,
[any string] Max 64 characters
Y
ad_typeType of adstringvideo | rewarded_video | playable | interstitial | offer_wall | bannerY
ad_actionThe action made in relation to the adstringclicked | show | failed_show | reward_receivedY
ad_fail_show_reasonThe reason why the ad failed to showstringunknown |offline | no_fill | internal_error | invalid_request | unable_to_precacheN
ad_durationThe duration in milliseconds that the ad was shown forlong3500 (in milliseconds = 3.5 seconds)N
ad_firstThe field can be added if this is the first ad to be shown for the userbooleanTRUEN

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:

FieldExample AExample BExample C
categoryadsadsads
ad_sdk_nameadmobfyberironsource
ad_placementend_of_levelad_for_coinsduring_level
ad_typeinterstitialrewarded_videobanner
ad_actionshowclickedfailed_show
ad_fail_show_reasonno_fill
ad_duration50006000
ad_firsttrue-

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", "");
}

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", "");
}