Event Tracking

GameAnalytics features the following event types:

Event	Description
Ad	Ads shown and clicked, fill rate.
Business	In-App Purchases supporting receipt validation on GA servers.
Design	Submit custom event id’s. Useful for tracking metrics specifically needed for your game.
Error	Submit exception stack traces or custom error messages.
Health	Automatically submits health metrics related to your game such as FPS.
Impression	Impression data from different ad networks
Progression	Level attempts with Start, Fail & Complete event.
Resource	Managing the flow of virtual currencies - like gems or lives

tip

Business Events

Business events are used to track real-money transactions.

Field	Type	Description	Example
currency	string	Currency code in ISO 4217 format.	USD
amount	integer	Amount in cents.	99 is 0.99$
itemType	string	The type / category of the item.	GoldPacks
itemId	string	Specific item bought.	1000GoldPack
cartType	string	The game location of the purchase. Max 10 unique values are allowed.	EndOfLevel

When a purchase is completed, there are 2 ways to track the event:

Traditional
Command Queue

<!-- Traditional way -->
gameanalytics.GameAnalytics.addBusinessEvent("[currency]", [amount], "[itemType]", "[itemId]", "[cartType]");

<!-- Command queue -->
GameAnalytics("addBusinessEvent", "[currency]", [amount], "[itemType]", "[itemId]", "[cartType]");

Custom Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addBusinessEvent(
  "[currency]",
  [amount],
  "[itemType]",
  "[itemId]",
  "[cartType]",
  fields
);

tip

For more information about custom event and fields raw export go here.

Ad Events

The GameAnalytics ad event needs to be called when certain events happen for the implemented ad sdk’s.

An ad sdk has callback methods activating code when certain things are activated (like ad show or ad clicked). To use the ad event it is need to call the GameAnalytics SDK when these delegates are called.

The examples below describe how to implement this for the following ad-types:

rewarded video
interstitial
bannner

All code examples use the AdMob SDK to showcase example usage. Other ad networks might differ in naming/structure, but the overall process should be applicable to all.

The ad SDK name argument for the ad event needs to be all lower-case with no spaces or underscore used. Here some examples of valid values to use for ad SDK names:

admob
unityads
ironsource
applovin

Rewarded Videos

Showing a rewarded video

To track if a rewarded video ad had been succesfully shown or has failed to show for some reason you have to call the following events:

if (rewardedVideo.Show()) {
  gameanalytics.GameAnalytics.addAdEvent(
    EGAAdAction.Show,
    EGAAdType.RewardedVideo,
    "AdMob",
    "[ad placement id]"
  );
} // the ad couldn't be shown
else {
  gameanalytics.GameAnalytics.addAdEvent(
    EGAAdAction.FailedShow,
    EGAAdType.RewardedVideo,
    "AdMob",
    "[ad placement id]"
  );
}

Tracking Rewards

To track if an user has received a reward from the ad send the following event:

gameanalytics.GameAnalytics.addAdEvent(
  gameanalytics.EGAAdAction.RewardReceived,
  gameanalytics.EGAAdType.RewardedVideo,
  "AdMob",
  "[ad placement id]"
);

Interstitial Ads

Showing an interstitial ad

To track if an interstitial ad had been succesfully shown or has failed to show for some reason you have to call the following events:

if (interstitial.Show()) {
  gameanalytics.GameAnalytics.addAdEvent(
    gameanalytics.EGAAdAction.Show,
    gameanalytics.EGAAdType.Interstitial,
    "AdMob",
    "[ad placement id]"
  );
} // the ad couldn't be shown
else {
  gameanalytics.GameAnalytics.addAdEvent(
    gameanalytics.EGAAdAction.FailedShow,
    gameanalytics.EGAAdType.Interstitial,
    "AdMob",
    "[ad placement id]"
  );
}

Tracking user clicks

