Integrate an Android app with Logister.

Before you start

Create the project with the Android integration type.

What is supported

The Android SDK starts with explicit, app-controlled telemetry.

Install

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

The current public Android package version is 0.1.1. 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.1.1")
}

• 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 for Android apps. Keep the API token in app configuration or a secure runtime source appropriate for your app; do not commit real project tokens into source control.

import org.logister.android.logisterClient

val client = logisterClient(
    apiKey = "your-project-api-token",
    baseUrl = "https://your-logister-host.example"
) {
    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)
}

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

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 for recurring sync, cleanup, cache refresh, or other scheduled app work where a missed run should be visible.

Mobile context

Send safe Android metadata that helps debugging without collecting secrets.

Privacy defaults

Keep Android instrumentation explicit.

The Android add-on starts with manual capture methods. Automatic crash, screen, network, retry, and offline-queue instrumentation should stay opt-in so each app can decide what data is collected, retained, and sent over the network.

• Do not send API tokens, authorization headers, cookies, payment data, medical data, or raw request/response bodies.
• Prefer stable, low-cardinality values such as route names, feature names, build metadata, status codes, and safe session IDs.
• Use the app's privacy review before sending device identifiers, user identifiers, query text, or raw URLs.

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