Android SDK

Kotlin, aus Java aufrufbar. Das SDK hängt nur von Googles Play-Install-Referrer-Bibliothek und AndroidX lifecycle-process ab. Ab dem Pro-Tarif.

Voraussetzungen

• Android 6.0+ (minSdk 23).
• Kotlin oder Java.
• Ein SDK-Schlüssel: Öffne im Dashboard deine App → Einstellungen → SDK-Schlüssel → Neuer Schlüssel. Er wird nur einmal angezeigt, kopiere ihn also gleich.

Installieren

Das SDK liegt auf Maven Central, das jedes neue Android-Projekt schon nutzt. Füge dem App-Modul eine Zeile hinzu und synchronisiere Gradle:

// app/build.gradle.kts
dependencies {
    implementation("dev.unolink:unolink:0.3.3")
}

Konfigurieren

Ruf configure einmal auf, in deiner Application-Klasse, bevor irgendetwas anderes läuft:

import dev.unolink.Unolink

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Unolink.configure(this, "ulk_…")
    }
}

Noch keine Application-Klasse? Leg diese an und registriere sie in AndroidManifest.xml:

<application android:name=".MyApp" …>

Java:

public class MyApp extends Application {
    @Override public void onCreate() {
        super.onCreate();
        Unolink.configure(this, "ulk_…");
    }
}

Optionen

Übergib UnolinkOptions als drittes Argument. Jedes Feld ist optional.

Unolink.configure(this, "ulk_…", UnolinkOptions(
    logLevel = LogLevel.DEBUG,
    debug = true,
))

Der Schlüssel ist öffentlich: Er wird mit deiner App ausgeliefert und kann nur Daten für genau diese eine App melden. Siehe SDK-Schlüssel.

Funnel-Events

Füge an jedem wichtigen Moment eine Zeile hinzu. Daraus werden die Schritte in Funnel und Journeys.

Unolink.onboardingCompleted()                 // the last onboarding screen is done
Unolink.paywallViewed("onboarding")           // a paywall appeared; placement says which one
Unolink.paywallSkipped("onboarding")          // closed without buying
Unolink.signUp("email")                       // an account was created
Unolink.signUpSkipped()                       // went on as a guest (0.3.2+)

Ohne RevenueCat meldest du Testphasen und Käufe selbst. Der Betrag ist ein BigDecimal, Preise werden also nie gerundet:

Unolink.trialStarted(productId = "pro_yearly")
Unolink.purchase(BigDecimal("49.99"), "USD", productId = "pro_yearly")
Unolink.purchaseCancelled(productId = "pro_yearly")   // closed the purchase sheet
Unolink.purchaseFailed(productId = "pro_yearly", reason = "card_declined")

Eigene Events nehmen einen Namen und bis zu 20 Eigenschaften:

Unolink.track("level_up", mapOf("level" to 3))

Die vollständige Liste mit den Namen, die im Dashboard ankommen, findest du unter Events.

Nutzer-ID und RevenueCat

Wenn du RevenueCat nutzt, verbinde es unter deiner App → Einstellungen → RevenueCat. Ruf dann nicht purchase oder trialStarted auf: RevenueCat sendet Testphasen, Käufe, Verlängerungen, Kündigungen und Erstattungen selbst, und Unolink ignoriert Kaufaufrufe aus der App, damit nichts doppelt zählt.

Um diese Käufe mit der Installation zu verknüpfen, melde RevenueCats eigene App-User-ID. Ab SDK 0.3.2 hält eine Zeile sie aktuell. Ruf sie einmal beim Start auf, vor oder nach configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink liest die ID beim Start, jedes Mal, wenn die App in den Vordergrund kommt, und vor jedem Event, und sendet sie nur, wenn sie sich geändert hat. Wenn RevenueCat noch nicht konfiguriert ist, schlägt das Lesen still fehl und wird später erneut versucht. Ruf nach Purchases.sharedInstance.logIn und logOut Unolink.revenueCatUserChanged() auf, um die neue ID sofort zu senden.

Ohne sie (oder vor 0.3.2) ruf setUserId mit RevenueCats ID auf, nach Purchases.configure, nach jedem Purchases.logIn und Purchases.logOut, und bei jedem Start. Nutze das eine oder das andere, nicht beides:

// after Purchases.configure, logIn and logOut, and on every launch
Unolink.setUserId(Purchases.sharedInstance.appUserID)

Für einen Gast ist das RevenueCats anonyme ID, sodass ein Kauf, der vor der Registrierung gemacht wird, sofort mit der Installation verknüpft wird. Nach logIn ist es die ID des Kontos. Jede ID, die eine Installation gemeldet hat, zählt, sodass der Kauf des Gasts verknüpft bleibt. Siehe Gäste und Konten.

