Design Events

Overview

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)

Fair Usage Policy

Event id’s are strings separated by colons defining an event hierarchy – like kill:robot:large.

It is important to not generate an excessive amount of unique nodes in the event hierarchy tree.

The maximum amount of unique nodes generated should not exceed 100,000 per day. With that in mind:

Poor Implementation Example

[level_name]:[weapon_used]:[damage_dealt]

Let's assume that:

level_name contains 100 values
weapon_used contains 300 values
damage_dealt contains 1-5000 values

This will generate an event hierarchy with: 100 * 300 * 5000 = 225,000,000 possible nodes. This is far too many. Also in this example, damage_dealt should be included as a floating point value after the event string. More specific information on formatting Design events can be found within our integration guides here.

If you are in breach of this policy we will reach out to you in the hopes of resolving the issue.

Implementation

The purpose of this section is to expose more examples of custom events in GameAnalytics and how they should be sent, from the planning phase up to aggregation and visualisation part in the tool. In this article we look at Design Events.

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.

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.

The following example of a hierarchy can be used 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 “:”. For example"

• 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);

note

The 123 represents the “timePlayed” value. The entire hierarchy can be generated dynamically.

Design Event Hierarchies

What’s important to understand with our custom design events is that you can generate a hierarchy of up to 5 parameters to represent an in-game event that you want to track. You can also attach a numerical value to represent some number for the event (e.g. time taken to complete a level). The numerical value is entirely optional and it is separate to the 5 parameter hierarchy, which consists of string values (or words in simpler terms). Custom progression events on the other hand only allow for 3 parameters, and should only be used to track player progression and specific events that can occur within a level. We’ll demonstrate an example use case below. In order to obtain the correct visualisations on your metrics, it is important to develop hierarchies structuring the data into sets of categories and subcategories (and possibly several levels of these). This is a best practice that will make it easier for you to identify, organise and work with your telemetry data. Although there is freedom when choosing the different subcategories, consistency should be maintained across the different events once the order is chosen. We recommend structuring your hierarchy as explained below: [category]:[sub_category]:[outcome].

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.

You may be wondering how this example implemented via code? Well here's an example of sending an event from this hierarchy via code:

GameAnalytics.NewDesignEvent ("SecretWeapons:NuclearCannon");

Example

Let’s create a use case for Design Events:

We have a game where the player completes levels (within 4 different worlds) in a linear fashion, and in order to complete the level you have to defeat non-player-characters (minions). We want to track the number of minions defeated on a level granularity. How many minions are our players defeating? Are there any particular levels where the minions are too low/too high

In this example, let’s look at a Unity SDK design event example:

GameAnalytics.NewDesignEvent ("World_2:Level_6:MinionsSlain", 123);

In this example the player defeated 123 non-player-character minions after finishing level 6 in world 2. Based on what was mentioned above, we can see 3 different parameters here and a numerical value attached to the event. The 3 parameters are:

• The World (World_2), assuming that the game has several worlds with levels under each world.
• The specific level under the world (Level_6)
• The actual event name that we want to track (MinionsSlain)

The numerical value is 123. You can have several outcomes. If we take the example above and wanted to track something else on top of this, we can replace “MinionsSlain” with a “Time” value to represent the amount of time in seconds it took to complete the level:

GameAnalytics.NewDesignEvent ("World_2:Level_6:Time", 85);

It’s important to utilise the hierarchy and parameters as much as possible to track exactly what you’re looking for. For example, if you excluded the World parameter, you wouldn’t know which world the player completed these events in. That may not be particularly useful data for you because if you’re looking at a level 6 event, it could have been in any world so you wouldn’t have that information unless you specify it in the event. Your event structure now looks like this:

This is quite simple for now, as it only consists of 2 outcome events, but they will obviously be multiplied depending on how many worlds and levels you have.