App intercept triggers

App intercept triggers let you show your app intercept at just the right moment. For example, you can show it right after someone finishes checkout, or the first time they try a new feature.

Here's how it works: your app tells our SDK when something happens in the app, and we call that an app event.

When an app event matches one of your study's triggers, the SDK shows the study's app intercept. Triggers only work in studies built in the study editor.

What's in a trigger

Every app intercept trigger has an event name, and an optional set of conditions.

• Event name is the name of an app event that your app records, like checkout_done . It has to match exactly, including upper and lower case.
• Conditions are optional. Each one has an Event property and one or more Values, like plan  is pro  or team . A condition passes when the app event has that property and its value matches one of them exactly, including case. If the app event doesn't have the property, the condition fails.

A trigger matches when the event name is the same and every condition passes.

Add a trigger

1. Open your study and head to Publish.
2. Choose App Intercept, or Both intercept and study link.
3. On the Setup tab, under How your app shows the intercept, pick SDK - iOS/Android.
4. Open the Triggers tab of your app intercept.
5. Click Add trigger.
6. Type the Event name. You'll see suggestions from the app intercept triggers in all the studies you can open.
7. To add a condition, click Add condition. Then type the Event property and add its Values.
8. Click Save.

Each saved trigger shows its event name, its conditions, and two lines of code to copy, one for Swift and one for Kotlin. These are the recordEvent  lines that make the trigger match, so you can hand them straight to your developer.

Two ways your app can use triggers

The top of the Triggers tab shows two ways your app can use its triggers. Your developer can pick one or use both.

Register the study

Your app registers the study when it starts, or once it knows who the app user is:

// iOS (Swift)
Task { await Ethnio.registerIntercept(studyId: 12345) }

// Android (Kotlin)
lifecycleScope.launch { Ethnio.registerIntercept(studyId = 12345) }

You'll find these lines on the Triggers tab with your study's ID already filled in. When your app registers the study, Ethnio checks if the study can show to this app user. If it can, Ethnio sends the study's triggers to the phone. That check covers the study's targeting rules, Display interval, and Cookie setting. So when a matching app event comes in, the SDK doesn't need to check with Ethnio again. The app intercept shows after the study's Delay on the Options tab.

• The phone keeps these triggers in memory only. Your app needs to register the study again every time it starts.
• The SDK checks with Ethnio again when your app registers the study again. It also checks when the app comes back to the foreground more than 15 minutes after the last check.
• Conditions read the embedded data that your app passes to registerIntercept , plus the event properties. If both have the same key, the event property wins.
• Targeting rules only read the embedded data of registerIntercept . They never read an event property.

Register the activation code

This way works for several studies at once. Your app registers an app intercept activation code once. Your app can then use the triggers of the studies connected to that code:

// iOS (Swift)
Task { await Ethnio.registerAppActivationCode("k3x9q-app") }

// Android (Kotlin)
lifecycleScope.launch { Ethnio.registerAppActivationCode("k3x9q-app") }

Your app can also pass embedded data and a language. For example, use await Ethnio.registerAppActivationCode("k3x9q-app", embeddedData: ["plan": "pro"])  in Swift or Ethnio.registerAppActivationCode("k3x9q-app", embeddedData = mapOf("plan" to "pro"))  in Kotlin. Conditions read this embedded data, and it also goes to the study's Embedded data questions. The call returns true once the phone has the code's triggers.

An app registers one activation code at a time. If it registers a different code, the first code's triggers stop right away. The phone keeps the code's last triggers, so they work as soon as the app starts again, even before the new fetch comes back.

To connect your study, head to the Triggers tab. Under Register the activation code, pick your code in App intercept activation code. The tab then shows the lines above with your code filled in.

To create or edit codes, click Manage activation codes next to the dropdown. Only account owners and admins can create or edit codes.

You'll need edit access to the study to pick its code. Read more about app intercept activation codes.

