Use Standard EventsStandard events are application-specific events that you dispatch in response to important player actions or milestones. Standard events have standardized names and defined parameter lists. More info
See in Glossary to track user experience and player behavior across five major areas:
The list of Standard Events covers a set of things that you might find useful to track in your games and applications. For example, most games have a concept of player progress, which could mean puzzles completed, matches played, RPG-type experience earned, or some other notion. By tracking standard progression events, you can better understand where players stop progressing and, ultimately, where they stop playing.
Most Standard Events define required and optional parameters that provide additional information about the state of your game when an AnalyticsA data platform that provides analytics for your Unity game. More info
See in Glossary event is sent. You can also define your own custom parameters. Setting parameters on your event allows you to filter data collected at the time the event occurred. Visualization tools for Standard and Custom Events can be viewed on the Analytics Dashboard, including Data ExplorerA Unity Analytics Dashboard page that allows you to build, view and export reports on your Analytics metrics and events. You can also see how metrics and custom events change over time. More info
See in Glossary, Funnel Analyzer, and Segment Builder.
Unity Analytics limits the number of Standard and Custom Events it accepts to 100 per hour, per user. In other words, if a single user playing your game manages to trigger more than 100 Standard or Custom Events within an hour, Analytics discards the additional events.
Note: To use Standard Events prior to Unity 2017.3, first download and import the Standard Events SDK from the Unity Asset storeA growing library of free and commercial assets created by Unity and members of the community. Offers a wide variety of assets, from textures, models and animations to whole Project examples, tutorials and Editor extensions. More info
See in Glossary.
Application events track player interaction with the application outside of the game itself (for example, in the menu or cut-scene screens before or after a level). You can analyze application events to see whether players use the basic parts of your user interface as often as you expect.
| Event name | Purpose |
|---|---|
| screen_visit | Player opened a screen in the UI(User Interface) Allows a user to interact with your application. More info See in Glossary, such as a high score or settings screen. |
| cutscene_start | Player began watching a cinematic cutscene. |
| cutscene_skip | Player skipped past a cinematic cutscene. |
Progression events track players as they advance through your game. Analyze standard progression events to monitor player progress in your game.
| Event name | Purpose |
|---|---|
| game_start | Player began a new game (useful for games with a distinct beginning and ending). |
| game_over | Player ended the game (useful for games with a distinct beginning and ending). |
| level_start | Player started a level. |
| level_complete | Player successfully completed a level. |
| level_fail | Player lost a level. |
| level_quit | Player quit out of a level. |
| level_skip | Player skipped past a level. |
| level_up | Player increased in rank or RPG-style experience level. |
Onboarding events track the first-time user experience (FTUE). Analyze standard onboarding events to monitor the effectiveness of your tutorials.
| Event name | Purpose |
|---|---|
| first_interaction | Player completed any interaction after opening the game for the first time. |
| tutorial_start | Player began a tutorial. |
| tutorial_step | Player passed a milestone in a tutorial. |
| tutorial_complete | Player completed a tutorial. |
| tutorial_skip | Player skipped a tutorial. |
Engagement events help you understand whether your players are engaging with your game, and whether they’re performing actions highly correlated with retention and virality.
| Event name | Purpose |
|---|---|
| push_notification_enable | Player enabled push notifications. |
| push_notification_click | Player responded to a pushed message. |
| chat_msg_sent | Player sent a chat message. |
| achievement_unlocked | Player completed an achievement. |
| achievement_step | Player completed a milestone towards an achievement. |
| user_signup | Player connected with a social network. |
| social_share | Player shared something such as an invite or gift through a social network. |
| social_accept | Player accepted something shared through a social network. |
Monetization events track income and game economy to help you balance your resources and improve sources of revenue.
| Event name | Purpose |
|---|---|
| store_opened | Player opened a store. |
| store_item_click | Player selected an item in a store. |
| iap_transaction | Player spent real-world money to make an in-app purchase. |
| item_acquired | Player acquired a resource within the game. |
| item_spent | Player expended an item within the game. |
| ad_offer | Player had an opportunity to watch an ad. |
| ad_start | Player started watching an ad. |
| ad_complete | Player finished watching an ad. |
| ad_skip | Player skipped an ad before completion. |
| post_ad_action | Player completed an action prompted by an ad. |
To dispatch a Standard event from a script, add the following namespace:
using UnityEngine.Analytics;
Note: When using the Standard Events SDK from the Unity AssetAny media or data that can be used in your game or Project. An asset may come from a file created outside of Unity, such as a 3D model, an audio file or an image. You can also create some asset types in Unity, such as an Animator Controller, an Audio Mixer or a Render Texture. More info
See in Glossary store, use the namespace UnityEngine.Analytics.Experimental instead.
Now you can dispatch Standard Events using the AnalyticsEvent class. Each Standard Event has a corresponding static function. For example, to send the game_start event, call the following function:
AnalyticsEvent.GameStart();
Many Standard Events have required parameters, and several have optional parameters. You can also add your own additional parameters in a dictionary. For example, if you wanted to track what screens players visit using the ScreenVisit event, but also wanted to track which screen they visited from, you can pass that information in a dictionary object:
public static void ReportScreenVisit(string screenName, string currentScreenName)
{
AnalyticsEvent.ScreenVisit(screenName, new Dictionary<string, object>
{
{ "from_screen", currentScreenName }
});
}
The total number of required parameters, optional parameters (only counting those that you use) and additional parameters cannot exceed ten. In other words, if an event function has 2 required parameters and you set 1 out of 2 optional parameters, you can pass a dictionary containing up to seven additional key-value pairs to the function. If you set both of the optional parameters in the same event, then your dictionary could only contain six key-value pairs.
Standard Event code example
The following class provides an example that uses the standard MonoBehaviour event functions to dispatch the Standard Events related to starting and ending levels.
The Awake function dispatches the level_start event. The example provides both the level name and the level index, but only one is required. The example also uses the name and index from the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary object, but you can use different values.
The OnDestroy function dispatches a level_complete, level_fail, level_skip, or level_quit event, based on the current level state value (which, in a real game, would be set by other code in the level using the SetLevelPlayState() function defined in this example). The example adds some additional parameters to these events using a dictionary called “customParams”.
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEngine.Analytics;
public class LevelEventManager : MonoBehaviour {
public enum LevelPlayState {InProgress, Won, Lost, Skip, Quit}
private Scene thisScene;
private LevelPlayState state = LevelPlayState.InProgress;
private int score = 0;
private float secondsElapsed = 0;
private int deaths = 0;
void Awake () {
thisScene = SceneManager.GetActiveScene();
AnalyticsEvent.LevelStart(thisScene.name,
thisScene.buildIndex);
}
public void SetLevelPlayState(LevelPlayState newState){
this.state = newState;
}
public void IncreaseScore(int points){
score += points;
}
public void IncrementDeaths(){
deaths++;
}
void Update(){
secondsElapsed += Time.deltaTime;
}
void OnDestroy(){
Dictionary<string, object> customParams = new Dictionary<string, object>();
customParams.Add("seconds_played", secondsElapsed);
customParams.Add("points", score);
customParams.Add("deaths", deaths);
switch(this.state){
case LevelPlayState.Won:
AnalyticsEvent.LevelComplete(thisScene.name,
thisScene.buildIndex,
customParams);
break;
case LevelPlayState.Lost:
AnalyticsEvent.LevelFail(thisScene.name,
thisScene.buildIndex,
customParams);
break;
case LevelPlayState.Skip:
AnalyticsEvent.LevelSkip(thisScene.name,
thisScene.buildIndex,
customParams);
break;
case LevelPlayState.InProgress:
case LevelPlayState.Quit:
default:
AnalyticsEvent.LevelQuit(thisScene.name,
thisScene.buildIndex,
customParams);
break;
}
}
}
Note that this example only uses the custom parameter dictionary created in OnDestroy() once. However, when you dispatch an event that uses such a dictionary frequently, you should create a single instance of the dictionary and reuse it rather than creating a new dictionary each time. Reusing the dictionary object reduces memory allocations that must be garbage collected in a future frame. See Analytics Event Parameters for more information.
2018–03–02 Page published with no editorial review
2018–03–02 - Service compatible with Unity 5.2 onwards at this date but version compatibility may be subject to change
New feature in 5.2