Skip to content

Custom Events

Custom Events are a powerful tool to record session data from your experience.

Custom Events automatically record x,y,z coordinates. If the position is not provided, it will use the position of the HMD. This allows events to be mapped to specific points in your experience. In conjunction with visual telemetry (gaze tracking), coordinates gives you the ability to map out how your Participants are interacting with your experience in 3d space.

There are two ways to record Custom Events - either by calling a function with all the properties as arguments or by constructing an object that will persist until manually recorded. The latter option will also automatically record a 'duration' property describing the time between its construction and when the event ends.

For C++, you must include PublicDependencyModuleNames.AddRange(new string[]{"Cognitive3D", "Json"}); in YourProject.Build.cs.

Basic Examples

An event requires a name. There is a also variation of this blueprint node that exposes the position of the event.

event simple

TWeakPtr<FAnalyticsProviderCognitive3D> provider = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (provider.IsValid())
{
//send an event with a name
provider.Pin()->customEventRecorder->Send("My Event");
//send an event with a name and a position
provider.Pin()->customEventRecorder->Send("My Event With Position",FVector(0,100,0));
}

Events can contain properties. Blueprint uses an array of AnalyticsEventAttr - this method is simple to set up, but sets all properties to a string type. In many cases, you should use the Make Custom Event node explained below. C++ uses FJsonObject and will correctly retain the property types.

event property

TWeakPtr<FAnalyticsProviderCognitive3D> provider = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (provider.IsValid())
{
//create some properties and send an event
TSharedPtr<FJsonObject> properties = MakeShareable(new FJsonObject());
properties->SetStringField("last login", FString("never"));
properties->SetNumberField("login attempts", 4);
provider.Pin()->customEventRecorder->Send("Login Attempt", properties);
}

Events can be linked to a Dynamic Object. For example, an Event when an product is purchased can reference which object was purchased. This requires a reference to a Dynamic Object component.

dynamic event

TWeakPtr<FAnalyticsProviderCognitive3D> provider = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (provider.IsValid())
{
 //send an event with a dynamic object
 FString dynamicObjectId = dynamicObjectPtr->GetObjectId()->Id;
 provider.Pin()->customEventRecorder->Send("Dynamic Object Event", properties, dynamicObjectId);
}

The Make Custom Event node is the most complex and most versatile. This will create a temporary Custom Event object that can be referenced elsewhere. The example here shows how to add an integer property, how to add a biometric sensor as a property and how to finish recording the event. This Custom Event does not need to be recorded immediately - it will automatically include a Duration property if Send is called later.

event object

TWeakPtr<FAnalyticsProviderCognitive3D> provider = FAnalyticsCognitive3D::Get().GetCognitive3DProvider();
if (provider.IsValid())
{
//create a custom event object and set properties on that
UCustomEvent* customEvent = NewObject<UCustomEvent>(this);
customEvent->SetCategory("Custom Event");
customEvent->SetDynamicObject(dynamicObjectPtr);
customEvent->AppendAllSensors();
customEvent->SetProperty("somekey1", 5);
customEvent->SetProperty("somekey2", "somevalue");
customEvent->SetPosition(FVector(0, 100, 0));
customEvent->Send();
}

Advanced Uses Cases

Trigger Areas

You can use Custom Events to identify when a Participant enters and exits a pre-defined region in your level. Recording when a participant enters an area could be useful to build Objectives with positional data normally only available in SceneExplorer.

At a high level, you could create a Custom Event when the participant enters a Trigger Volume and call 'Send at HMD Position' on that Custom Event when they leave. You'll also need to ensure that the Pawn is configured to activate ActorBeginOverlap Events.

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page.