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 tool, such as Google Analytics 4 (Firebase), Mixpanel, or Amplitude.

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 Cordova SDK 4.1.0 or higher. For release details, see Cordova Changelogs.

Before you start

Check the following before you add a listener:

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

• 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.

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

events: InsiderEvents;

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

Method example

Register the listener after you initialize the SDK.

document.addEventListener('deviceready', onDeviceReady, false);

let insiderEventSubscription;

async function onDeviceReady() {
    await Insider.init('your_partner_name', 'group.com.your-company.your-app', handleInsiderCallback);

    insiderEventSubscription = 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. Each subscription is removed on its own, so removing yours does not affect other listeners. Calling remove() more than once is safe.

Method signature

// InsiderEventSubscription
remove(): void;

Method example

if (insiderEventSubscription) {
    insiderEventSubscription.remove();
    insiderEventSubscription = undefined;
}

addObserver returns undefined and logs a warning if the callback is not a function.

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's Date and Date.now() use milliseconds. Use new Date(timestamp * 1000). new Date(timestamp) gives a date in January 1970.

Date values in parameters

Date parameters arrive as ISO-8601 strings (e.g., "2024-06-01T00:00:00.000Z"). Parse them with new Date(value).

Ordering and error handling

• You can add several listeners. The plugin registers a single native listener, delivers each event to all of your callbacks, and removes the native listener when the last subscription is removed.

• Events are delivered to the WebView in the order the SDK recorded them. 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.