Standard Events

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:

• Application: Track the usage of basic elements in your application user interface
• Progression: Track player progress through your application or game
• Onboarding: Track the earliest interactions players have with your application or game
• EngagementEngagement is a broad measure of how players enjoy, or are otherwise invested, in your game. Impossible to measure directly, the following metrics are frequently used to estimate engagement: Retention, DAU, MAU, DAU/MAU, number of sessions, and session length. More info
  See in Glossary: Track important actions related to social sharing, achievements
• Monetization: Track revenue-related events as well as your in-game economies

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 AnalyticsAbbreviation of Unity Analytics
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

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.

Progression events

Progression events track players as they advance through your game. Analyze standard progression events to monitor player progress in your game.

Onboarding events

Onboarding events track the first-time user experience (FTUE). Analyze standard onboarding events to monitor the effectiveness of your tutorials.

Engagement events

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.

Monetization events

Monetization events track income and game economy to help you balance your resources and improve sources of revenue.

Scripting Standard Events

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 Asset 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