Skip to main content

Custom events & traces

Beta

This page documents Bugsee React Native SDK 7.x, which is in beta and can change between betas. The stable release is 6.x: see the 6.x documentation. Upgrading? See Migrating from 6.x to 7.x.

Besides what Bugsee captures automatically, you can add your own signals to the session a report replays:

  • Events mark that something happened (payment_processed, onboarding_skipped), optionally with parameters.
  • Traces follow how one value changes over time (cart_total, logged_in), so you can see its state right before a problem.

Both are recorded on the report timeline, next to the video, logs and network events. They keep recording during a blackout, which hides only what describes the screen.

Calls made before Bugsee.launch are not held until launch. Record events and traces after launch.

Custom events​

Bugsee.event(name, params?) records a named event:

import Bugsee from '@bugsee/react-native';

// Without parameters
Bugsee.event('payment_processed');

// With parameters
Bugsee.event('payment_processed', {
  amount: 125,
  currency: 'USD',
  items: [{ sku: 'A-100', quantity: 2 }],
  coupon: null,
});

params is a plain object. Leave it out (or pass undefined) for an event without parameters; the event is then recorded with no parameters at all, not with an empty object.

Accepted parameter values​

Each value in params, at any depth, is one of (EventParamValue):

ValueRules
string
numberFinite (no NaN or Infinity), and smaller than 263 in magnitude.
boolean
nullRecorded as null on both platforms.
arrayOf accepted values.
plain objectOf accepted values. A member whose value is undefined is left out, as JSON.stringify does.

Objects and arrays can nest up to 16 levels deep.

The parameters are checked and copied when you call event, so changing your object afterward does not change what was recorded.

What is rejected​

event throws synchronously, and records nothing, when its input is outside that set. The message names the path of the bad value, such as params.items[0].added:

InputThrown
name that is not a stringTypeError
name that is an empty stringRangeError
params that is null, an array, or not a plain objectTypeError
A Date, Map, Set, typed array, class instance, function, bigint or symbol valueTypeError
undefined as an array elementTypeError
An object or array that contains itself (a cycle)TypeError
A non-finite number, or one of 263 or more in magnitudeRangeError
Nesting deeper than 16 levelsRangeError
Changed from 6.x

6.x accepted null as "no parameters". In 7.x, Bugsee.event('name', null) throws TypeError: leave the argument out instead.

Convert values the SDK does not accept before you pass them, for example a Date to date.toISOString() and a Map to Object.fromEntries(map).

Custom traces​

Bugsee.trace(name, value) records the current value of a trace. Each call adds a new point for that name, so call it whenever the value changes:

import Bugsee from '@bugsee/react-native';

Bugsee.trace('credit_balance', 15);       // number
Bugsee.trace('current_location', 'USA'); // string
Bugsee.trace('logged_in', true);          // boolean

The value (TraceValue) is a string, a boolean, or a finite number smaller than 263 in magnitude. A boolean is recorded as a boolean on both platforms, not as 0 or 1.

trace throws synchronously, and records nothing, for:

InputThrown
name that is not a stringTypeError
name that is an empty stringRangeError
A value that is not a string, number or boolean (including null and undefined)TypeError
A non-finite number, or one of 263 or more in magnitudeRangeError

Handling the checks​

Because both calls throw on invalid input, guard calls whose input you do not control, so a bad value does not break the code path that records it:

import Bugsee, { type EventParams } from '@bugsee/react-native';

function recordEvent(name: string, params?: EventParams): void {
  try {
    Bugsee.event(name, params);
  } catch (error) {
    console.warn('Bugsee event not recorded:', error);
  }
}

The types EventParams, EventParamValue and TraceValue are exported, so TypeScript catches most invalid values at compile time.

Found an issue, typo, or wrong statement on this page? Report it now →