Integrate an Android app with Logister.

Before you start

Create the project with the Android integration type.

What is supported

Choose each app-backed collector explicitly.

Install

Install org.logister:logister-android from Maven Central.

Privacy-safe automatic crash capture and durable pre-auth delivery are available in package version 0.3.0. Make sure your app resolves dependencies from Maven Central, then add the library to the Android app module.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("org.logister:logister-android:0.3.0")
}

• View the Maven Central package page for artifact metadata and available versions.
• Open the Maven repository path when you need to verify synced versions directly.
• Use GitHub for source, examples, releases, and issue tracking.

Configure

Create one client with app and release defaults.

Use the Kotlin facade with a LogisterTokenProvider. Do not compile a long-lived Logister project API key into the app; your backend should mint short-lived mobile ingest tokens with POST /api/v1/mobile_ingest_tokens.

import org.logister.android.LogisterExceptionDataPolicy
import org.logister.android.LogisterToken
import org.logister.android.LogisterTokenProvider
import org.logister.android.logisterClient

class AppBackendTokenProvider : LogisterTokenProvider {
    override fun fetchToken(): LogisterToken {
        return LogisterToken("short-lived-mobile-token", System.currentTimeMillis() / 1000 + 900)
    }
}

val client = logisterClient(
    baseUrl = "https://your-logister-host.example",
    tokenProvider = AppBackendTokenProvider()
) {
    environment("production")
    release("${BuildConfig.VERSION_NAME}+${BuildConfig.VERSION_CODE}")
    repository("acme/android-app")
    commitSha(BuildConfig.GIT_SHA)
    branch(BuildConfig.GIT_BRANCH)
    packageName(BuildConfig.APPLICATION_ID)
    appVersion(BuildConfig.VERSION_NAME)
    buildNumber(BuildConfig.VERSION_CODE.toString())
    buildType(BuildConfig.BUILD_TYPE)
    application(myApplication)
    exceptionDataPolicy(LogisterExceptionDataPolicy.TYPE_AND_STACKTRACE)
    sessionTracking(true)
    installationTracking(true, rotationDays = 90)
    breadcrumbs(capacity = 50)
    offlineQueue(enabled = true, maxEvents = 30, maxBytes = 512 * 1024, maxAgeDays = 7)
    automaticCrashCapture(true, LogisterExceptionDataPolicy.TYPE_AND_STACKTRACE)
    applicationExitCapture(true)
}

Android package name is the best default service identity. Release should include enough app version/build information to separate user-visible releases from CI or hotfix builds.

Source and deployments

Attach source context in the app, and record deployments from CI/CD.

The Android SDK adds repository, commit_sha, and branch to event context when you set them on the client builder. If the project is connected to the GitHub App, Logister can use those values to resolve stack frames and link to source.

Deployment records should be sent from CI/CD, not from the mobile app. After a Play, Firebase App Distribution, internal, or enterprise deploy succeeds, POST a deployment envelope to /api/v1/deployments with the release, environment, repository, commit SHA, branch, and workflow URL.

{
  "deployment": {
    "release": "1.4.0+42",
    "environment": "production",
    "repository": "acme/android-app",
    "commit_sha": "4f8c2d1a9b7e6c5d4a3b2c1d0e9f8a7b6c5d4e3f",
    "branch": "main",
    "release_tag": "android-v1.4.0",
    "workflow_run_url": "https://github.com/acme/android-app/actions/runs/123"
  }
}

Events

Send errors, logs, metrics, and transactions from Kotlin.

import org.logister.android.captureExceptionAsync
import org.logister.android.captureMetricAsync
import org.logister.android.captureMessageAsync
import org.logister.android.captureTransactionAsync

client.captureMessageAsync("Checkout opened") {
    context("screen_name", "Checkout")
    sessionId("session-123")
}

client.captureMetricAsync("cart.item_count", 3, "count")

client.captureTransactionAsync("screen.load", 184.2) {
    context("screen_name", "Checkout")
}

try {
    runCheckout()
} catch (exception: Exception) {
    client.captureExceptionAsync(exception) {
        mechanism("handled_exception")
        handled(true)
    }
}

