logister-android

Android SDK for Logister.

This repository is the canonical home for the Android package add-on. Build Android client source, Gradle configuration, examples, tests, and release notes here rather than inside the Rails app.

Current Scope

• Single-module Android library configured for Gradle and Maven publication.
• Kotlin core with Java-compatible builders and async APIs for broad Android interop.
• Dependency-light HTTP transport using HttpURLConnection.
• Injectable transport for tests or alternate networking stacks.
• Async client methods for errors, logs, metrics, transactions, spans, and check-ins.
• Capture Android app metadata such as package name, version name, version code, build type, Android version, API level, device model, locale, and session ID.

Automatic crash, screen, network, retry, and offline-queue instrumentation should remain opt-in while privacy defaults are settled.

Install

Install the Android SDK from Maven Central:

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

• Maven Central: https://central.sonatype.com/artifact/org.logister/logister-android
• Maven repository path: https://repo1.maven.org/maven2/org/logister/logister-android/
• Android integration docs: https://docs.logister.org/integrations/android/

For local development, open this repository as an Android library project or include it as a composite build from an Android app.

Maven Central Release

The Maven coordinates are:

org.logister:logister-android:<version>

The org.logister namespace is verified in Sonatype Central Portal. Release signing uses an in-memory GPG key from GitHub Actions secrets.

The release workflow uses GitHub Actions secrets, not checked-in credentials:

• MAVEN_CENTRAL_USERNAME
• MAVEN_CENTRAL_PASSWORD
• SIGNING_KEY
• SIGNING_PASSWORD

Push a semantic version tag to upload a signed deployment to Central Portal:

git tag v0.1.0
git push origin v0.1.0

After the workflow succeeds, review the deployment in Sonatype Central Portal and click Publish. The workflow intentionally uploads without automatically publishing so signed artifacts can be inspected before sync to Maven Central.

Kotlin Usage

import org.logister.android.captureExceptionAsync
import org.logister.android.captureMetricAsync
import org.logister.android.captureMessageAsync
import org.logister.android.captureTransactionAsync
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}")
    packageName(BuildConfig.APPLICATION_ID)
    appVersion(BuildConfig.VERSION_NAME)
    buildNumber(BuildConfig.VERSION_CODE.toString())
    buildType(BuildConfig.BUILD_TYPE)
}

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

Spans And Check-ins

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

Java Interop

The Kotlin client classes remain Java-friendly, so Java apps can still use LogisterClient.builder(...), LogisterEventOptions.builder(...), and LogisterSpan.builder(...) directly.

Verification

Run the Android unit tests with:

./gradlew test

If your Android SDK is installed outside the default location, set ANDROID_HOME before running Gradle.

Public Repository Hygiene

This repository is designed to be public and open source. Keep examples generic: use placeholder API tokens, example hostnames, and environment variables instead of real project credentials.

Do not commit Android signing keys, Logister project API keys, Cloudflare tokens, Maven Central credentials, .env files, or local.properties.

CI runs scripts/secret-scan.sh, and dependency updates are tracked by .github/dependabot.yml for Gradle and GitHub Actions.

The CI workflow does not need secrets. The Maven Central release workflow does; set publishing credentials with the GitHub CLI:

gh secret set MAVEN_CENTRAL_USERNAME --repo taimoorq/logister-android
gh secret set MAVEN_CENTRAL_PASSWORD --repo taimoorq/logister-android
gpg --armor --export-secret-keys YOUR_KEY_ID | gh secret set SIGNING_KEY --repo taimoorq/logister-android
gh secret set SIGNING_PASSWORD --repo taimoorq/logister-android

The Rails-side integration plan lives in the logister Rails repository under docs/cloudflare-mobile-integrations-plan.md.