Record Events

It’s important to use data to refine your design, player experience, and revenue. This engages players and improves their game experience.

Record Custom Events

Custom Events must have a schema defined in Event Manager or they'll be classed as invalid. You can record Custom Events at any time once the SDK has been activated (see Initial Setup), and they are batched for upload. Batches are uploaded automatically every 60 seconds.

The following code is an example of how to send a Custom Event:

public class MyEvent : Event
	public MyEvent() : base("myEvent")

	public string FabulousString { set { SetParameter("fabulousString", value); } }
	public int SparklingInt { set { SetParameter("sparklingInt", value); } }
	public float SpectacularFloat { set { SetParameter("spectacularFloat", value); } }
	public bool PeculiarBool { set { SetParameter("peculiarBool", value); } }

public void RecordMyEvent()
	MyEvent myEvent = new MyEvent
		FabulousString = "hello there",
		SparklingInt = 1337,
		SpectacularFloat = 0.451f,
		PeculiarBool = true


Note that Custom Event parameter values must be one of the following primitive types: string, int, long, float, double or bool.

What needs to be tracked in the game?

When you design something in your game, you need to have a reason for it. Track how players interact with your game to validate your intentions and answer question such as:

  • How difficult is this level?
  • Is my tutorial easy to follow?
  • Have a lot of players purchased this offer?

For the example, ‘Is this level as hard as I think it is?’, you can track where players die in the level, how many tries it takes to complete the level, and what are the most popular items used to finish.

Custom Events and parameters

A Custom Event is the action or the result of an action by a player or your system in your game. Events cover all actions, for example:

  • A player finished a dungeon.
  • A player joins a guild.
  • An offer is displayed to players.
  • A player buys something.

When you have your Events, use parameters to add details. A parameter is any detail about an Event. For example, when a player finishes a dungeon, the Event would be dungeonCompleted. The parameters could be:

  • dungeonName: Which dungeon was finished.
  • Time: How long it look for the player to finish.
  • playerHealth: The health of the player at the end of the dungeon.
  • potionsUsed: How many potions the player used to finish the dungeon.

Detailed parameters add more depth to your data. In this puzzle game, we categorize the missionCompleted event by the movesRemaining parameter to gauge the game’s difficulty and if more moves are required.

Parameters can be many types of values, including:

  • String: Name of an item, username, and text entered.
  • Integer: Number of items owned, health points, or potions used at the end of the level.
  • Float: A complex completion rate or score.
  • Boolean: A true or false value.

An Event structure in Unity Analytics’ Event Manager.

Standard Events

Unity Analytics collects Standard Events automatically once you’ve integrated the SDK into your project. These Events are standard to every game, and are also used by out of the box dashboards and in Data Explorer.

These Standard Events include:

Event nameDescriptionTrigger type
newPlayerSends when a new player installs the app on their device.Auto
gameStartedSends at the start of a new session. A new session starts when the user first launches an app.Auto
gameEndedSends when a player exits the game.Auto
gameRunningSends periodically when the app is running to detect session activity.Auto
clientDeviceRecords the first time a user launches an app and when device information changes.Auto
ddnaForgetMeRecords when a player opt outs of data collection via the privacy plugin.Auto
transactionSends when a player makes an in-app purchase and tracks the purchase amount. Transaction validation is done via the Unity IAP.Auto when using Unity IAP
adImpressionCan be sent manually when a player has seen an ad within the game.
sdkStartSends when the SDK initialises.Auto
notificationOpenedSends when a Push Notification is opened or a notification was received while the game is in front.Auto
notificationServicesRecords the player’s push notification tokens.Auto
outOfGameSendSends when a Push Notification is sent to a player.Auto from Player Engagement
userAssignmentAutomatically assigns a player to a campaign for reporting.Auto from Player Engagement

Common tracking scenarios

First time user experience

In this case you want to check how many players complete the tutorial. Use the Standard Event newPlayer and one Custom Event that triggers once a tutorial step is completed, such as tutorialStepCompleted with the parameter stepID to indicate the ID or name of the step.

If you want more granularity in your tutorial analysis, you can also add an Event that tracks when the tutorial begins so that you can determine if the tutorial is starting properly for all players. You can also add an Event when the tutorial ends when a step is started to follow the complete player journey in the tutorial.

You can understand user drop off and where to optimize better with more Custom Events added to track within the first-time user experience.

An item is bought

For every virtual or real currency transaction in the game, you should always use the transaction Standard Event and add custom parameters to accommodate your needs. The transaction Standard Event is used to populate the revenue dashboard and metrics in the Data Explorer. You can validate your revenue using the transaction Event and the Unity IAP plugin. The transaction Event already has many useful parameters to register what the player spent money on, how much they spent and what they received. All the parameters under productsReceived and productsSpent help you get set up.

When tracking purchases, you need to track purchases in USD as separate parameters as well as local currency to normalize data and to have accurate revenue metrics. The transaction Event is a Standard Event and can be either triggered manually or automatically fired if the Unity IAP is integrated into your game.

You might be developing an RPG where the player can buy and receive heroes, gear and resources from multiple points such as the shop, popup offers, and a daily reward system. The following parameters help register most of the information of your transactions.

You cannot add extra parameters to the transaction event.

Feature adoption

Use both Standard and Custom Events to measure the success of new features within the game and how users adopt them. For example, you might want to introduce guilds into the game. This is a feature which is important for long-term engagement and player interactions, especially for RPGs. Implementing the following Events tracks guild engagement:

  • guildJoined: User joins a guild.
  • guildLeft: User leaves a guild.
  • guildMessageSent: User sends a message in guild chat.
  • guildRole: User has an admin role within the guild.

Analyzing each of these Events helps you determine how active users are within the guild feature and they can also be used with existing Events to see their overall engagement with the game. Try comparing users who join a guild versus those who don’t; it’s possible that users in guilds spend more money or play more often.

Player lifecycle

Tracking the user’s lifecycle throughout the game is important to determine when they stop playing the game or to identify any other issues with the game.

Using our current game example, you can track users by the following Events:

  • characterLevelUp: The current level of the user.
  • Transaction: When a user makes a purchase.
  • guildJoined: When a user joins a guild.
  • currencyGained: Amount of in-game currency gained.

Using a variety of these Events is useful to see how users are engaging with the game and if there are any dropoff points that need optimizing. Analyzing level distribution shows what level users get to before they stop playing. Additionally, tracking their transactions is important as spenders are often more engaged in the game and play for longer.