Docs > Introduction > Data and Events

Data and Events

GameAnalytics has 5 event types available for tracking different concepts in your game.

The documentation below gives examples of how you might use each event, the limitations with each and our data retention policies. Specific code examples are included in the SDK documentation.


Business Events

Copy link to clipboard

Use this event to track real money transactions in your game.

With the business event, you can include information on the specific type of in-app item purchased, and where in the game the purchase was made.

Example A: A player goes into the game’s shop and makes a purchase of a pack of coins.

Example B: You show the player a screen at the end of a level to prompt them to buy lives. They choose to purchase a pack of 3 lives that costs $0.99.

Field Example A Example B
cartType shop endOfLevel
itemType coinPack lives
itemId coinPack2 lifePack3
amount 99 99
currency USD USD

Note: We allow up to 10 cartTypes and up to 100 unique itemTypes and itemIds each.


Purchase Validation

Copy link to clipboard

The GameAnalytics SDK can automatically capture the purchase receipt from the app store. This is used to validate the purchases and ensure that your monetization data is correct. See the SDK documentation for more information on how to include the receipt with the Business event.

Purchase validation is supported only on iOS and Android at the very moment and it is a must-have for games using our latest SDKs (v2) in order to view data in the default monetization dashboards. Once the implementation is up and running, all monetization metrics will be split by valid metrics, non-valid metrics and the general metrics. The valid ones are the result of processing only the business events marked as valid while the non-valid are the those created by processing invalid business events. The general are the sum of the two. For further information check out this article.


Resource Events

Copy link to clipboard

Use this event to track when players gain (source) or lose (sink) resources like virtual currency and lives.

A “sink” is when a player loses or spends a resource. A “source” is when a player gains or earns a resource.

  • Example A: A player spends one life by starting a game.
  • Example B: A player buys a boost in the game with 100 gold currency.
  • Example C: A player earns a reward of 5 lives for watching an ad.
  • Example D: A player buys a pack of 100 gold currency as an in-app purchase for $0.99 from the store. (The event below is only for the addition of gold to the player’s balance.)
Field Example A Example B Example C Example D
flowType sink sink source source
itemType continuity boost reward purchase
itemId startGame rainbowBoost videoAd goldPack
amount 1 100 5 100
resourceCurrency life gold life gold

Note: You will need to pre-define a list of currencies and itemTypes when you instrument your game. The max amounts of unique resourceCurrency, itemTypes and unique itemIds are 100 each.

Optimizing the sending of resource events

It is best to send Resource events after gameplay is completed by a player, as opposed to every time the player’s balance goes up/down within a game. For example, if your player gains coins for making matches in a game, but loses them every time he hits an obstacle, wait until the end of the game to sum up how many coins they earned and lost, and then send that as one event.


Progression Events

Copy link to clipboard

Use this event to track when players start and finish levels in your game. This event follows a 3 hierarchy structure (for example World, Level and Phase) to indicate a player’s path or place in the game.

This type of events can be used for calculating metrics such as how many levels were started on a day and not only.

“Progress” could mean things like leveling up, completing quests, completing missions, or completing milestones. You can ONLY track one type of progression with this event. For example, if you have levels and quests in your game, the progression event should only be used for either tracking levels or quests, but not both. Use Design Event and/or Custom Dimensions to track a secondary progression concept, if need be.

  • Example A: A players starts Day 1 of the Wild West world in Plants vs. Zombies 2.
  • Example B: A player completes the “Enter a Competition” quest in My Horse by entering the Europe competition.
Field Example A Example B
progressionStatus start complete
progression01 level quest
progression02 wildWest enterCompetition
progression03 day1 europeCompetition
value (blank) (blank)

For these events, you can send:

All three levels of the hierarchy structure (progression01, progression02 and progression03) OR you can send just progression01 and progression02 OR you can send just progression 01.


Error Events

Copy link to clipboard

You can use the Error event to log errors or warnings generated by your players’ in-game behaviour.

Example A: A player has scored over 1 billion points on a level, which is not supposed to happen in your game.

Field Example A
severity Warning
message crazyHighScore

The options for severity are pre-defined in our SDK as:

  • Info
  • Debug
  • Warning
  • Error
  • Critical

Some users choose to include a stack trace in the message field.


Design Events

Copy link to clipboard

Track any other concept in your game using this event type. For example, you could use this event to track GUI elements or tutorial steps.

  • Example A: A player completes the first step in your new user tutorial by naming their character.
  • Example B: A player clicks on the button to turn on the volume in your game.
Field Example A Example B
eventId newUserTutorial:namedCharacter:complete guiClick:volume:on
value (blank) (blank)

For more information how to use the Design event, see here.


Data Retention Policy

Copy link to clipboard
  • We have a backend Data Retention Policy of 12 months.
  • We provide the ability to query Historical Data for the last 12 months. This applies across all features of GameAnalytics, except for Segments and Data Export
  • For Data Export, we provide the ability to export data for the last 6 months.
  • For Segments, we provide the ability to run a segment over the past 1 month of data. What this means is that after creating a segment, it always can be applied to the past month’s worth of data.
  • For Dashboards, Explore Tool and Cohorts you can query historically up to July 1st 2018.  It was from this month onwards when our new backend went live with all GameAnalytics users, events and metrics.

Event Limitations

Copy link to clipboard

These are the recommended unique value limitations.

Default annotations

Field Unique Limit
build 100
platform 30
device 500
os_version 255
progression 100 pr. event part
custom_01 50
custom_02 50
custom_03 50

Business Event

Field Unique Limit
event_id (itemType) 100
event_id (itemId) 100
cart_type 10

Resource Event

Field Unique Limit
event_id (virtualCurrency) 20
event_id (itemType) 20
event_id (itemId) 20

Design Event

Field Unique Limit
event_id (entire string) 50000*

* This is a very large threshold. The amount of tree-nodes generated will also affect if the game will be throttled. Having this many is not recommended and it can affect the GameAnalytics tool experience (downloading that much information to the browser).

Contact support

Any queries about the platform are welcome.

Give article feedback

Let us know what you think about the articles.