Listen to recorded events

Event Listener lets your app observe every event the Insider SDK records on the device. You can forward these events to your own analytics stack, such as Google Analytics 4 (Firebase), Mixpanel, Amplitude, or your own backend.

The listener receives custom events, default events, and campaign events (e.g., push_session and inapp_seen). Each event arrives with its parameters and the time it was recorded.

This method is available on React Native SDK 9.0.0 or higher. Expo projects use the same react-native-insider API. For release details, see React Native Changelogs.

Before you start

Check the following before you add a listener:

• The Insider SDK is initialized, and you add the listener after initialization.

• A session is started. Events tagged before a session starts are delivered when the session starts.

• The user has not opted out of data collection. Nothing is delivered while the user has opted out. For details, see Set GDPR consent.

Event Listener is separate from registerInsiderCallback and does not replace it. Push and in-app callbacks keep working as before. For details, see Set callback.

Add an event listener

Call Insider.events.addObserver with a callback. The callback is called once for every event the SDK records. The method returns a subscription that you use to stop receiving events.

The following table shows the parameters that the callback receives.

Method signature

static get events(): InsiderEvents;

// InsiderEvents
addObserver(
  callback: (name: string, parameters: { readonly [key: string]: any }, timestamp: number) => void
): InsiderEventSubscription | undefined;

Method example

Register the listener after you initialize the SDK.

import Insider from 'react-native-insider';

const subscription = Insider.events.addObserver((name, parameters, timestamp) => {
  // Forward the event to your analytics tool.
  console.log(name, parameters, new Date(timestamp * 1000));
});

Remove an event listener

Call remove() on the subscription to stop receiving events. Other subscriptions keep receiving events.

Method signature

// InsiderEventSubscription
remove(): void;

Method example

Remove the subscription when the component that added it unmounts.

import { useEffect } from 'react';
import Insider from 'react-native-insider';

export function useInsiderEventForwarding() {
  useEffect(() => {
    const subscription = Insider.events.addObserver((name, parameters, timestamp) => {
      // Forward the event to your analytics tool.
    });

    return () => subscription?.remove();
  }, []);
}

addObserver returns undefined if the SDK is not available or the callback is not a function. Use optional chaining (subscription?.remove()) when you remove the subscription.

Event details

Which events are delivered

The listener receives every event the SDK records. The following events are delivered:

• Custom events and default events.

• Campaign events, such as inapp_seen and push_session.

• session_start.

• Events you create by calling the tag event methods from inside the callback. This is safe and does not cause recursion.

The following events are not delivered:

• Events recorded while the SDK is disabled or the user has opted out of data collection.

• Events dropped by the per-session event limit.

• flush_event, the SDK heartbeat event.

• Event names that Insider One excludes from listener delivery for your app.

Event timestamps

timestamp is in seconds, while JavaScript Date and Date.now() use milliseconds. Use new Date(timestamp * 1000). Using new Date(timestamp) gives a date in January 1970.

Date values in parameters

The SDK preserves nested objects and arrays in parameters. Date parameters arrive as formatted date strings.

Ordering and error handling

• You can add several listeners. The SDK delivers each event to all of your callbacks.

• Callbacks are called in the order the SDK recorded the events.

• The callback runs for every event, so keep it light and do not block.

• An error thrown from one callback does not stop the other callbacks from receiving the event.

Forward events to your analytics tool

The following example forwards selected events and converts the timestamp to milliseconds, which most analytics tools expect.

const FORWARDED_EVENTS = new Set(['purchase', 'item_added_to_cart', 'product_detail_page_view']);

Insider.events.addObserver((name, parameters, timestamp) => {
  if (!FORWARDED_EVENTS.has(name)) return;

  const recordedAtMillis = timestamp * 1000;
  // Send name, parameters, and recordedAtMillis to your analytics tool.
});

Forward only the event names you need. GA4 allows up to 500 distinct event names per user, so forwarding every Insider event can push your own events over that limit.

Event parameters may contain user data. You are responsible for what you send to third-party tools. Forward an allow-list of events and parameters, as in the example above.

Limits

• Events dropped by the per-session event limit are never delivered, so the stream you forward matches what Insider One records.

• Priority events such as inapp_seen, push_session, and confirmation_page_view bypass the limit and are always delivered.

• Events you create from inside the callback are delivered to every listener, and they count toward the per-session event limit.

• Insider One can exclude specific event names from listener delivery for your app. flush_event is never delivered.