Installation guides
Android & Kotlin
The metricraven-android library records screen views, goals and identified users from native Android apps, in Kotlin or Java. Each device shows on the realtime globe as a live visitor, under the person you identified it as. It has no dependencies and supports Android 6.0 and later.
Set up
Allow your app in Settings
In your site's Settings → General → Site, add your application ID under Mobile apps, for example
com.example.app. App events from IDs that aren't listed are rejected.Add the library
example// app/build.gradle.kts (Maven Central is in every new project's repositories) dependencies { implementation("com.metricraven:metricraven-android:0.2.0") }Configure it once at launch
MyApp.ktimport android.app.Application import com.metricraven.MetricRaven class MyApp : Application() { override fun onCreate() { super.onCreate() // The app ID defaults to your application ID; version, build and device are read automatically. MetricRaven.configure(this, siteId = "ana_pub_…") } }Track screens
example// Jetpack Compose @Composable fun SettingsScreen() { LaunchedEffect(Unit) { MetricRaven.screen("Settings") } // … } // Or with Navigation: every destination as its route navController.addOnDestinationChangedListener { _, destination, _ -> destination.route?.let { MetricRaven.screen(it) } }Send events and identify users
example// A goal, with up to 10 props. MetricRaven.track("signup", mapOf("plan" to "pro", "seats" to 3)) // After sign-in: the same user ID as your server events, server identify and payments. MetricRaven.identify(user.id, mapOf("name" to user.name, "email" to user.email)) // Verified instead: your server signs the user (signIdentity in @metricraven/node). MetricRaven.identifyWithToken(tokenFromYourServer) // On sign-out. MetricRaven.reset()
Verify it works
Open the app on a device or emulator. It appears as a live visitor in Traffic, with the name you identified it with. Screens are listed under Pages as paths like /Settings, and your app ID appears under Hostnames.
API
| Call | Notes |
|---|---|
| configure(context, siteId, appId, consent) | Once at launch, in Application.onCreate. appId defaults to the application ID. Returns false for an app ID that isn't an application ID. |
| screen(name, props) | A screen view. Names like "Settings" become the path /Settings. |
| track(name, props) | A goal. Names: letters, digits, _ : . -, up to 100 characters. Up to 10 props (strings, numbers, booleans). |
| identify(userId, traits) | Links this device to your user ID, with optional name, email, image (https) and up to 10 custom traits. Self-asserted, so a server identify takes precedence. |
| identifyWithToken(token) | Signed identify with a token your server signed. Verified, like server identify; get a fresh token at sign-in and launch. |
| reset() | On sign-out. Forgets identify state and, with consent, starts a new visitor ID. |
| setConsent(granted) | With consent a random visitor ID is kept on the device; without it the server derives a daily one. |
| openedFrom(uri) | utm_* campaign parameters from a deep link, attached to the next screen view. |
| flush() | Sends what is queued now. The library also flushes when the app comes to the foreground, goes to the background and when the network returns. |
| paywall(provider, …) | Paywall views, closes, cancels and taps from RevenueCat, Superwall, Adapty or your own paywall. See Paywall events (/docs/paywall-events). |
Each screen view carries the device's language and the screen size in dp (for example 411x914, like CSS pixels on the web). They show under Language and Screen size. Events and identify calls never carry them.
Campaigns from deep links
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
MetricRaven.openedFrom(intent?.data) // utm_* go on the next screen view
}One person across the app and your server
Use the same user ID everywhere: server events, server identify, payments and the app's identify. For a verified profile on the device, have your server sign a token for the signed-in user and call identifyWithToken: the live map then shows the device as that person, marked verified. An unsigned identify is a self-asserted claim and never borrows a verified profile.
Details
- Events wait in SharedPreferences while the device is offline (up to 500, for 7 days) and are delivered in order, with backoff on network errors, rate limits and server errors.
- Without consent nothing is stored on the device. Let people choose in your app and call
setConsent; consent at launch isconfigure(…, consent = true). - The library adds the
INTERNETandACCESS_NETWORK_STATEpermissions and needs no ProGuard or R8 rules. It reads no advertising ID or device identifier. - Using GA4 or Firebase instead? Connect it through Google Analytics 4 realtime to show app users on the live map without this library.
- React Native and Expo apps: use @metricraven/react-native. iOS: the Swift package. Flutter: the Flutter package.