> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trueorigin.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Android SDK

> Add TrueOrigin to a native Android app from Maven Central.

Requirements: Android 7.0 or later (minSdk 24), compileSdk 30 or later, Kotlin 1.9 or
later. For React Native and Expo, use [`@trueorigin/react-native`](/sdk/react-native)
instead.

## Install

The SDK is on Maven Central as `dev.trueorigin:trueorigin-android`. In your app module's
`build.gradle.kts`:

```kotlin theme={null}
dependencies {
    implementation("dev.trueorigin:trueorigin-android:0.1.1")
}
```

`mavenCentral()` and `google()` must be among your repositories, as in every new Android
project: the SDK brings Google's Install Referrer library and `kotlinx-coroutines-core`
with it.

<Accordion title="Without Maven Central">
  Every release is also on
  [GitHub](https://github.com/trueorigin-dev/trueorigin-android/releases/latest) as
  `trueorigin.aar` with its SHA-256. Put the AAR in your module's `libs/` folder and
  declare the two libraries yourself:

  ```kotlin theme={null}
  dependencies {
      implementation(files("libs/trueorigin.aar"))
      implementation("com.android.installreferrer:installreferrer:2.2")
      implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
  }
  ```
</Accordion>

## Configure

Your SDK key is shown when you create the app, and can be rotated in the dashboard under
**Settings → SDK key**. It is a public client key: it ships inside your app.

```kotlin theme={null}
import dev.trueorigin.TrueOrigin

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        TrueOrigin.configure(this, apiKey = "to_…")
    }
}
```

Only the first call counts. On the first launch after install the SDK reads the install
referrer from Google Play, reports the install, then waits for the result. If the device
is offline, it retries with exponential backoff for up to six hours, across launches.

<Warning>
  Your app's **Android URL** in the dashboard must be its Google Play URL. Google Play
  passes the tap on to your app in the install referrer; an install without it is
  unmatched.
</Warning>

## Read the attribution

```kotlin theme={null}
import dev.trueorigin.Attribution

// in a coroutine
val attribution = TrueOrigin.attribution()
when (attribution.status) {
    Attribution.Status.MATCHED -> showOnboarding(attribution.campaign)
    Attribution.Status.UNMATCHED -> {}   // organic, or installed without a tracking link
    else -> {}                           // keep an else branch: new statuses may come
}
```

`TrueOrigin.onAttribution { attribution -> … }` is the callback form, called once on the
main thread. Both return right away on later launches: the result is stored.
`TrueOrigin.currentAttribution` reads the stored result without waiting, or `null` before
the first answer. The statuses are the same as on iOS: see
[Reading the attribution](/sdk/attribution#status).

### Options

```kotlin theme={null}
TrueOrigin.configure(
    this,
    apiKey = "to_…",
    options = TrueOrigin.Options(logging = BuildConfig.DEBUG),
)
```

| Option                | Default |                                                                                |
| --------------------- | ------- | ------------------------------------------------------------------------------ |
| `logging`             | `false` | Debug lines to Logcat, tag `TrueOrigin`. Errors are logged either way.         |
| `reportTimeoutMillis` | 6 hours | How long to keep retrying the first report before the status becomes `FAILED`. |

`TrueOrigin.installId` is the SDK's id for this install. It stays the same until the app
is uninstalled; a reinstall gets a new one. It and `revenueCatAttributes()` throw before
`configure`.

## RevenueCat

After configuring both SDKs, attach the install identity before purchases, on every app
start and after each successful RevenueCat `logIn` or `logOut`:

```kotlin theme={null}
Purchases.sharedInstance.setAttributes(TrueOrigin.revenueCatAttributes())
```

More in [RevenueCat](/revenuecat).

## Privacy

The SDK does not read the advertising ID or `ANDROID_ID` and asks for no permission
beyond `INTERNET`; Google's Install Referrer library adds its own permission to bind to
Google Play. Its only identifier is a random install id in the app's no-backup storage,
removed with the app and never in a backup.

What your app declares in Google Play's Data safety form is your decision. What the SDK
sends is listed in our [privacy policy](https://trueorigin.dev/privacy).