Custom Events

During the normal lifecycle of a Moonsense Session the user may wish to associate additional data to live alongside the captured sensor data. We provide this capability using user provided events we call CustomEvents. These events could be anything from tracking button clicks, user sign in actions, deep link interactions, navigation and so on. Custom events provided to the SDK are timestamped and slotted into the the Moonsense Bundle for consumption as a part of the standard read API, see here.


A Custom Event contains 3 parts:

  • Event Name - A non optional name provided to the Custom Event. At a minimum the user is expected to provide this name. The name should not exceed 50 characters.

  • Event Key - An optional key to uniquely identify this event within a given Moonsense Session. The key cannot exceed 50 characters.

  • Properties - A map containing additional attributes associated with the created Custom Event. This is also an optional field. The key in the map cannot exceed 50 characters and the value 500 characters.

Below is an example of a Custom Event:

session.addCustomEvent( eventName = "user_signed_in", eventKey = "log_in", properties = mapOf( "user_id" to "1234", "referral_id" to "ref_123", "attempts" to "1" ) )
session.addCustomEvent( eventName: "user_signed_in", eventKey: "log_in", properties: [ "user_id" : "1234", "referral_id" : "ref_123", "attempts" : "1" ] )
session.addCustomEvent( "user_signed_in", "log_in", { "user_id" : "1234", "referral_id" : "ref_123", "attempts" : "1", } )

The documentation for Custom Events can be found here:

Internal Implementation

Every custom event created is uniquely timestamped by the Moonsense SDK, and can be monitored on the timeline of the given Session. The event can be observed in relation to the other data captured by the SDK allowing the user to know exactly when it happened. A Custom Event can be created immediately after Moonsense.startSession()(we do not need to wait for onSessionStarted() to be invoked). However the SDK does not permit Custom Events to be added once a Session has been stopped i.e. onSessionStopped() has been called.

The SDK does validate every Custom Event provided and will throw an exception on failure(like exceeding the maximum character length for example).