Implementing Event Tracking
The purpose of this article is to expose more examples of custom events in GameAnalytics and how they should be sent, from the planning phase up to aggregation and visualization part in the tool.
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.
Design EventsCopy link to clipboard
- To better understand the space of possibilities with Design Events, we visualize a game that rewards the players with achievements for reaching various milestones such as killing a certain number of NPCs or for exploring the map.
- We also propose to track how much time it took the players to accomplish the achievements under the “Killing” category.
- We propose the following example of a hierarchy for tracking such achievements:
- Each level in the hierarchy will form a part in the name of the event.
- In order for our back-end to detect hierarchies, the event parts need to be separated by colons “:”.
- The composition of the first event in the scheme will be “Achievements:Killing:Neutral:10_Kills”.
- The “timePlayed” value is attached to the event separately as we can see the value “123” in the next code example.
GameAnalytics.NewDesignEvent ("Achievement:Killing:Neutral:10_Kills", 123);
- 123 represents the “timePlayed” value. The entire hierarchy can be generated dynamically.
Visualizing “Killing” and “Exploring” Achievements
- For creating meaningful metrics about achievements, each corresponding event needs to be sent only once as the achievement can be unlocked only one time.
- GameAnalytics will count how many events have been aggregated (how many users unlocked the achievement) and the average “timePlayed” for each achievement under the “Killing” category.
Note: The tool also calculates the sum of the values but in this case the average time is more useful than total time.
- After the aggregation of the custom events (which can take up to 24 hours), metrics for each branch in the hierarchy are generated and they can be visualized using the explore tool.
- The events are grouped by “Count” in the image below to highlight how many users accomplished each achievement (each user sends an achievement event type only once in his lifetime). Many visualization combinations can be done using the “Explore” visualization tool available in GameAnalytics. Read more about this feature in the Explore article.
- In the same manner, the “Exploring” achievements can be visualized.
- If the “Mean” or “Sum” grouping option is selected for the “Exploring” achievements, the tool will return a “No data found” message since no value has been attached to the corresponding design events.
- Hierarchies can have up to 5 levels.
- As a result only 5 event parts should be described in the string attached to the “NewDesignEvent” method of the SDK you are using.
- Next we propose a much simpler hierarchy that covers the tracking of how many users have discovered a specific secret location where a secret weapon can be equipped.
- Similar to achievements, each unique design event needs to be triggered only once per user in order to track the number of users, not the amount of times the discovery of the secret weapons happened.
- Example of sending an event from this hierarchy via code:
- The generated metrics can be visualized in the same manner as the examples above.
- Design Events can be included as steps inside funnels to track how many users have executed a particular sequence of actions across all sessions in a specified date range.
- For instance, a tutorial inside a game can be monitor by creating the following hierarchy of events corresponding to each step:
- The lessons are counted using the 01, 02,.. counting method to make sure they are displayed in-order when using the event picker. The events need to be aggregated and also included in our database to be able to create a funnel using them. This can take up to two days, since we perform all the aggregations across all our games simultaneously.
- We swiftly fired 1 event for each of the lessons in the scheme from 1 to 6 and after aggregation we created and processed the following funnel:
Read more about the funnel feature in our dedicated article for Funnels.
Progression EventsCopy link to clipboard
- Progression events are specialized design events for tracking the progress of players.
- They contain 3 event parts called progression01, progression02 and progression03.
- They come with 3 statuses for determining the stage of progress: start, complete and fail.
- We propose the following scheme to implement and see the results in the GameAnalytics dashboards.
- Let’s have a look at how a progression event can be sent via code with the Unity SDK:
GameAnalytics.NewProgressionEvent (GAProgressionStatus.Start, "World_01", "Stage_01", "Level_Progress"); // without score
GameAnalytics.NewProgressionEvent (GAProgressionStatus.Complete, "World_01", "Stage_01", "Level_Progress", 200); // with score
- Once the events are aggregated, the custom metrics automatically generated for each status of each progression can be compared under the same plot.
- For instance, in the next figure we can see a comparison between the aggregated “Start” and “Complete” progression events for the “Stage_01” actions enumerated in the proposed scheme.
- In this example all the players who completed the first stage also “completed” the fight with the boss. Note that it is not necessary for all start events to end up with Complete or Fail events. The player might not reach the point where the associated Complete or Fail event is created leading to differences in the amount of Start events against Complete and Fail in the dashboards.
Resource EventsCopy link to clipboard
Resource events are divided into two categories: sink and source.
- For better understanding of how they can be used we propose a scenario for a game in which the source for resources are actual in-app purchases or looting while the spending of resources can be done either in the shop or during combat.
- Virtual currencies can be anything. In our case we choose gold and silver for in-game transactions and also we mark “grenade” as a “currency” for exposing the space of possibility in this feature.
- Example of code for creating a source and a sink event with “Grenade” as currency:
GameAnalytics.NewResourceEvent (GAResourceFlowType.Source, "Grenade", 2, "Looting", "BossKilled");
GameAnalytics.NewResourceEvent (GAResourceFlowType.Sink, "Grenade", 1, "Combat", "GrenadeThrow");<span style="color: gray;font-size: 0.8em"><code></code></span><span style="color: gray;font-size: 0.8em"><code> </code></span>
- Note: you need to make sure all currencies and item types are declared in the initialising phase. Read more in the dedicated technical documentation associated to the SDK you are using.
- The tool will automatically generate dashboards for each detected currency to highlight the balance between the sink and the source mechanics in the game.
- In the next representation we can view the “Grenade” resource dashboard for a date range composed by only one day
- Each aggregated resource event can also be visualised directly using the explore tool in the same manner as design and progression events.
Business EventsCopy link to clipboard
- Monetization metrics are divided into 3 submetrics each.
- For instance, ARPDAU is calculated in 3 different ways due to in-app purchase validation:
- ARPDAU valid (metric based on only business events marked as valid after validation)
- ARPDAU invalid (metric based on only business events marked as invalid after validation)
- ARPDAU (the general metric based on all aggregated business events, valid+invalid)
- The metrics above can be opened by using the explore tool by any game in our network.
Note: By default, all games that are using the latest official SDKs will view only valid monetization metrics in the default dashboards while REST API integrations will view global monetization metrics.
In other words it is highly important to implement purchase validation if you are using the latest SDKs and purchase validation is available for the platform you are targeting in order to view data in the default monetization metrics.
- Example of sending a business event in iOS using the Unity SDK:
string receipt= "MIIT8AYJKoZIhvcNAQcC...2LJuwKuaCXT4Y="; // raw receipt from the purchase platform provider
GameAnalytics.NewBusinessEventIOS("USD",249,"Shop item","Minigun Purchase","Shop_01",receipt);
- Once the event is aggregated it will automatically participate in generating monetization metrics. No other efforts are needed.
- In the next figure we see an example of monetization dashboard populated with data from events marked as valid.
Error EventsCopy link to clipboard
Error events are contextual messages to track the performance of the game.
- They can be sent by calling the dedicated method, e.g.:
GameAnalytics.NewErrorEvent (GAErrorSeverity.Info, "Could not find available server.");
All error events are streamed in the real-time dashboard. They will also populate the widgets in the Quality dashboard once fully aggregated. For example, in the following image we can visualise the “Error events”” count and the “Users affected by error events” count widgets: