Auto-Update SDK

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

Make sure your Sentry Java version is at least 8.27.0 and you have the Sentry Android Gradle Plugin configured for your project.

You'll also need an internal integration token with Build Distribution permissions.

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

Configure the Gradle Plugin

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

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

These options control different things and can be used independently:

• enabled: When true, all non-ignored variants are uploaded to Build Distribution. The installGroups are applied to all uploaded variants.
• updateSdkVariants: Only these variants get the auto-update SDK installed and the distribution properties (auth token, install groups) embedded in the app. Variants listed here must not be in ignoredVariants.
• installGroups: Applied at upload time to all uploaded variants (controlled by enabled), and embedded in the app for variants in updateSdkVariants.

This means you can upload all variants for distribution without the auto-update SDK, or add the auto-update SDK to specific variants without uploading others.

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 and install groups in the app

No additional dependency declarations are needed.

Usage

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.

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}")
        }
    }
}

Install Groups

Install groups let you control which build the Auto-Update SDK returns when checking for updates. The API always returns a single build — the latest (by semver version, then build number) whose install groups overlap with the filter. See the Install Groups guide for full details on how filtering works.

Gradle Configuration

Add installGroups to the distribution block:

sentry {
  distribution {
    enabled = true
    updateSdkVariants.set(setOf("nightly", "beta"))
    installGroups.set(setOf("alpha", "staging"))
  }
}

The Gradle plugin tags the uploaded build with these groups and embeds them in the app so the SDK sends them explicitly when checking for updates. This is the recommended approach — it ensures deterministic filtering regardless of how many builds share the same version number.

Programmatic Override

You can override the groups the SDK sends at runtime to filter by different groups than what the build was uploaded with:

SentryAndroid.init(context) { options ->
    options.distribution.installGroups = setOf("beta", "internal")
}

This overrides the groups used for filtering update checks. It does not change the groups the build was tagged with on Sentry.

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

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

   Groovy

   Copied

   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)