Custom Events

Any event that could not be accommodated through predefined events, can be created through Custom Events.

Overview

Custom events allow you to track specific user interactions and business events that are unique to your application. These events provide detailed insights into user behavior and help you understand how users interact with your app's features.

Types of Events

Events in Upshot.ai are classified as timed and non-timed events.

Non-Timed Events

An event where the start time and an end time are the same is a non-timed event.

Example: A button has been clicked. It does not matter how long the button has been pressed for, this is a non-timed event, where you are only interested in the fact that the button has been clicked.

Timed Events

An event which has different start and end times is a timed event. Timed events have to be closed for the provided eventId. Timed events can be closed in two ways: Set Data And close the created event or simply close the event for the eventId.

Example: A game level takes 30 seconds to finish. So a "game level played" event starts at X and ends at Y. There's a time component associated with the event here, hence it is considered as a timed event.

Creating Custom Events

Basic Usage

JavaScript

import Upshot from "react-native-upshotsdk";
// Create a custom event
Upshot.createCustomEvent(
  eventName,
  JSON.stringify(payload),
  isTimed,
  function (eventId) {
    console.log("Custom Event ID:", eventId);
  }
);

TypeScript

import Upshot  from 'react-native-upshotsdk';

// Create a custom event with proper typing
Upshot.createCustomEvent(
  eventName: string,
  JSON.stringify(payload),
  isTimed: boolean,
  (eventId: string | null) => {
    if (eventId) {
      console.log('Custom Event ID:', eventId);
    } else {
      console.error('Failed to create custom event');
    }
  }
);

Event Properties

Properties provide context for events and help you understand user behavior better:

JavaScript

import Upshot from 'react-native-upshotsdk';
// Example with multiple property types
const properties = {
  string_prop: "value",
  number_prop: 42,
  bool_prop: true,
  date_prop: new Date() //In TImeStamp with milli seconds,
  user_level: 5,
  category: "gaming",
};

Upshot.createCustomEvent(
  "custom_event",
  JSON.stringify(properties),
  false, // non-timed event
  function (eventId) {
    console.log("Custom Event ID:", eventId);
  }
);

TypeScript

import Upshot from "react-native-upshotsdk";
interface CustomEventProperties {
  string_prop: string;
  number_prop: number;
  bool_prop: boolean;
  array_prop: string[];
  date_prop: string;
  user_level?: number;
  category?: string;
}

// Example with multiple property types
const properties: CustomEventProperties = {
  string_prop: "value",
  number_prop: 42,
  bool_prop: true,
  array_prop: ["item1", "item2"],
  date_prop: new Date().toISOString(),
  user_level: 5,
  category: "gaming",
};

Upshot.createCustomEvent(
  "custom_event",
  JSON.stringify(properties),
  false, // non-timed event
  (eventId: string | null) => {
    if (eventId) {
      console.log("Custom Event ID:", eventId);
    }
  }
);

Timed Events

For events that have a duration, you can create timed events and close them when the activity is complete:

JavaScript

import Upshot from "react-native-upshotsdk";
// Start a timed event
const startProperties = {
  level: 1,
  difficulty: "easy",
};

Upshot.createCustomEvent(
  "game_level_started",
  JSON.stringify(startProperties),
  true, // timed event
  function (eventId) {
    if (eventId) {
      console.log("Timed Event Started:", eventId);

      // Store eventId to close later
      // When the level is completed, close the event
      setTimeout(() => {
        const endProperties = {
          level: 1,
          difficulty: "easy",
          score: 1500,
          time_taken: 30,
        };

        Upshot.setValueAndClose(JSON.stringify(endProperties), eventId);
      }, 30000); // Close after 30 seconds
    }
  }
);

TypeScript

import Upshot from "react-native-upshotsdk";
interface GameLevelProperties {
  level: number;
  difficulty: string;
  score?: number;
  time_taken?: number;
}

// Start a timed event
const startProperties: GameLevelProperties = {
  level: 1,
  difficulty: "easy",
};

Upshot.createCustomEvent(
  "game_level_started",
  JSON.stringify(startProperties),
  true, // timed event
  (eventId: string | null) => {
    if (eventId) {
      console.log("Timed Event Started:", eventId);

      // When the level is completed, close the event
      const endProperties: GameLevelProperties = {
        level: 1,
        difficulty: "easy",
        score: 1500,
        time_taken: 30,
      };

      Upshot.setDataAndCloseCustomEvent(
        eventId,
        JSON.stringify(endProperties),
        (success: boolean) => {
          console.log("Event closed:", success);
        }
      );
    }
  }
);

Best Practices

1. Use descriptive event names - Choose clear, consistent naming conventions
2. Include relevant properties - Add context that helps with analysis
3. Follow naming conventions - Use snake_case for event names and properties
4. Validate event data - Check data types and required fields before sending
5. Document event taxonomy - Maintain a list of all custom events and their properties
6. Use timed events appropriately - Only for events with meaningful duration
7. Keep property values simple - Use primitive types when possible
8. Batch related events - Group similar events for better analysis