Android quickstart
Count events from an Android app through your own server and the server API, with a consent question, as Insights Orbit has no Android SDK yet.
Tutorial8 min read
Insights Orbit has no SDK for Android yet. You can still count what people do in your app: the app tells your own server, and your server sends the event to the server API with an API key. In about 20 minutes you build a Jetpack Compose app for Northwilds that asks before counting, then sends App opened and Brochure requested.
The API key never goes into the app. Anyone can unpack an app and read what is inside it, and a key that sends events would let them send anything.
Tested with: Android Gradle plugin 9.5.1, Gradle 9.8.2, Kotlin 2.4.21, Compose BOM 2026.09.00, JDK 17, an Android 16 (API 36) emulator, and Node.js 24 for the server.
Before you start
You need:
- A site in Insights Orbit for the app. Events from your server carry no page address, so the site's addresses don't matter here. See Add your first site.
- The site key, from the site's Install screen.
- An API key that sends events. An Admin makes it under API keys with Send events ticked. It starts with
ins_live_and is a secret. See API keys. - A server you control, with Node.js 20 or later for this guide's example. Any language works: it is one
POSTrequest. - Android Studio, or the Android SDK and JDK 17 or later.
What you get, and what you don't
Server events count in Events, goals, revenue and the monthly events, like events from a website. They have no visitor and no visit, so the app doesn't change the numbers of visitors, visits or bounce rate, and there are no countries or devices: their device is server. Each event counts as a goal completion of its own.
1Add an endpoint to your server
The app sends { id, name, properties } to your server. The server checks the name against a list, adds the site key and passes it on with the API key. This is the same endpoint as in the iOS quickstart, so one serves both apps:
import { createServer } from 'node:http'const INSIGHTS = process.env.INSIGHTS_URL ?? 'https://api.bifrostorbit.com/insights/v1'const ALLOWED = new Set(['App opened', 'Brochure requested', 'Trip booked'])createServer(async (request, response) => { if (request.method !== 'POST' || request.url !== '/analytics') return response.writeHead(404).end() let body = '' for await (const chunk of request) { body += chunk if (body.length > 10_000) return response.writeHead(413).end() } let event try { event = JSON.parse(body) } catch { return response.writeHead(400).end() } if (!ALLOWED.has(event?.name)) return response.writeHead(400).end() const answer = await fetch(`${INSIGHTS}/server/events`, { method: 'POST', headers: { authorization: `Bearer ${process.env.INSIGHTS_API_KEY}`, 'content-type': 'application/json' }, body: JSON.stringify({ site: process.env.INSIGHTS_SITE, events: [{ id: event.id, name: event.name, properties: event.properties }] }), }).catch(() => null) if (!answer?.ok) console.warn('Insights Orbit did not take the event', answer?.status, await answer?.text()) response.writeHead(answer?.ok ? 202 : 502).end()}).listen(process.env.PORT ?? 3000)Start it with the site key and the API key:
INSIGHTS_SITE=SITE_KEY INSIGHTS_API_KEY=ins_live_… node analytics-relay.mjs- The list of names stops anyone who finds the endpoint from filling your reports with made-up events. Add each event the app sends.
idcomes from the app. The server API counts an id it has already seen in the last eight days once, so the app or your server can safely send again.- If your server already has an API, add the same route there instead, as the Laravel quickstart does in PHP.
Check it: curl -X POST localhost:3000/analytics -d '{"id":"check-1","name":"App opened"}' answers 202, and a name that isn't on the list answers 400.
2Create the project
In Android Studio, select New Project › Empty Activity and use:
- Name:
Northwilds - Package name:
com.northwilds.app - Minimum SDK: API 24
- Build configuration language: Kotlin DSL
Replace the generated Gradle files and manifest with the ones below. You can delete the generated ui/theme folder, as the app uses the default Material 3 theme.
// settings.gradle.ktspluginManagement { repositories { google() mavenCentral() gradlePluginPortal() }}dependencyResolutionManagement { repositories { google() mavenCentral() }}rootProject.name = "Northwilds"include(":app")// build.gradle.ktsplugins { id("com.android.application") version "9.5.1" apply false id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false}# gradle.propertiesorg.gradle.jvmargs=-Xmx2gandroid.useAndroidX=true// app/build.gradle.ktsimport java.util.Propertiesplugins { id("com.android.application") id("org.jetbrains.kotlin.plugin.compose")}val local = Properties().apply { rootProject.file("local.properties").takeIf { it.exists() }?.inputStream()?.use(::load)}android { namespace = "com.northwilds.app" compileSdk = 37 defaultConfig { applicationId = "com.northwilds.app" minSdk = 24 targetSdk = 36 versionCode = 1 versionName = "1.0" buildConfigField("String", "ANALYTICS_URL", "\"${local.getProperty("analytics.url") ?: "https://northwilds.com/analytics"}\"") } buildFeatures { compose = true buildConfig = true }}dependencies { implementation(platform("androidx.compose:compose-bom:2026.09.00")) implementation("androidx.compose.material3:material3") implementation("androidx.activity:activity-compose:1.13.0")}<!-- app/src/main/AndroidManifest.xml --><?xml version="1.0" encoding="utf-8"?><manifest xmlns:android="http://schemas.android.com/apk/res/android"> <uses-permission android:name="android.permission.INTERNET" /> <application android:label="Northwilds" android:theme="@android:style/Theme.Material.Light.NoActionBar"> <activity android:name=".MainActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application></manifest>3Point the app at your server
ANALYTICS_URL is your server's https address, https://northwilds.com/analytics in this guide. While you build, point it at the server on your computer in local.properties, which stays out of source control. The emulator reaches your computer at 10.0.2.2:
# local.propertiesanalytics.url=http://10.0.2.2:3000/analyticsAndroid refuses plain http by default. Allow it in debug builds only, with a second manifest that release builds leave out:
<!-- app/src/debug/AndroidManifest.xml --><?xml version="1.0" encoding="utf-8"?><manifest xmlns:android="http://schemas.android.com/apk/res/android"> <application android:usesCleartextTraffic="true" /></manifest>4Add the analytics client
// app/src/main/java/com/northwilds/app/Analytics.ktpackage com.northwilds.appimport android.content.Contextimport org.json.JSONObjectimport java.net.HttpURLConnectionimport java.net.URLimport java.util.UUIDimport java.util.concurrent.Executorsobject Analytics { private val worker = Executors.newSingleThreadExecutor() fun allowed(context: Context): Boolean? = prefs(context).takeIf { it.contains("allowed") }?.getBoolean("allowed", false) fun setAllowed(context: Context, allowed: Boolean) { prefs(context).edit().putBoolean("allowed", allowed).apply() } fun track(context: Context, name: String, properties: Map<String, String> = emptyMap()) { if (allowed(context) != true) return val body = JSONObject() .put("id", UUID.randomUUID().toString()) .put("name", name) .put("properties", JSONObject(properties)) .toString() worker.execute { runCatching { val connection = URL(BuildConfig.ANALYTICS_URL).openConnection() as HttpURLConnection connection.requestMethod = "POST" connection.connectTimeout = 5_000 connection.readTimeout = 5_000 connection.doOutput = true connection.setRequestProperty("Content-Type", "application/json") connection.outputStream.use { it.write(body.toByteArray()) } connection.responseCode connection.disconnect() } } } private fun prefs(context: Context) = context.getSharedPreferences("analytics", Context.MODE_PRIVATE)}- No extra libraries:
HttpURLConnectionandorg.jsoncome with Android. - Nothing is sent until the person agrees (step 5):
allowedisnullbefore they answer, andtrackonly sends when it istrue. - Requests run on a background thread and errors are ignored, so analytics never slows the app down or stops it.
- Properties are text here. Never send names, email addresses or other personal data. Send your own events has the limits.
5Ask before counting
Insights Orbit reads nothing from the phone: the only data is what your app sends. Whether you ask first is your decision with your adviser; this app asks once and remembers the answer.
// app/src/main/java/com/northwilds/app/MainActivity.ktpackage com.northwilds.appimport android.os.Bundleimport androidx.activity.ComponentActivityimport androidx.activity.compose.setContentimport androidx.compose.foundation.layout.Arrangementimport androidx.compose.foundation.layout.Columnimport androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.foundation.layout.paddingimport androidx.compose.material3.AlertDialogimport androidx.compose.material3.Buttonimport androidx.compose.material3.MaterialThemeimport androidx.compose.material3.Textimport androidx.compose.material3.TextButtonimport androidx.compose.runtime.LaunchedEffectimport androidx.compose.runtime.getValueimport androidx.compose.runtime.mutableStateOfimport androidx.compose.runtime.rememberimport androidx.compose.runtime.setValueimport androidx.compose.ui.Modifierimport androidx.compose.ui.platform.LocalContextimport androidx.compose.ui.unit.dpclass MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { MaterialTheme { TripScreen() } } }}@androidx.compose.runtime.Composablefun TripScreen() { val context = LocalContext.current var asking by remember { mutableStateOf(Analytics.allowed(context) == null) } var sent by remember { mutableStateOf(false) } LaunchedEffect(Unit) { Analytics.track(context, "App opened") } Column(Modifier.fillMaxSize().padding(24.dp), verticalArrangement = Arrangement.spacedBy(16.dp)) { Text("Lofoten ski touring week", style = MaterialTheme.typography.headlineSmall) Text("Seven days of ski touring above the fjords, from €2,450.") Button( enabled = !sent, onClick = { Analytics.track(context, "Brochure requested", mapOf("trip" to "lofoten-ski-touring")) sent = true }, ) { Text(if (sent) "On its way" else "Send me the brochure") } } if (asking) { AlertDialog( onDismissRequest = {}, title = { Text("May we count how you use the app?") }, text = { Text("We keep no personal data.") }, confirmButton = { TextButton(onClick = { Analytics.setAllowed(context, true) asking = false Analytics.track(context, "App opened") }) { Text("Yes") } }, dismissButton = { TextButton(onClick = { Analytics.setAllowed(context, false) asking = false }) { Text("No thanks") } }, ) }}- Yes stores the answer and sends App opened at once. Every later launch sends it too.
- No thanks stores the answer, and
tracksends nothing from then on. Give people a switch in your settings screen that callsAnalytics.setAllowed, so they can change their mind.
6Check that events arrive
Run the app on the emulator, select Yes, then Send me the brochure.
- In Insights Orbit: Events lists App opened and Brochure requested within a few seconds. Open one to see its details, such as
trip. - On your server: a refused event prints
Insights Orbit did not take the eventwith the status, such as401for a wrong key. - From the API, on the Growth plan, with a key that reads events:
curl "https://api.bifrostorbit.com/insights/v1/events?site=SITE_KEY&name=Brochure%20requested" \ -H "Authorization: Bearer ins_live_…"The event comes back with "device": "server" and its properties.
To try No thanks, clear the app's storage under Settings › Apps › Northwilds › Storage and open it again: the question comes back, and after No thanks nothing reaches your server.
Next steps
- Send events from a server: every field, including
revenue,timestampanduserId. - Set up goals: count Brochure requested as success.
- iOS quickstart: the same for iPhone.
- Read raw events: every event for your own data tools.
Was this page helpful?