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 |
Read more about events here
Event ids are strings separated by colons defining an event hierarchy – like “kill:robot:large”.
A bad implementation example.
[level_name]:[weapon_used]:[damage_done]
level_name could be 100 values, weapon_used could be 300 values and damage_done could be 1-5000 perhaps. This will generate an event hierarchy with: 100 * 300 * 5000 = 150M possible nodes.
This is far too many. Also the damage should be put as a value and not in the event string. The processing will perhaps be blocked for a game doing this and cause other problems when browsing our tool.
The maximum amount of unique nodes generated should be around 10k.
It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.
Read more about events here
You will get the most benefit of GameAnalytics when understanding what and how to track.
Business Events
Business events are used to track in-game transactions using real money.
| Field | Type | Description | Example |
|---|---|---|---|
| currency | string | Currency code in ISO 4217 format: More info here. | 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. | EndOfLevel |
| receipt | base64 string | The transaction receipt. Nil allowed. | nil |
You can send a business event by calling the following method:
gameanalytics::GameAnalytics.addBusinessEvent("[currency]", [amount], "[itemType]", "[itemId]", "[cartType]");
For more information on Business 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.
Here's how to send a source (add) event with the Gem currency from an in-app purchase:
gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::EGAResourceFlowType::Source, "Gems", 400, "IAP", "Coins400");
You can also send a sink event (subtract) to remove Gem currency in order to buy an item:
gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::EGAResourceFlowType::Sink, "Gems", 400, "Weapons", "SwordOfFire");
sink (subtract) Gem currency to source (buy) some amount of another virtual currency (BeamBooster).
gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::EGAResourceFlowType::Sink, "Gems", 100, "Boosters", "BeamBooster5Pack");
gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::EGAResourceFlowType::Source, "BeamBooster", 5, "Gems", "BeamBooster5Pack");
sink (subtract) 3 BeamBooster currency that were used during a level.
gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::EGAResourceFlowType::Sink, "BeamBooster", 3, "Gameplay", "BeamBooster5Pack");
| Field | Type | Required | Description |
|---|---|---|---|
| flowType | enum | yes | Add (source) or subtract (sink) resource. |
| currency | string | yes | One of the available currencies set in GA_Settings (Setup tab).This string can only contain [A-Za-z] characters. |
| amount | float | yes | Amount sourced or sunk. |
| itemType | string | yes | One of the available item types set in GA_Settings (Setup tab). |
| itemId | string | yes | Item id (string max length = 32) |
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.
For more information on Resource Events go here.
Progression Events
Progression events are used to track attempts at completing some part of a game (level, area). A defined area should follow a 3 tier hierarchy structure (could be world:stage:level) to indicate what part of the game the player is trying to complete.
When a player is starting a progression attempt a start event should be added.
When the player then finishes the attempt a fail or complete event should be added along with a score if needed.
The next sample adds a progression start event:
gameanalytics::GameAnalytics::addProgressionEvent(gameanalytics::EGAProgressionStatus::Start, "world01", "stage01", "level01");
| Field | Type | Required | Description |
|---|---|---|---|
| progressionStatus | enum | yes | Start, Complete or Fail |
| progression01 | string | yes | 1st progression (e.g. world01). |
| progression02 | string | no | 2nd progression (e.g. level01). |
| progression03 | string | no | 3rd progression (e.g. phase01). |
| score | int | no | Score of the attempt |
It is not required to use all 3 progression tiers if your game does not have them. Below you can find all the possible combinations you can use for progression events:
progression01progression01andprogression02progression01andprogression02andprogression03
At least progression01 must be set for such events (an empty value is not allowed).
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)
For more information on Progression Events go here.
Error Events
Used to track custom error events in the game. This event should be used when something goes wrong inside the game's logic (also note that unhandled exceptions & crashes will be automatically sent over as error events). It is possible to group the events by severity level and attach a message.
Error should be set to the severity of the error recorded. The following severity levels are accepted:
DebugInfoWarningErrorCritical
| Field | Type | Required | Description |
|---|---|---|---|
| severity | enum | yes | gameanalytics::EGAErrorSeverity::Debuggameanalytics::EGAErrorSeverity::Infogameanalytics::EGAErrorSeverity::Warninggameanalytics::EGAErrorSeverity::Errorgameanalytics::EGAErrorSeverity::Critical |
| message | string | no | Custom error message |
Here's an example on how you can send an error event:
gameanalytics::GameAnalytics::addErrorEvent(gameanalytics::EGAErrorSeverity::Error, "Something went bad!");
For more information on Error Events go here.
Design Event
Used to track any type of design event that you want to measure, f.x. GUI elements or tutorial steps. Custom dimensions are not supported for design events.
The event name is a String which can consist of 1 to 5 segments. Segments are seperated by ‘:’ and can have a max length of 64 characters. (e.g. "segment1:anotherSegment:gold").
To send a design event you have to use the following function:
gameanalytics::GameAnalytics::addDesignEvent("Kill:Sword:Robot");
It is also possible to attach a float value to the event. It is up to you to decide what you want this value to represent. This will (in addition to count) make the mean and sum aggregation available in the tool.
gameanalytics::GameAnalytics::addDesignEvent("BossFights:FireLord:KillTimeUsed", 234.f);
| Field | Type | Required | Description |
|---|---|---|---|
| eventId | string | yes | Event id |
| value | float | no | Optional custom value |
For more information on Design Events go here.