Record Custom Events

Custom Events must have a schema defined in Event Manager or they'll be classed as invalid. You can record Custom Events at any time once the SDK has been activated (see Initial Setup), and they are batched for upload. Batches are uploaded automatically every 60 seconds.

As of version 5.1.0, the structure of a custom event must be encoded in a sub-class of the Event class we provide. This gives you type safety when working with the same event across multiple locations, and can help to prevent validation errors when the events are uploaded.

Using the generic CustomEvent class

For simplicity and quick turn-around, we offer a generic CustomEvent class that you can use out-of-the-box in a very similar way to the previous plain dictionary API. This comes at the cost of the type safety and validation options offered by using dedicated sub-classes for each type of event.

CustomEvent myEvent = new CustomEvent("MyEvent")
{
    { "fabulousString", "woah!" },
    { "peculiarBool", true },
    { "sparklingInt", 1337 },
    { "spectacularFloat", 313.37f }
};
AnalyticsService.Instance.RecordEvent(myEvent);

Note that although the Custom Event parameter values are an object type, values must actually be one of the following primitive types: string, int, long, float, double or bool. If you attempt to add an unsupported value type, the CustomEvent class throws an ArgumentException.

Using a specific Event sub-class

The following code is an example of how to make a sub-class of Event that matches your Custom Event's schema:

public class MyEvent : 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 with 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.

Note that Custom Event 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, which only exists for supported types.

The following code is an example of how to send a Custom Event using the sub-class you created:

MyEvent myEvent = new MyEvent
{
	FabulousString = "hello there",
	SparklingInt = 1337,
	SpectacularFloat = 0.451f,
	PeculiarBool = true
};

AnalyticsService.Instance.RecordEvent(myEvent);

Use event sub-classes to provide type safety and to add your own extra logic, and also provide additional functionality through the Validate() and Reset() methods.

Validate

The Validate() method is called before event serialization and can be used during development to check locally whether an event matches its schema or not. For example, many of the Standard events offered by the SDK displays warnings if they are missing required fields. You can also prevent an invalid event from being recorded at all by throwing an exception inside Validate().

Note that events that are recorded and uploaded and validated more thoroughly by the back-end, so take care in allowing invalid events to get through so that they are visible outside the application itself. However, this mechanism is primarily intended to provide fast feedback to assist initial implementation and debugging, so a loud failure may be useful.

protected override void Validate()
{
    base.Validate();

    if (!ParameterHasBeenSet("requiredParameter"))
    {
        Debug.LogWarning("A value for requiredParameter must be set!");
		// Event will be recorded but a warning will be displayed in the log.
    }
	
	if (!ParameterHasBeenSet("doubleRequiredParameter"))
	{
		throw new Exception("A value for doubleRequiredParameter REALLY must be set!");
		// Event will not be recorded at all.
	}
}

Reset

The Event class is designed to be pooled, so you can create a single instance and re-use it for the entire application lifecycle. Once an event has been serialized to the Analytics buffer, the Reset method is invoked to clear the Event of all its parameters, returning it to a blank state for the next round.

If you added any extra logic or fields of your own to your sub-class and want to make use of object pooling, you must extend the Reset method to clear up any state you might have accumulated.

public override void Reset()
{
    base.Reset();

    m_MyExtraSystemValue = null;
}