Android (Kotlin)

Überblick

• Keine ANDROID_ID, keine Werbe-ID, kein Gerätemodell, keine Install-ID — nichts Dauerhaftes.
• Nichts wird auf das Gerät geschrieben (keine SharedPreferences, keine Dateien, keine Datenbank). Events und Session-ID liegen nur im Arbeitsspeicher.
• Events werden gebündelt aus einem Hintergrund-Thread gesendet, mit neutralem User-Agent: trackd-android/<version>. Das SDK fängt alle Fehler ab und bringt deine App nie zum Absturz.

Voraussetzungen: minSdk 21 (Android 5.0), Kotlin 1.9+ / 2.x. Java-Aufrufer werden unterstützt.

Installation

Das Maven-Central-Paket folgt. Bis dahin:

1. Lade Trackd.kt herunter und lege die Datei unter app/src/main/java/one/trackd/sdk/Trackd.kt ab (Paket behalten oder die erste Zeile anpassen).
2. Stelle sicher, dass dein App-Manifest die Internet-Berechtigung enthält — auch für Release-Builds. Ohne sie werden keine Events gesendet:

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

Alternativ kannst du den Ordner sdk/android/ als Gradle-Modul einbinden (include(":trackd"), implementation(project(":trackd"))).

Initialisieren

Einmal in Application.onCreate() initialisieren, danach Screens und Events tracken:

import one.trackd.sdk.Trackd

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Trackd.init(this, "YOUR_WEBSITE_ID", debug = BuildConfig.DEBUG)
        // selbst gehostet: Trackd.init(this, "YOUR_WEBSITE_ID", host = "https://stats.example.com")
    }
}

Registriere die Klasse im Manifest (<application android:name=".MyApp" …>). Events, die vor init getrackt werden, bleiben im Speicher und werden danach gesendet. Lege im Dashboard ein Projekt mit deiner Application-ID (z. B. com.example.mygame) als Domain an.

API

Trackd.init(
    context, websiteId,
    host = "https://trackd.one",
    debug = false,
    flushIntervalMs = 30_000,   // spätestens 30 s nach einem Event senden
    flushAt = 20,               // … oder sobald 20 Events gesammelt sind
)

Trackd.screen("Home")                              // Screen-View (Alias: screenView)
Trackd.screen("Settings/Profile", "Profile")       // mit Titel
Trackd.event("signup", mapOf("plan" to "pro", "trial" to true))
Trackd.revenue(4.99, "EUR", "order-123")           // → Event "purchase"
Trackd.flush()                                     // jetzt senden (asynchron)
Trackd.setEnabled(false)                           // Opt-out: stoppen + Warteschlange leeren

// Hilfsmethoden für Games & Medien
Trackd.gameStart(level = 1, mode = "hard")
Trackd.levelComplete(level = 5, score = 1200, timeMs = 45_000)
Trackd.gameOver(level = 3, reason = "fell")
Trackd.videoWatch("intro", durationMs = 30_000, completed = true)
Trackd.adView("rewarded", "ad-1")
Trackd.tutorialStep(step = 2, total = 5, skipped = false)

Event-Daten müssen flach sein (String, Number, Boolean). Verschachtelte Maps/Listen, null und NaN/Infinity werden verworfen; das JSON ist auf 4 KB begrenzt.

Screens mit Jetpack Compose

@Composable
fun HomeScreen() {
    LaunchedEffect(Unit) { Trackd.screen("Home") }
}

// automatisch für Navigation Compose
DisposableEffect(navController) {
    val listener = NavController.OnDestinationChangedListener { _, destination, _ ->
        // Routen-Vorlagen wie "profile/{id}" — nie Nutzerdaten in Screen-Namen
        destination.route?.let { Trackd.screen(it.substringBefore('?')) }
    }
    navController.addOnDestinationChangedListener(listener)
    onDispose { navController.removeOnDestinationChangedListener(listener) }
}

Mit klassischen Activities/Fragments rufst du Trackd.screen("Settings") in onResume() auf.

Batching, Wiederholungen & Sessions

• Senden bei 20 gesammelten Events, 30 s nach einem Event (beides konfigurierbar), bei flush() und wenn die App in den Hintergrund geht.
• Max. 50 Events / 60 KB pro Request, max. 500 Events in der Warteschlange (die ältesten fallen weg).
• Netzwerkfehler, 5xx, 408, 429 → exponentielles Backoff (1 s … 5 min, Retry-After wird beachtet); derselbe Batch wird mit derselben batch_id erneut gesendet, der Server verwirft Duplikate.
• Session-ID: 20 zufällige Zeichen aus SecureRandom, nur im Speicher, neu nach 30 Minuten ohne Events oder 30 Minuten im Hintergrund. Prozessende = neue Session.

Google Play: Datensicherheit

Gib App-Aktivität → App-Interaktionen an (und Sonstige Aktionen, wenn du revenue nutzt) sowie Standort → Ungefährer Standort (Land, serverseitig aus der IP abgeleitet), Zweck Analytics, nicht weitergegeben, verschlüsselt übertragen. Geräte- oder andere IDs: nicht erhoben. Diese Angaben beschreiben nur das SDK — ergänze, was deine App sonst noch erhebt.

Hinweise

• ProGuard / R8: keine Keep-Regeln nötig.
• Self-Hosting über http:// lehnt der Server außerhalb von localhost ab; Android 9+ blockiert Klartext-Verkehr ohnehin. Nutze HTTPS.
• Beendet das System die App, während Events in der Warteschlange liegen, gehen diese verloren — der Preis dafür, nie Analysedaten auf die Festplatte zu schreiben.
• Ob du für die App eine Einwilligung brauchst, musst du selbst prüfen — siehe Datenschutz & DSGVO.