Skip to content

Custom Events

Custom Events are the major way Cognitive3D collects user interactions from your product.

Tracking Custom Events

These are essential for understanding user behavior, tracking progress through tasks, and identifying points of friction or success.

Each Custom Event is visualized as a point on the session timeline in SceneExplorer, allowing you to see exactly when and where an action occurred in the 3D space.

Sending a Custom Event

Sending a Custom Event is a single function call. You provide a descriptive name for the event and the 3D position where it occurred.

Basic Event

At its simplest, you can send an event with just a name and a position. The position should be an array of [x, y, z] coordinates.

// The position where the event happened in world space
const eventPosition = [1.5, 1.2, -3.0];

// Send the event
c3d.customEvent.send('player_jumped', eventPosition);

Adding Context with Properties (Props)

To make your analytics truly powerful, you can attach a properties object to any Custom Event. This allows you to add rich, contextual data to the event, which can be used for detailed filtering and analysis on the dashboard.

The properties object can contain any key-value pairs you need.

const eventPosition = [10.2, 0.4, 8.1];

// Define a properties object with relevant data
const eventProperties = {
    weapon_used: 'Plasma Rifle',
    target_type: 'EnemyDrone',
    damage_dealt: 75,
    was_critical_hit: true
};

// Send the event with its properties
c3d.customEvent.send('enemy_hit', eventPosition, eventProperties);

Automatically recorded Events

The SDK also sends some events automatically to track important session and hardware events. You will see these appear in your session data without any extra code.

  • Session start: Fired automatically when c3d.startSession() is successfully called, marking the beginning of data collection.

  • Session end: Fired automatically when c3d.endSession() is called, marking the end of the user's session.

  • Left Controller Lost tracking: Fired when the left controller tracking is lost.

  • Right Controller Lost tracking: Fired when the right controller tracking is lost.

  • Left Controller regained tracking: Fired when tracking is restored for the left controller.

  • Right Controller regained tracking: Fired when tracking is restored for the right controller.

Configuration and Batching

Custom Events are collected locally and sent to the server in batches. You can control the size of these batches in your configuration.

In settings.js:

// settings.js
export default {
  config: {
    // ... other settings
    // Number of Custom Event snapshots to store before sending
    customEventBatchSize: 64,
  },
};

At Runtime:

// Change the batch size to 32 during the session
c3d.config('customEventBatchSize', 32);

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 or join our Discord.