App intercept activation codes
An app intercept activation code lets your app use the triggers of several studies at once. Your app registers the code one time, and the phone gets the app intercept triggers of every study that uses it. After that, you can turn studies on and off or add triggers without releasing a new version of your app.
A code looks like k3x9q-app : five lowercase letters and digits, followed by -app .
Activation codes vs. Global JS codes
The names sound alike, but they're two different things. Each one has its own window, and each window only lists its own codes.
|
|
App intercept activation code | Global JS activation code |
|---|---|---|
| For | App intercepts with the Ethnio SDK | Web intercepts on your website |
| Looks like | k3x9q-app |
abcde-gl |
| Where it goes | One line in your app's code | A script tag on your site, usually through a tag manager |
| What it brings | The app intercept triggers of its studies | The web intercept that matches the page's URL |
| Managed in | Manage App Intercept Activation Codes | Manage Global JS |
A study published as Both intercept and study link can use both kinds of code. Its web intercept uses a Global JS code, and its app intercept uses an app intercept activation code. Read more about Global JS activation codes for Study editor.
💡 Do you need a code at all?
You only need a code if you want one line in your app to use the triggers of several studies. If your app registers a study with registerIntercept instead, that study's triggers work without a code. Not sure which one fits your app? Read App intercept triggers.
Create an activation code
- Open Manage App Intercept Activation Codes. You can get there in two ways:
- On the study's Publish page, open the app intercept's Triggers tab and click Manage activation codes.
- Head to All studies, click the gear icon at the top right, and select Manage app activation codes. Collaborators don't see this option.
- Click Add App Intercept Activation Code. On plans other than Enterprise, you can have one code. After that, the button opens an upgrade window.
- Give the code a name in Custom label for this activation code, like "iOS production" or "Android beta".
- In Minimum time between intercepts, pick how long a phone waits before it shows another intercept from this code. It's 1 hour by default.
- Click Save & close. The new code won't work until you save it.
Your code shows in Activation code (not editable). Under Register this code in your app, you'll find a Swift line and a Kotlin line with your code already filled in. Click Copy next to each line and send them to your developer.
Only account owners and admins can create, edit, or delete activation codes. Everyone else on your team can see them. Anyone who can edit a study can pick a code for it.
Register the activation code in your app
Your developer adds one line to your app, after the SDK key is set:
// iOS (Swift)
Task { await Ethnio.registerAppActivationCode("k3x9q-app") }
// Android (Kotlin)
lifecycleScope.launch { Ethnio.registerAppActivationCode("k3x9q-app") }
Replace k3x9q-app with your own code. Then your app records its app events with recordEvent . Read more about App events using the app intercept SDK.
Your app can also send embedded data and a language with the code. For example, in Swift: await Ethnio.registerAppActivationCode("k3x9q-app", embeddedData: ["plan": "pro"])
The triggers' conditions check this embedded data, and it also fills the study's Embedded data questions. The call returns true once the phone has the code's triggers.
Keep in mind that your app can only register one activation code at a time. If it registers a different code, the first code's triggers stop right away.
The phone saves the code's latest triggers. That way they work as soon as your app registers the code after a restart, even without a connection.
You can use the same code in your iOS app and your Android app. For test builds, use a separate test code with a copy of the study. That way your tests never show an intercept to your real app users.
Connect a study to a code
- Open the study, head to Publish and open the app intercept's Triggers tab.
- Under Register the activation code, pick your code in App intercept activation code.
Each study can use one activation code, and one code can serve many studies. To disconnect a study, pick No code. For a study published as both, you do this on the Triggers tab of its app intercept.
Once a study has a code, the tab shows the code's name and the code itself. It also shows the code's traffic, its minimum time between intercepts, and the lines to copy. A Live badge shows when the code is in use.
A few things to know about which triggers reach the phone:
- A study only counts if it's turned on, built in the study editor, and published as an app intercept or as both.
- One code sends up to 25 triggers from up to 10 studies. If its studies have more, the oldest triggers win. The newer ones won't reach the phone through this code.
- When you copy a study, the copy keeps its triggers but has no activation code. Pick a code on the copy's Triggers tab.
Minimum time between intercepts
This setting keeps the same app user from seeing one intercept after another. Once a trigger of a code shows an intercept, that phone won't show another intercept from the same code's triggers until the minimum time has passed. That includes the same study.
- You can pick 1, 2, 3, or 12 hours, or 1, 2, 3, or 30 days. The default is 1 hour.
- Each code has its own minimum time. The phone keeps counting it, even after the app or the phone restarts.
- The minimum time doesn't apply to intercepts that your app shows with
display(studyId:). It doesn't apply to the triggers of a study that your app registered either. Neither kind makes the next intercept wait. - A preview doesn't make the next intercept wait.
Live badge and traffic
The Live badge shows next to a code once your apps have fetched its triggers more than 25 times today. You'll see it in the window and on the study's Triggers tab.
The Triggers tab also shows Traffic today and Traffic in the last 30 days for the code. Both count how often your apps fetched the code's triggers, not how many intercepts appeared. The badge and the numbers update about every 5 minutes.
⚠️ Each fetch counts as a pageview
Each time an app fetches a code's triggers, it counts as one pageview on your plan, just like a page with Ethnio JavaScript. The SDK fetches when the app starts and registers the code. It also fetches when the app comes back to the foreground more than 15 minutes after the phone last got the triggers. And it fetches the first time the app registers the code again after a trigger showed an intercept. Registering the same code again within those 15 minutes doesn't fetch, so your app can do it on every screen. Read more about How Pageview Counting Works.
Edit or delete a code
- You can change the name and the minimum time between intercepts at any time. The code itself can't change.
- To delete a code, click the delete icon next to it in the window. It's deleted right away, even if you don't click Save & close. This cannot be undone.
- Ethnio never gives a new code the value of a deleted one.
- When you delete a code, its studies are left without a code, but they keep their triggers. Apps that still use the deleted code get no triggers on their next fetch, and the SDK clears the triggers it saved for that code.
- To move a study to another code, pick the other code on the study's Triggers tab.
Troubleshooting
The code doesn't show the Live badge.
The badge needs more than 25 fetches today, and it can take about 5 minutes to show up. Check that the app that registers the code is released and in use today. Also check that the app sets your organization's SDK key before it registers the code. With another organization's key, the app gets no triggers, and its fetches don't count.
A study's triggers never reach the phone.
Make sure the study is turned on, uses this code, and is published as an app intercept. If the code serves lots of studies, this study's triggers may be past the limit of 25 triggers from 10 studies.
I can't create a code.
Only account owners and admins can create codes. Ask one of them to create it, or to make you an admin. If the button opens an upgrade window, your organization already has a code. More codes need the Enterprise plan.
Still need help? Reach out to help@ethn.io and we're happy to help.