Version: 2022.1
Advanced Integration (SDK)
Monetization

Custom Events

Custom events can be any specific in-game action your user performs. They allow you to track player behavior Unity AnalyticsAbbreviation of Unity Analytics
See in Glossary
does not track automatically, such as level achievement, 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
change, entering a store, or interacting with game objects. Each custom event can have its own parameters. Setting parameters on your event allows you to filter data collected at the time the event occurred. Visualization tools for Custom Events can be viewed in 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.

// Reference the Unity Analytics SDK namespace
using UnityEngine.Cloud.Analytics;

//  Use this call for wherever a player triggers a custom event
UnityAnalytics.CustomEvent(string customEventName,
IDictionary<string, object> eventData);
UnityAnalytics.CustomEvent Input Parameters
Name Type Description
customEventName string Name of custom event. Name cannot include the prefix “unity.” — This is a reserved keyword.
eventData dictionary Additional parameters sent to Unity AnalyticsA data platform that provides analytics for your Unity game. More info
See in Glossary
at the time the custom event was triggered. eventData key cannot include the prefix “unity.” — This is a reserved keyword.

A few considerations with regards to the custom events:

  • Be consistent! Maintain consistent data types for each parameter in your event data. For example, don’t send a level parameter as a number, then change it to be a string. Doing so can lead to erroneous behavior, making your data difficult to interpret.
    • Boolean (true/false)
    • String (characters)
    • Numbers (int, float, etc.).
  • Default limit of 10 parameters per custom event.
    • If there are more parameters passed, the call will fail with a return value of AnalyticsResult.TooManyItems
  • Default limit of 500 characters for the dictionary content.
    • If more than 500 characters are passed, the call will fail with return value of AnalyticsResult.SizeLimitReached
  • Default limit of 100 custom events per hour, per user.
    • If more than 100 events per hour are called, the call will fail with return value of AnalyticsResult.TooManyRequests
  • Consider how parameters are parsed by the Analytics system.
    • All numbers, ints, floats, etc., even if sent as strings, are parsed as numbers.
    • Only strings and Booleans are considered ‘categorizable’.
    • Consequently, if you want something to be summed or averaged, send it as a number (e.g., 51 or ‘51’). If you want it to be categorized, as you would with a level or option, make sure it will parse as a string (e.g., ‘Level51’).

In the example below we are interested in knowing what our user had in their inventory at the time the game ended.

// Reference the Collections Generic namespace
  using System.Collections.Generic;

  int totalPotions = 5;
  int totalCoins = 100;
  string weaponID = "Weapon_102";
  UnityAnalytics.CustomEvent("gameOver", new Dictionary<string, object>
  {
    { "potions", totalPotions },
    { "coins", totalCoins },
    { "activeWeapon", weaponID }
  });

Press Play

To send test Custom Event data to our servers and validate your integration, trigger your Custom Event during Editor Play mode.

Advanced Integration (SDK)
Monetization