Docs > Event Types, Metrics & Dimensions > Ad Events > Ad Events (Implementation)

Ad Events (Implementation)

The purpose of this article 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.

#

Overview

Copy link to clipboard

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

Copy link to clipboard

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

Copy link to clipboard

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

Contact support

Any queries about the platform are welcome.

Give article feedback

Let us know what you think about the articles.