# Android & Kotlin

> Track screens, events and signed-in users in native Android apps (Kotlin or Java), with an offline queue and consent.

Source: https://metricraven.com/docs/android-sdk  
Markdown: https://metricraven.com/docs/android-sdk.md  
Section: Installation guides

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**

   ```kotlin
   // 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**

   ```kotlin title="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**

   ```kotlin
   // 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**

   ```kotlin
   // 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

```kotlin
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](https://metricraven.com/docs/server-events), [server identify](https://metricraven.com/docs/identify-users), 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](https://metricraven.com/docs/search-console#ga4-realtime) to show app users on the live map without this library.
- React Native and Expo apps: use [@metricraven/react-native](https://metricraven.com/docs/react-native). iOS: [the Swift package](https://metricraven.com/docs/ios-sdk). Flutter: [the Flutter package](https://metricraven.com/docs/flutter).
