# Android (Kotlin)

Track screens, goals and signed-in users in native Android apps with the ProductLense Kotlin library, attributed to the Play Store campaign behind each install.

The ProductLense Android library is plain Kotlin with no required dependencies. It sends screen views, goals and `identify` from your app to ProductLense, needs no device identifiers, and reports app traffic next to your website: the Hostname breakdown shows your application id beside your domain.

## 1. Add your app ID

In ProductLense, open **Settings → General → App IDs** and add your application id, for example `com.example.app`. Events from any other app id are rejected.

## 2. Install

```kotlin title="app/build.gradle.kts"
dependencies {
    implementation("app.productlense:productlense-android:0.1.0")
    // optional: Play Store install referrer attribution
    implementation("com.android.installreferrer:installreferrer:2.2")
}
```

Android 5.0 (API 21) or later. The library declares the `INTERNET` permission.

## 3. Start ProductLense and track screens

```kotlin title="ExampleApp.kt" {1,5}
import app.productlense.analytics.android.ProductLense

class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        ProductLense.init(this, siteId = "YOUR_SITE_ID")
    }
}

// in each screen
ProductLense.screen("Settings")
```

`siteId` is on **Settings → Snippet**; the app id defaults to your application id. Call `ProductLense.screen` in each activity's `onResume`, or from a Navigation `OnDestinationChangedListener` (`ProductLense.screen(destination.label.toString())`). In Compose, call it in a `LaunchedEffect` keyed on the route.

ProductLense keeps the install id, the opt-out choice and unsent events in `SharedPreferences`, sends them every 10 seconds on a background thread, and sends what is left when the app goes to the background.

## 4. Goals and users

```kotlin
ProductLense.track("signup", mapOf("plan" to "pro"))
ProductLense.identify(user.id, name = user.name, email = user.email)
```

Call `identify` after sign-in with the user id your billing provider stores on the customer, so app visits, web visits and payments join up. See [how payments are attributed](/docs/revenue/attribution).

## In-app purchases

Connect [RevenueCat](/docs/revenue/revenuecat) and pass the install id once after configuring both SDKs:

```kotlin
Purchases.sharedInstance.setAttributes(ProductLense.revenueCatAttributes())
```

Each purchase then lands on the channel that brought the install.

## Attribution

- **Play Store**: with the `installreferrer` library on the classpath, ProductLense reads the install referrer once, in the background, on first launch, and puts its `utm_*` tags on the first screen.
- **Deep links**: the intent that launches an activity is read automatically. Pass links that arrive later, in `onNewIntent`, to `ProductLense.openURL(intent.dataString)`. Only `utm_*`, `ref`, `via`, `source` and click ids leave the device.

## Privacy

- The library creates a random install id on first launch. It is not the advertising id (AAID). ProductLense stores only a hash of it.
- `ProductLense.optOut()` stops collection, deletes unsent events and forgets the install id; `ProductLense.optIn()` resumes with a new one.
- Google Play data safety: **App activity → App interactions**, collected for **Analytics**, not shared.

## Verify your installation

1. Run the app on a device or emulator and open a few screens.
2. Open the Live page in the ProductLense dashboard. Your device appears within a few seconds.
3. Open **Events**: each screen is a `pageview` row with your application id as the hostname and `Android app` as the browser.
4. Pass `debug = true` to `ProductLense.init` to log dropped events and failed sends (tag `ProductLense`).

If nothing appears, check the app id in Settings and follow [Verify your installation](/docs/install/verify).