Create a custom event

Unity Analytics comes with standard events that work without the need for additional configuration. However, you can create custom events to record player actions that are unique to your game. These must be created on the Unity Dashboard and then implemented in your game code.

Note: Legacy Unity Analytics custom events will need to be re-created in the UGS Event Manager for the data they are sending to be received and considered valid by UGS Analytics. For more information, see the upgrade guide.

Create a custom event through the Unity Dashboard

  1. Go to the Event Manager and select Add New > Custom Event.
  2. Give it a name and description.
  3. The first character of your event name needs to be a letter.
  4. The name must consist only of English alphanumeric and underscore characters.
  5. Select Assign Parameter to add parameters to your event. You can add existing parameters created or create new ones here by selecting Assign Parameter > Create New Parameter. A parameter needs a name, description and data type.
  6. The first character of your parameter name must be a letter.
  7. The name must consist only of English alphanumeric and underscore characters (a-z, A-Z, 0-9 or _).
  8. There is a set of reserved parameter names that cannot be used in custom event definitions (see the list of reserved parameter names).
  9. Ensure your event is set to Enabled.

Note: Once created, you can enable or disable your custom event, but you can't delete it.

Note: Parameters can be edited but not deleted. You can add up to 1,500 parameters to the environment.

Note: you can create parameters from the main Event Manager page by seleecting Add New > Custom Parameter.

If you wish to copy this event to another environment, see the copy custom events to another environment tutorial.

Create a matching Event class in your game

Note: These API methods changed in version 5.1.0 of the SDK. Please ensure you have the latest version of the SDK installed!

The UGS Analytics SDK is designed to help you match your game code with your event schemas as defined in the Unity Dashboard. While we provide helper classes for all of the standard events that you might encounter, you must make your own helper classes to support the custom events that are unique to your game. This is done through making sub-classes of the abstract Event class. This gives you type safety when working with the same event across multiple locations, and can help you to prevent validation errors when the events are uploaded.

The following code is an example of how to make a sub-class of Event, for an event called myEvent that has individual parameters of each of the four available types:

public class MyEvent : Unity.Services.Analytics.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); } }
}

The Event base class provides the SetParameter(...) methods, which take in the string parameter name from your event schema and a value type. Wrapping this in write-only properties or type-safe methods ensures that repeated uses of the same event are less likely to introduce mistakes, and that changes to the underlying schema or the way you populate events can be made with the benefit of refactoring tools. Since the names of parameters in events are case sensitive, and their values must match the types defined in the Event Manager, this gives you one place to manage the mapping between what the game can supply and what is expected by the Analytics back-end.

Note: Parameter values must be one of the following primitive types: string, int, long, float, double or bool. This restriction is enforced by the SetParameter(...) methods provided by the Event base class.

Once you have created your event schema and helper class, you can record it at any time after the SDK has been activated (see SDK setup) using the AnalyticsService.Instance.Record(...) method. For more information, see the how to record an event tutorial.