Analytics event parameters

Note: Gaming Services Analytics is now available as a preview packageA preview package is in development and not yet ready for production. A package in preview might be at any stage of development, from the initial stages to near completion.
See in Glossary. Gaming Services AnalyticsAbbreviation of Unity Analytics
See in Glossary is an improved offering that allows you to easily understand game performance and player behaviors so you can make strategic decisions. See the documentation.

Both Standard and Custom events allow you to send additional information to the Analytics Service as part of an event. The only difference between Standard and Custom Events is that most 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 have required or optional parameters which take precedence over any custom parameters.

Pass your custom parameters to the appropriate AnalyticsEvent function in the form of a Dictionary<string, object> instance. The keys of this dictionary are the parameter names, and the values are the parameter values. When creating this dictionary, maintain consistent key names and data types for each parameter in your event data, both within a single version of your game as well as from version to version. For example, don’t send a level name parameter as a number sometimes and as a string at other times. Doing this can make your data difficult to interpret.

Note: Do not begin the key names of the custom parameter dictionary with the prefix “unity”, which is reserved for internal Unity AnalyticsA data platform that provides analytics for your Unity game. More info
See in Glossary events.

Unity serializes values sent to the Analytics service. It parses number characters as numbers even if the data type you add to the dictionary is a string. In other words, adding the string “51” to the parameter dictionary is equivalent to adding the number 51.

You can pass up to ten parameters with an event. For Standard Events, this limit includes the required parameters and any optional parameters to which you assign a value (unused optional parameters don’t count against this limit). In addition, the length of an individual key name and string value passed to the event must not exceed 100 characters and the total length of all key names and string values must not exceed 500 characters.

For efficiency, you can create the parameter dictionary instance as a class member and reuse the dictionary each time you dispatch the event. Reusing the dictionary object avoids allocating memory each time you send the event. This reduces the memory allocations that the C# garbage collector needs to clean up. The more frequently you dispatch an event in a 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, the more benefit this technique provides. The following example defines a class that dispatches a Custom event. The class defines a parameter dictionary as an instance variable and sets the parameter values each time it sends an event.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Analytics;

public class MyCustomAnalyticsEvent : MonoBehaviour {
    private const string Name = "my_custom_event";

    private Dictionary<string, object> parameters 
        = new Dictionary<string, object>();

    void Start(){
        // Define parameters with default values
        parameters.Add("character_class", "Unknown");
        parameters.Add("health", 0);
        parameters.Add("xp", 0);
        parameters.Add("world_x", 0);
        parameters.Add("world_y", 0);
        parameters.Add("world_z", 0);
    }

    public bool Dispatch(string characterClass, 
                         int health, 
                         int experience, 
                         Vector3 location){
                         
        // Set parameter values for a specific event
        parameters["character_class"] = characterClass;
        parameters["health"] = health;
        parameters["xp"] = experience;
        parameters["world_x"] = location.x;
        parameters["world_y"] = location.y;
        parameters["world_z"] = location.z;

        // Send event
        AnalyticsResult result 
            = AnalyticsEvent.Custom(Name, parameters);
        if(result == AnalyticsResult.Ok){
            return true;
        } else {
            return false;
        }
    }
}

You can use the same technique for the custom parameters you send with Standard events.

• 2018–03–02 Page published

• 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