Unolink speichert die ID selbst nie, nur einen Einweg-Hash, der für jede deiner Apps anders ist.

Deferred Deep Links

Wenn jemand auf Android einen Unolink-Link antippt, aus Google Play installiert und die App öffnet, liest das SDK den Play-Install-Referrer und ruft deinen Listener einmal auf, im Main-Thread. Leg Deeplink und Parameter des Links im Dashboard fest (Links → ⋯ → Bearbeiten).

Unolink.setDeferredDeepLinkListener { link ->
    // link.deepLink: "/promo/3for2" or "myapp://promo/3for2", or null
    // link.params:   mapOf("offer" to "3for2")
    // link.linkSlug: "tiktok", or null for your app's main link
    // link.clickId:  "clk_01JA…"
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

Der Listener wird einmal pro Installation aufgerufen. Registriere ihn direkt nach configure oder später: Ein Link, der vor der Registrierung angekommen ist, wird trotzdem zugestellt, auch bei einem späteren Start, wenn vorher kein Listener gesetzt war.

Nach dem Onboarding öffnen

Der erste Start beginnt meistens im Onboarding. Wenn der Screen des Links hinter Onboarding oder Anmeldung liegt, öffne ihn nicht aus dem Listener. Sobald Onboarding (oder Anmeldung) erledigt ist, lies den ausstehenden Link, öffne ihn und markiere ihn dann als verbraucht:

// when onboarding (or sign-in) is done, and on every launch after that until it's consumed
Unolink.getPendingDeferredDeepLink()?.let { link ->
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

Der Link wartet, bis du ihn als verbraucht markierst, auch wenn die App zwischendurch geschlossen wird (bis zu 30 Tage nach der Installation; 0.3.3+). Ein neuer Nutzer, der mitten im Onboarding aufhört, bekommt ihn beim nächsten Start trotzdem, du musst ihn also nicht selbst speichern. Ruf consumeDeferredDeepLink() auf, sobald du ihn geöffnet hast: Bis dahin gibt getPendingDeferredDeepLink() ihn bei jedem Start zurück. Vor configure und bis Google Play geantwortet hat (ein, zwei Sekunden beim ersten Start), ist er null.

Zum Testen ohne Installation über Play nutze debugInstallReferrer (siehe Testen). Wie der Referrer funktioniert, steht unter Deferred Deep Links unter Android.

Weitere Aufrufe

Wie es sich verhält

• Erster Start: liest den Play-Install-Referrer, registriert die Installation und liefert dann den Deeplink, falls es einen gibt.
• Automatische Events: first_open, session_start (beim Start oder nach 30 Minuten im Hintergrund) und app_background. Sie sind kostenlos.
• Events werden auf dem Gerät gespeichert (bis zu 1.000) und alle 15 Sekunden gebündelt gesendet, solange die App geöffnet ist, und wenn sie in den Hintergrund geht. Offline warten sie und werden erneut versucht.
• Es blockiert nie, wirft nie Exceptions und nutzt nie die Advertising ID.

Testgeräte

Debugfähige Builds sind automatisch Testgeräte. Ihre Daten sind echt, aber ausgeblendet, bis du Testgeräte einbeziehen in Funnel und Journeys aktivierst. Mehr unter Testen.

Datenschutz

• Eine zufällige Installations-ID, nur im eigenen Speicher deiner App abgelegt. Eine Neuinstallation bekommt eine neue.
• App-Version, OS-Version, SDK-Version, Smartphone oder Tablet, Sprache. Das Land kommt vom Netzwerk-Edge. IP-Adressen werden nie gespeichert.
• Keine Advertising ID, kein Fingerprinting.
• Pack nie Namen, E-Mail-Adressen oder andere personenbezogene Daten in Event-Eigenschaften.

Fehlerbehebung

• Nichts im Dashboard? Aktiviere Testgeräte einbeziehen: Debug-Builds sind standardmäßig ausgeblendet.
• Immer noch nichts? Konfiguriere mit UnolinkOptions(logLevel = LogLevel.DEBUG) und filtere Logcat nach Unolink. Ein falscher oder widerrufener Schlüssel wird als Fehler geloggt.
• Kein Deeplink? Er kommt nur bei Installationen aus Google Play über einen Unolink-Link mit gesetztem Deeplink an, beim ersten Start. Installiere neu, um erneut zu testen, oder nutze debugInstallReferrer.

Mehr unter Fehlerbehebung.