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
Business Events
Business events are used to track real-money transactions.
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 |
GameAnalytics.AddBusinessEvent("[currency]", [amount], "[itemType]", "[itemId]", "[cartType]");
Custom Business 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:
Dictionary<string, object> fields = new Dictionary<string, object>();
fields.Add("test", 100);
fields.Add("test_2", "hello_world");
GameAnalytics.AddBusinessEvent("USD", 1000, "item", "id", "cart", "[receipt]", "google_play", "[signature]", fields);
For more information on custom event fields and raw data export go here.
For more information on Business Events go here.
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.
Resource Events
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) Gem currency from an in-app purchase.
GameAnalytics.AddResourceEvent(EGAResourceFlowType.Source, "Gems", 400, "IAP", "Coins400");
sink (subtract) Gem currency to buy an item.
GameAnalytics.AddResourceEvent(EGAResourceFlowType.Sink, "Gems", 400, "Weapons", "SwordOfFire");
sink (subtract) Gem currency to source (buy) some amount of another virtual currency (BeamBooster).
GameAnalytics.AddResourceEvent(EGAResourceFlowType.Sink, "Gems", 100, "Boosters", "BeamBooster5Pack");
GameAnalytics.AddResourceEvent(EGAResourceFlowType.Source, "BeamBooster", 5, "Gems", "BeamBooster5Pack");
sink (subtract) 3 BeamBooster currency that were used during a level.
GameAnalytics.AddResourceEvent(EGAResourceFlowType.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:
Dictionary<string, object> fields = new Dictionary<string, object>();
fields.Add("test", 100);
fields.Add("test_2", "hello_world");
GameAnalytics.AddResourceEvent(EGAResourceFlowType.Sink, "BeamBooster", 3, "Gameplay", "BeamBooster5Pack", fields);
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.SinkEGAResourceFlowType.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 |
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 follows 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.
Add a progression start event.
GameAnalytics.AddProgressionEvent(EGAProgressionStatus.Start, "world01", "stage01", "level01");
Add a progression complete event.
GameAnalytics.AddProgressionEventWithScore(EGAProgressionStatus.Complete, "world01", "stage01", "level01", 1000);
It is not required to use all 3 if your game does not have them.
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)
If you do not need progression02 or progression03 do not make any references to these parameters when calling the method.
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:
Dictionary<string, object> fields = new Dictionary<string, object>();
fields.Add("test", 100);
fields.Add("test_2", "hello_world");
GameAnalytics.AddProgressionEventWithScore(EGAProgressionStatus.Complete, "world01", "stage01", "level01", 1000, fields);
For more information on custom event fields and raw data export go here.
| Field | Type | Description | Example |
|---|---|---|---|
| progressionStatus | enum | Status of added progression | EGAProgressionStatus.Start EGAProgressionStatus.Fail EGAProgressionStatus.Complete |
| progression01 | string | Required progression location. | World01 |
| progression02 | string | Not required. Use if needed or else set to empty string. | Stage01 |
| progression03 | string | Not required. Use if needed or else set to empty string. | Level01 |
| score | integer | An optional score when a user completes or fails a progression attempt. | 1023 |
For more information on Progression Events go here.
Error Events
Used to track custom error events in the game. You can group the events by severity level and attach a message.
To add a custom error event call the following function:
GameAnalytics.AddErrorEvent(EGAErrorSeverity.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:
Dictionary<string, object> fields = new Dictionary<string, object>();
fields.Add("test", 100);
fields.Add("test_2", "hello_world");
GameAnalytics.AddErrorEvent(EGAErrorSeverity.Debug, "Something went bad in some of the smelly code!", fields);
For more information on custom event fields and raw data export go here.
| Field | Type | Description | Example |
|---|---|---|---|
| severity | enum | Severity of error | EGAErrorSeverity.Debug EGAErrorSeverity.Info EGAErrorSeverity.Warning EGAErrorSeverity.Error EGAErrorSeverity.Critical |
| message | string | Error message (can be null) | “Error when entering level12” |
For more information on Error Events go here.
Design Events
Every game is special. Therefore some needed events might not be covered by our other event types. The design event is available for you to add your own event-id hierarchy.
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.s
To add a design event call the following method.
GameAnalytics.AddDesignEvent("BossFights:FireLord:Kill");
It is also possible to add a float value to the event. This will (in addition to count) make the mean and sum aggregation available in the tool.
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:
Dictionary<string, object> fields = new Dictionary<string, object>();
fields.Add("test", 100);
fields.Add("test_2", "hello_world");
GameAnalytics.AddDesignEvent("BossFights:FireLord:KillTimeUsed", 234, fields);
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 |
It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.
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 = 1.5M 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.
For more information on Design Events go here.