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 Android SDK 17.2.0 or higher. For release details, see Android SDK Changelog.

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

Implement the InsiderEventListener interface and register it through Insider.Instance.events(). The SDK calls onEventRecorded once for every event it records.

The following table shows the parameters that the listener receives.

Method signatures

public InsiderEvents events()

// InsiderEvents
public void addObserver(@NonNull InsiderEventListener listener)

// InsiderEventListener
void onEventRecorded(@NonNull String name, @NonNull Map<String, Object> parameters, long timestamp)

fun events(): InsiderEvents

// InsiderEvents
fun addObserver(listener: InsiderEventListener)

// InsiderEventListener
fun onEventRecorded(name: String, parameters: Map<String, Any>, timestamp: Long)

Method examples

Register the listener in your Application class, after you initialize the SDK.

import android.app.Application;
import android.util.Log;
import com.useinsider.insider.Insider;
import com.useinsider.insider.InsiderEventListener;

public class MyApplicationClass extends Application {
    private final InsiderEventListener analyticsForwarder = (name, parameters, timestamp) -> {
        // Forward the event to your analytics tool.
        Log.d("InsiderEvents", name + " " + parameters + " " + timestamp);
    };

    @Override
    public void onCreate() {
        super.onCreate();
        Insider.Instance.init(this, "your_partner_name");
        Insider.Instance.events().addObserver(analyticsForwarder);
    }
}

import android.app.Application
import android.util.Log
import com.useinsider.insider.Insider
import com.useinsider.insider.InsiderEventListener

class MyApplicationClass : Application() {
    private val analyticsForwarder = InsiderEventListener { name, parameters, timestamp ->
        // Forward the event to your analytics tool.
        Log.d("InsiderEvents", "$name $parameters $timestamp")
    }

    override fun onCreate() {
        super.onCreate()
        Insider.Instance.init(this, "your_partner_name")
        Insider.Instance.events().addObserver(analyticsForwarder)
    }
}

Register the listener after Insider.Instance.init. If the SDK is not initialized yet, the listener is not registered and the SDK logs a warning.

Remove an event listener

Call removeObserver to stop receiving events. Only the listener you pass is removed; other listeners keep receiving events. Removal always takes effect, even if the SDK is disabled or the user has opted out.

Method signature

public void removeObserver(@NonNull InsiderEventListener listener)

fun removeObserver(listener: InsiderEventListener)

Method example

If you register a listener from an Activity or Fragment, remove it when that component is destroyed.

@Override
protected void onDestroy() {
    Insider.Instance.events().removeObserver(eventListener);
    super.onDestroy();
}

override fun onDestroy() {
    Insider.Instance.events().removeObserver(eventListener)
    super.onDestroy()
}

The SDK holds listeners with a strong reference and never removes them on its own. If you do not remove a listener, the listener and everything it references (e.g., the Activity) stay in memory.

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 since 1970, not milliseconds. Multiply it by 1000 to get milliseconds.

Date values in parameters

Date parameters arrive as formatted date strings, not as Date objects.

Threading, ordering, and error handling

• The listener is called on an internal background thread, not on the main thread. Switch to the main thread yourself if you update the UI.

• All listeners are called from the same thread, in the order the SDK recorded the events. A slow listener delays the listeners after it and the events that follow, so move expensive work to your own thread and return quickly.

• If your listener throws an exception, the SDK catches it so the app does not crash, and the other listeners are still called. Handle errors inside your listener so its own work is not lost.

• Adding the same listener twice keeps a single registration. The listener is called once per event.

Forward events to your analytics tool

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

private static final Set<String> FORWARDED_EVENTS =
        new HashSet<>(Arrays.asList("purchase", "item_added_to_cart", "product_detail_page_view"));

private final InsiderEventListener analyticsForwarder = (name, parameters, timestamp) -> {
    if (!FORWARDED_EVENTS.contains(name)) return;

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

private val forwardedEvents = setOf("purchase", "item_added_to_cart", "product_detail_page_view")

private val analyticsForwarder = InsiderEventListener { name, parameters, timestamp ->
    if (name !in forwardedEvents) return@InsiderEventListener

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