To track if an user has clicked an interstitial ad (and consequently left the app to visit the advertiser's site) you can use the next event:

// send ad event
gameanalytics.GameAnalytics.addAdEvent(
  GAAdAction.Clicked,
  GAAdType.Interstitial,
  "AdMob",
  "[AD_PLACEMENT_OR_UNIT_ID]"
);

If the ad loads successfully send the following ad event when onAdLoaded() listener method is called:

gameanalytics.GameAnalytics.addAdEvent(
  GAAdAction.Show,
  GAAdType.Banner,
  "admob",
  "[AD_PLACEMENT_OR_UNIT_ID]"
);

If the ad fails to load we can call the following event:

gameanalytics.GameAnalytics.addAdEvent(
  GAAdAction.FailedShow,
  GAAdType.Banner,
  "admob",
  "[AD_PLACEMENT_OR_UNIT_ID]"
);

To track if an user has clicked and ad (and subsequently has left the app to visit the advertiser's site or store page) we can call a GAAdAction.Clicked event. For example, for admob the banner ad click is registered on the onAdOpened() listener method.

gameanalytics.GameAnalytics.addAdEvent(
  GAAdAction.Clicked,
  GAAdType.Banner,
  "admob",
  "[AD_PLACEMENT_OR_UNIT_ID]"
);

Custom Ad Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addAdEvent(
  GAAdAction.Clicked,
  GAAdType.Banner,
  "admob",
  "[AD_PLACEMENT_OR_UNIT_ID]",
  fields
);

tip

For more information on custom event fields and raw data export go here.

Field	Type	Description	Example
adAction	enum	A defined enum for ad action (for example clicked).	GAAdAction.Clicked GAAdAction.Show GAAdAction.FailedShow GAAdAction.RewardReceived
adType	enum	A defined enum for ad type (for example interstitial).	GAAdType.Video GAAdType.RewardedVideo GAAdType.Playable GAAdType.Interstitial GAAdType.OfferWall GAAdType.Banner
adSdkName	string	Name of the Ad/Ad mediation SDK.	admob
adPlacement	string	Identifier of ad in the game or the placement of it.	level_complete_ad
adPlacement	string	Identifier of ad in the game or the placement of it.	level_complete_ad
duration	int	Optional. Only used for video ads to track how long the user watched the video for.	10
noAdReason	enum	Optional. Used to track the reason for not being able to show an ad when needed (for example no fill).	GAAdError.Unknown GAAdError.Offline GAAdError.NoFill GAAdError.InternalError GAAdError.InvalidRequest GAAdError.UnableToPrecache

tip

For more information on Ad Events go here.

Resource Events

Resource events are used to register the flow of your in-game economy (virtual currencies) – the sink (subtract) and the source (add) for each virtual currency.

Before calling the resource event it is needed to specify what discrete values can be used for currencies and item types in the Configuration phase.

source (add)

Add hard currency from an in-app purchase.

Traditional
Command Queue

gameanalytics.GameAnalytics.addResourceEvent(
  gameanalytics.EGAResourceFlowType.Source,
  "Gems",
  400,
  "IAP",
  "Coins400"
);

GameAnalytics("addResourceEvent", "Source", "Gems", 400, "IAP", "Coins400");

sink (subtract)

Subtract hard currency to buy an item.

Traditional
Command Queue

gameanalytics.GameAnalytics.addResourceEvent(
  gameanalytics.EGAResourceFlowType.Sink,
  "Gems",
  400,
  "IAP",
  "Coins400"
);

GameAnalytics("addResourceEvent", "Sink", "Gems", 400, "IAP", "Coins400");

Subtract a gem currency to source (buy) some amount of another virtual currency (BeamBooster):

Traditional
Command Queue

gameanalytics.GameAnalytics.addResourceEvent(
  ga.EGAResourceFlowType.Sink,
  "Gems",
  100,
  "Boosters",
  "BeamBooster5Pack"
);

gameanalytics.GameAnalytics.addResourceEvent(
  gameanalytics.EGAResourceFlowType.Source,
  "BeamBooster",
  5,
  "Gems",
  "BeamBooster5Pack"
);

GameAnalytics(
  "addResourceEvent",
  "Sink",
  "Gems",
  100,
  "Boosters",
  "BeamBooster5Pack"
);

GameAnalytics(
  "addResourceEvent",
  "Source",
  "BeamBooster",
  5,
  "Gems",
  "BeamBooster5Pack"
);

Subtract 3 BeamBooster currency that were used during a level:

Traditional
Command Queue

gameanalytics.GameAnalytics.addResourceEvent(
  gameanalytics.EGAResourceFlowType.Sink,
  "BeamBooster",
  3,
  "Gameplay",
  "BeamBooster5Pack"
);

GameAnalytics(
  "addResourceEvent",
  "Sink",
  "BeamBooster",
  3,
  "Gameplay",
  "BeamBooster5Pack"
);

Custom Resource Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addResourceEvent(
  ga.EGAResourceFlowType.Source,
  "BeamBooster",
  5,
  "Gems",
  "BeamBooster5Pack",
  fields
);

tip

For more information on custom event fields and raw data export go here.

Field	Type	Description	Example
flowType	enum	A defined enum for sourcing and sinking resources.	`EGAResourceFlowType.Sink` `EGAResourceFlowType.Source`
currency	string	The resource type/currency to track. Has to be one of the configured available resource currencies. This string can only contain [A-Za-z] characters.	Gems BeamBoosters Coins
amount	float	Amount sourced or sinked. 0 or negative numbers are not allowed.	100.0
itemType	string	For sink events it can describe an item category you are buying (Weapons) or a place (Gameplay) the currency was consumed. For source events it can describe how the currency was gained. For example “IAP” (for in-app purchase) or from using another currency (Gems). Has to be one of the configured available itemTypes.	Weapons IAP Gameplay Boosters
itemId	string	For sink events it can describe the specific item (SwordOfFire) gained. If consumed during Gameplay you can simply use “Consumed”. For source events it describes how the player got the added currency. This could be buying a pack (BoosterPack5) or earned through Gameplay when completing a level (LevelEnd).	BoosterPack5 SwordOfFire LevelEnd Coins400

caution

Be careful to not call the resource event too often! In a game where the user collect coins fairly fast you should not call a Source event on each pickup. Instead you should count the coins and send a single Source event when the user either complete or fail the level.

tip

For more information on Resource Events go here.

Progression Events

To add a progression event call the following function:

Traditional
Command Queue

gameanalytics.GameAnalytics.addProgressionEvent(
  gameanalytics.EGAProgressionStatus.Start,
  "world01",
  "stage01",
  "level01"
);

GameAnalytics("addProgressionEvent", "Start", "world01", "stage01", "level01");

Custom Progression Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addProgressionEvent(
  gameanalytics.EGAProgressionStatus.Start,
  "world01",
  "stage01",
  "level01",
  fields
);

tip

For more information on custom event fields and raw data export go here.

Field	Type	Description	Example
progressionStatus	enum	Status of added progression	gameanalytics.EGAProgressionStatus.Start gameanalytics.EGAProgressionStatus.Fail gameanalytics.EGAProgressionStatus.Complete
progression01	string	Required progression location.	World01
progression02	string	Not required. Use if needed.	Stage01
progression03	string	Not required. Use if needed.	Level01
score	integer	An optional score when a user completes or fails a progression attempt. Remember to set progression02 and/or progression03 if they are not used when using score parameter.	1023

It is not required to use all 3 if your game does not have them, you can have any of the following combinations:

progression01
progression01 and progression02
progression01 and progression02 and progression03

caution

At least progression01 must be set for such events (an empty value is not allowed).

info

Progressions need to be set in order (e.g: you cannot have only progression01 and progression03, nor progression02 and progression03, you are required to start from 01 and continue)

tip

If you do not need progression02 or progression03 do not make any references to these parameters when calling the method.

tip

For more information on Progression Events go here.

Error Events

To add a custom error event call the following function:

Traditional
Command Queue

gameanalytics.GameAnalytics.addErrorEvent(
  gameanalytics.EGAErrorSeverity.Debug,
  "Something went bad in some of the smelly code!"
);

GameAnalytics(
  "addErrorEvent",
  "Debug",
  "Something went bad in some of the smelly code!"
);

Custom Error Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addErrorEvent(
  gameanalytics.EGAErrorSeverity.Debug,
  "Something went bad in some of the smelly code!",
  fields
);

tip

For more information on custom event fields and raw data export go here.

Field	Type	Description	Example
severity	enum	Severity of error	`gameanalytics.EGAErrorSeverity.Debug` `gameanalytics.EGAErrorSeverity.Info` `gameanalytics.EGAErrorSeverity.Warning` `gameanalytics.EGAErrorSeverity.Error` `gameanalytics.EGAErrorSeverity.Critical`
message	string	Error message (can be null)	`“Error when entering level12”`

tip

For more information on Error Events go here.

Design Events

Please note that custom dimensions and progression filters will not be added on design and error events. Therefore you cannot (at the moment) filter by these when viewing design or error metrics.

To add a design event call the following method:

Traditional
Command Queue

<!-- Traditional way -->
gameanalytics.GameAnalytics.addDesignEvent(string eventName, float eventValue);

<!-- Command queue -->
GameAnalytics("addDesignEvent", string eventName, float eventValue);

Example:

Traditional
Traditional

<!-- Traditional way -->
gameanalytics.GameAnalytics.addDesignEvent("BossFights:FireLord:KillTimeUsed", 234);

<!-- Command queue -->
GameAnalytics("addDesignEvent", "BossFights:FireLord:KillTimeUsed", 234);

Custom Design Event Fields

It is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. Here is an example of how to use it:

var fields = {
  test: 100,
  test_2: "hello_world",
};

gameanalytics.GameAnalytics.addDesignEvent(
  "BossFights:FireLord:KillTimeUsed",
  234,
  fields
);

tip

For more information on custom event fields and raw data export go here.

Field	Type	Description	Example
eventId	string	The eventId is a hierarchy string that can consist of 1-5 segments separated by ‘:’. Each segment can have a max length of 32.	“StartGame:ClassLevel1_5”, “StartGame:ClassLevel6_10”
value	float	A float event tied to the eventId. Will result in sum & mean values being available.	34.5

tip

For more information on Design Events go here.

Event Tracking

Business Events

Custom Event Fields

Ad Events

Rewarded Videos

Showing a rewarded video

Tracking Rewards

Interstitial Ads

Showing an interstitial ad

Tracking user clicks

Banner Ads

Tracking Banner Clicks

Custom Ad Event Fields

Resource Events

source (add)

sink (subtract)

Custom Resource Event Fields

Progression Events

Custom Progression Event Fields

Error Events

Custom Error Event Fields

Design Events

Custom Design Event Fields

Event Tracking

Business Events​

Custom Event Fields​

Ad Events​

Rewarded Videos​

Showing a rewarded video​

Tracking Rewards​

Interstitial Ads​

Showing an interstitial ad​

Tracking user clicks​

Banner Ads​

Tracking Banner Clicks​

Custom Ad Event Fields​

Resource Events​

source (add)​

sink (subtract)​

Custom Resource Event Fields​

Progression Events​

Custom Progression Event Fields​

Error Events​

Custom Error Event Fields​

Design Events​

Custom Design Event Fields​

Business Events

Custom Event Fields

Ad Events

Rewarded Videos

Showing a rewarded video

Tracking Rewards

Interstitial Ads

Showing an interstitial ad

Tracking user clicks

Banner Ads

Tracking Banner Clicks

Custom Ad Event Fields

Resource Events

source (add)

sink (subtract)

Custom Resource Event Fields

Progression Events

Custom Progression Event Fields

Error Events

Custom Error Event Fields

Design Events

Custom Design Event Fields