# Auto-Update SDK | Sentry for Android

This feature is available only if you're in the [Early Adopter program](https://docs.sentry.io/organization/early-adopter-features.md). Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.

The Auto-Update SDK is designed for **internal builds only** and should never be used in production builds distributed through the Google Play Store or other public app stores.

The Sentry Auto-Update SDK enables your internal Android builds to automatically check for and install newer versions distributed through Sentry's Build Distribution. This is particularly useful for distributing nightly, alpha, or beta builds to your internal teams.

## [Pre-requisites](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#pre-requisites)

Make sure your Sentry Java version is at least 8.27.0 and you have the [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md) configured for your project.

You'll also need an [internal integration token](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#create-an-integration-token) with Build Distribution permissions.

## [Create an Integration Token](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#create-an-integration-token)

To use the Auto-Update SDK, you need to create an internal integration token with the appropriate permissions:

1. Navigate to **Settings > Custom Integrations** in your Sentry organization

2. Click **Create New Integration**

3. Select **Internal Integration** and click **Next**

4. Give your integration a name (e.g., "Build Distribution")

5. Under **Permissions**, select **Read** next to the **Distribution** scope.

6. Click **Save Changes**

7. Scroll down to the Tokens section and click **New Token**

8. Save the generated token, you'll need it to integrate the SDK

## [Installation](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#installation)

### [Configure the Gradle Plugin](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#configure-the-gradle-plugin)

Add the auto-update SDK configuration to your app's `build.gradle` or `build.gradle.kts` file:

`build.gradle.kts`

```kotlin
sentry {
  distribution {
    // Enable build distribution uploads
    enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent

    // Specify which build variants should include the auto-update SDK
    // These must be variants where the Sentry SDK is enabled (not in ignoredVariants)
    updateSdkVariants.set(setOf("nightly", "beta"))

    // Auth token (defaults to SENTRY_DISTRIBUTION_AUTH_TOKEN env var)
    authToken.set(System.getenv("SENTRY_DISTRIBUTION_AUTH_TOKEN"))
  }
}
```

This expects to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`, copy the token you generated in the preceding step to this variable in your CI environment.

### [Configuration Options](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#configuration-options)

| Option              | Description                                                              | Default                                  |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
| `enabled`           | Controls whether variants are uploaded for distribution                  | `false`                                  |
| `updateSdkVariants` | Set of Android build variants that should have the auto-update SDK added | `[]` (empty set)                         |
| `authToken`         | Integration token for build distribution operations                      | `SENTRY_DISTRIBUTION_AUTH_TOKEN` env var |

The `updateSdkVariants` configuration controls which variants get the auto-update SDK installed. The `enabled` option controls whether all builds are uploaded. You can have builds uploaded without the auto-update SDK, or vice versa. The enabled option when set to true will upload all variants that are not ignored via the Sentry `ignoreVariants`, `ignoredBuildTypes`, or `ignoredFlavors` options.

### [Auto-Installation](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#auto-installation)

When you add a variant to `updateSdkVariants`, the Sentry Gradle Plugin automatically:

1. Adds the `sentry-android-distribution` dependency to that variant
2. Embeds the distribution auth token securely in the app

No additional dependency declarations are needed.

## [Usage](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#usage)

### [Check for Updates](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#check-for-updates)

Once configured, you can check for updates in your application code. This is typically done at app startup or when the user navigates to a settings screen.

```kotlin
import io.sentry.Sentry
import io.sentry.UpdateStatus
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

// Check for updates using coroutines
suspend fun checkForUpdate() {
    val status = withContext(Dispatchers.IO) {
        Sentry.distribution().checkForUpdateBlocking()
    }

    when (status) {
        is UpdateStatus.NewRelease -> {
            Sentry.distribution().downloadUpdate(status.info)
        }
        is UpdateStatus.UpToDate -> {
            // Current version is the latest
            Log.i("Sentry Distribution", "App is up to date")
        }
        is UpdateStatus.UpdateError -> {
            // An error occurred while checking for updates
            Log.i("Sentry Distribution", "Update check failed: ${status.message}")
        }
        is UpdateStatus.NoNetwork -> {
            // No network connection available
            Log.i("Sentry Distribution", "No network connection: ${status.message}")
        }
    }
}
```

## [Security Considerations](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#security-considerations)

* **Internal Use Only**: Never ship the auto-update SDK in production builds destined for public app stores
* **Token Security**: The distribution token is embedded in the app and can be extracted by reverse engineering. Use tokens with only the distribution read permission which is the minimum required permission for the auto-update SDK.

## [Best Practices](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#best-practices)

1. **Variant Separation**: Create dedicated build variants for internal distribution:

   ```groovy
   android {
       buildTypes {
           debug { /* ... */ }
           nightly { /* ... */ }
           beta { /* ... */ }
           release { /* ... */ }
       }
   }

   sentry {
       distribution {
           // Only enable for non-production variants
           updateSdkVariants = ["nightly", "beta"]
       }
   }
   ```

2. **Update Timing**: Check for updates at appropriate times:

   * On app launch automatically
   * In a settings/about screen (user-initiated)