App events using the app intercept SDK

You can show an app intercept at the exact moment you care about, like a finished checkout, a first upload, or a canceled subscription. We call that moment an app event. Your app records it with one line of code, and the Ethnio SDK checks it against your app intercept triggers. If a trigger matches, the study's app intercept shows.

⚠️ You'll need our SDK for app events

Only the Ethnio SDK for iOS and Android can record app events.


Record an app event

Your developer adds one recordEvent  call to the app, right where the moment happens. You pick the event name. Just make sure the trigger uses the same one.

iOS (Swift)

Ethnio.recordEvent("checkout_done", properties: ["plan": "pro", "cart": "full"])

Android (Kotlin)

Ethnio.recordEvent("checkout_done", properties = mapOf("plan" to "pro", "cart" to "full"))

The properties are optional. Without them, the call is just Ethnio.recordEvent("checkout_done") . Your developer can make the call from any thread, and it returns right away.

You don't have to write these lines yourself. Each saved trigger on the app intercept's Triggers tab comes with a matching Swift line and Kotlin line, ready to copy.

Keep in mind that app events only match after your app registers the study or an activation code. Read more about the two ways your app can use triggers.


Event names

  • The name has to match the trigger's Event name exactly, upper and lower case included. For example, Checkout_Done  doesn't match checkout_done .
  • Spaces and tabs at the start or end of the name don't count. The SDK removes them.
  • A name can be up to 100 characters long.
  • Names that start with ethnio:  are reserved for us, and the SDK ignores those app events. The one exception is the preview event ethnio:preview:<study id> . It tests a study in a build of your app that registers the study's activation code.

💡 Pro tip: agree on the names early

A new event name means a new recordEvent  call, so it has to wait for your next app release. Ask your developer which events the app already records, and use those exact names in your triggers.


Event properties

Event properties are extra details about the moment, as keys and values. Your trigger's conditions read them. For example, if a checkout_done  trigger has the condition that plan  is pro , it only matches checkouts on the Pro plan.

  • A condition passes when the event has the property and its value is one of the condition's values, letter for letter. If the property is missing, the condition fails.
  • Conditions also read the embedded data your app passed when it registered the study or the activation code. If both have the same key, the event property wins.
  • The SDK keeps up to 20 properties per event. A key can use the letters a to z and A to Z, digits, _ , and - , with up to 100 characters. A value can have up to 255 characters. The SDK drops any other property.
  • Keys that start with ethnio_  are reserved, and so are preview , sdk_key , l , and invite_done . The SDK drops them, and a condition can't use them.

Please note that event properties never reach the study's targeting rules. Targeting only reads the embedded data from registerIntercept .


What leaves the phone

App events stay on the phone. The SDK checks each one against the triggers it already has. If no trigger matches, the app event never leaves the phone, so Ethnio never sees it.

When a trigger matches, the SDK loads the study's app intercept. Only then does the event reach Ethnio. Its name and its event properties come along as embedded data, so the study's Embedded data question can save them with the response. Read more about saving embedded data using the study editor.


See the event name on a response

Want to know which app event showed the intercept? Add an Embedded data question to the study:

  1. In the study editor, head to the Embedded data tab and click Add embedded data. You can also use one you already have.
  2. Enter ethnio_event  in Parameter to pass via URL. If that URL parameter is already in use, click Add URL parameter first.
  3. To save an event property too, click Add URL parameter and enter the property's key, such as plan .

The responses page then shows the event name, such as checkout_done , on each response that came from a trigger. It works whether your app registers the study or an activation code.

An Embedded data question with the URL parameters ethnio_event and plan


When the SDK ignores an app event

App events don't wait in line. If one of these is true, the SDK drops the app event and nothing shows:

  • The phone doesn't have any triggers yet. For example, the app hasn't registered a study or an activation code since it started, or Ethnio's first answer hasn't arrived.
  • An app intercept is already on screen or still loading. The SDK never closes one for an app event.
  • A trigger already showed an app intercept. That turns off all triggers until the app registers again. Read Why triggers stop after an app intercept shows.
  • The app isn't in the foreground.
  • A trigger of your activation code showed an app intercept recently, and the code's minimum time between intercepts hasn't passed yet. It only applies to the code's triggers.
  • For an activation code's triggers, the study's Display interval or Cookie setting leaves out this app user.
  • The activation code's triggers are out of date. This happens when a trigger's app intercept starts to load and Ethnio answers that the study is turned off or that the triggers changed. The SDK then fetches the code's triggers again. Until they arrive, only the triggers of a study your app registered can match.
  • Your app hasn't set Ethnio.sdkKey  yet. On Android, it also needs to call Ethnio.initialize(context)  before anything else.

To see what happened, ask your developer to set Ethnio.logLevel  to debug. The console then shows one line for each app event, for example app event checkout_done: no trigger matches .

Still need help? Reach out to help@ethn.io and we're happy to help.


Still need help? Contact Us Contact Us