Captured exceptions include structured exception context. Metric values should use stable names and units, and transactions should describe app work such as screen loads, local processing, sync jobs, or API calls.

Spans and check-ins

Use spans for waterfalls and check-ins for recurring Android work.

import org.logister.android.checkInAsync
import org.logister.android.captureSpanAsync
import org.logister.android.logisterSpan

client.captureSpanAsync(
    logisterSpan("trace-123", "GET /checkout", 42.5) {
        spanId("span-456")
        parentSpanId("span-root")
        kind("http")
        status("ok")
        context("screen_name", "Checkout")
    }
)

client.checkInAsync("daily-sync", "ok") {
    durationMs(812.4)
    context("expected_interval_seconds", 86_400)
}

Use shared trace IDs when a screen action triggers multiple spans. Check-ins are useful only for recurring work whose declared interval the app can reasonably meet and where a missed run is actionable. Android background scheduling is inexact, so use transaction and error events for WorkManager jobs that may be delayed by device state.

Mobile context

Send safe Android metadata that helps debugging without collecting secrets.

Stability inbox

Triage by failure type, release, impact, and affected cohort.

Android projects open a stability-specific inbox. Use the recommended, impact, or newest sort and filter by mechanism, release/build, Play track, environment, build type, device, Android/API version, screen, foreground state, and time range. The detail view keeps the Java/Kotlin cause chain, breadcrumbs, occurrences, app/device context, and raw event together.

R8 mappings

Upload each release's private mapping.txt.

1. Open Project settings → Integrations → R8 mappings.
2. Select the build's mapping.txt and enter the exact package name and version code.
3. Send an event from that build and confirm the stack says Deobfuscated.

Mappings are project- and build-scoped. If the event has no build number or no matching artifact, Logister shows Build unknown or Mapping missing rather than treating obfuscated frames as trustworthy.

Google Play

Import Play vitals without merging them into SDK metrics.

The optional Google Play panel is under Project settings → Integrations. Put the service-account JSON in the host's secret store, enter the environment-variable name as the credential reference, select permitted tracks, save, and queue an import. Logister stores crash/ANR rates, anomalies, release tracks, source, freshness, and time zone as a separate Play snapshot because Play and SDK populations can differ. Play rate rows are version-code scoped, so Logister resolves each selected track to its active version codes before filtering those rows.

Privacy defaults

Keep Android instrumentation explicit and bounded.

Sessions, the rotating installation pseudonym, breadcrumbs, the uncaught-exception handler, historical app exits, and offline delivery are disabled until enabled with an Application. Automatic crashes use TYPE_AND_STACKTRACE by default, which omits throwable messages and cause chains. Historical exits omit Android's raw description. The SDK never reads Android ID, advertising ID, IMEI, or a hardware serial.

• Do not send API tokens, authorization headers, cookies, payment data, medical data, or raw request/response bodies.
• Automatic crashes are synchronously persisted before the previous Android crash handler runs and therefore require offlineQueue.
• Keep breadcrumb capacity and offline queue event, byte, and age limits bounded.
• Flush after authentication and call clearSessionBoundQueuedEvents() during logout or account replacement.
• Use the app's privacy review before enabling installation tracking or sending user IDs, raw URLs, or custom breadcrumb data.

Verification

Confirm one event from the app before widening instrumentation.

Gradle resolves org.logister:logister-android
client can send one captureMessageAsync call
Activity page shows the Android log event
Inbox shows a test exception when captureExceptionAsync is called
Insights can filter by environment, release, service, or screen_name
Performance shows transactions or spans after timing events arrive
Event detail shows source context when repository and commitSha are configured
Event detail shows deployment context after CI posts /api/v1/deployments

Package releases

Android SDK releases are versioned separately from the Rails app.

The Android repository publishes signed artifacts to Maven Central from semantic version tags. The current release path also creates a GitHub release for the same tag. Use the package manager version that matches your app's compatibility needs, and update through Gradle dependency management or Dependabot as new versions are released.

• SDK source: github.com/taimoorq/logister-android
• Maven Central: org.logister:logister-android
• Maven repository path: repo1.maven.org/maven2/org/logister/logister-android