• An app intercept from the code's triggers ignores the study's targeting rules. The event name and the conditions are its targeting.
• The phone still checks the study's Display interval and Cookie setting.
• After a trigger of the code shows an app intercept, the phone waits for the code's Minimum time between intercepts before another trigger of that code can show one. The default is 1 hour.
• Your app can only use triggers from studies that are turned on and published as an app intercept (or both).
• One code holds at most 25 triggers from at most 10 studies. If its studies have more, the oldest triggers win.
• Each fetch of the code's triggers counts as one pageview on your plan. Your app can still register the code on every screen. If your app registers it again less than 15 minutes after the phone last got the triggers, the SDK doesn't send a new request.

If your study is published as Both intercept and study link, you pick the activation code on the Triggers tab of its app intercept. The web intercept keeps its own Global JS code.

Which trigger wins

• One app event shows at most one app intercept.
• A trigger of a study that your app registered always wins over the triggers of an activation code.
• If two triggers match the same app event, the oldest one wins.
• Your app can still show the app intercept itself with display(studyId:) , without any trigger. If you want triggers to decide when it shows, don't call display(studyId:)  for this study.

Why triggers stop after an app intercept shows

When a trigger shows an app intercept, the SDK turns off every trigger on that phone. That includes every study, whether your app registered the study or an activation code. This keeps an app user from getting a second study on their very next tap.

A study's triggers come back only when your app registers that study again. A code's triggers come back only when your app registers the code again, for example the next time the app starts. Coming back to the foreground after 15 minutes doesn't bring them back.

Previews and app intercepts that your app shows with display(studyId:)  don't turn off any triggers.

Limits

• A study can have up to 50 app intercept triggers.
• An event name can be up to 100 characters. It can't start or end with a space, and it can't contain a tab. It also can't start with ethnio: . We save that for Ethnio's own events.
• A trigger can have up to 10 conditions, and each condition up to 50 values.
• An event property can be up to 100 characters, with no spaces or special characters. You can't use the names Ethnio uses itself, like preview  or anything that starts with ethnio_ .
• A value can be up to 255 characters. It can't contain " , & , < , > , or a tab.

Test on a phone

You can test a study's triggers before any participant sees them. Both tests work even while the study is turned off. A preview doesn't count as a view, doesn't set a cookie, and doesn't make the next intercept wait.

Test that the study is connected to the code

1. Ask your developer for a test build that registers the activation code.
2. In that build, record the app event ethnio:preview:<study id>  from a debug menu. For example, record ethnio:preview:66 .
3. The app intercept shows as a preview.

Keep in mind the preview event only works when the study uses that code and has at least one app intercept trigger. It skips the event name and the conditions.

Test your event names and conditions

1. In a test build, register the study with preview: true .
2. Record your app events with their event properties.
3. When a trigger matches, the app intercept shows as a preview.

Want to test a code's triggers with real matches? Use a test code with a copy of the study that's turned on. A copy keeps the study's triggers but not its activation code, so pick the test code on the copy's Triggers tab.

Troubleshooting

The app intercept never shows after the app event.

• Check the event name and the property values letter by letter, including upper and lower case.
• Check that your app registered the study or the activation code after it started. App events recorded before that are lost.
• An earlier trigger may have shown an app intercept. That turns off all triggers until the app registers again. Read Why triggers stop after an app intercept shows.
• For a code's triggers, check the code's Minimum time between intercepts, the Display interval, and the Cookie setting.
• Ask your developer to set Ethnio.logLevel  to debug. The console then says what the SDK did with each app event, for example app event checkout_done: no trigger matches .

The Triggers tab is grayed out.

Your study uses a WebView. Pick SDK - iOS/Android on the Setup tab.

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

Related articles

• App events using the app intercept SDK
• App intercept activation codes
• Web intercept triggers
• Ethnio iOS SDK
• Ethnio Android SDK
• Embedded data targeting for intercepts