Installation guides

Android & Kotlin

On this page

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

  1. 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.

  2. 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")
    }
  3. Configure it once at launch

    MyApp.kt
    import 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_…")
        }
    }
  4. 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) }
    }
  5. 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

CallNotes
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.

example
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 is configure(…, consent = true).
  • The library adds the INTERNET and ACCESS_NETWORK_STATE permissions 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.