Android-SDK

Kotlin, aan te roepen vanuit Java. De SDK hangt alleen af van de Play Install Referrer-bibliotheek van Google en AndroidX lifecycle-process. Pro-abonnement en hoger.

Vereisten

• Android 6.0+ (minSdk 23).
• Kotlin of Java.
• Een SDK-sleutel: open in het dashboard je app → Instellingen → SDK-sleutels → Nieuwe sleutel. Hij wordt maar één keer getoond, dus kopieer hem meteen.

Installeren

De SDK staat op Maven Central, dat elk nieuw Android-project al gebruikt. Voeg één regel toe aan de app-module en synchroniseer Gradle:

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

Configureren

Roep configure één keer aan, in je Application-klasse, voordat er iets anders draait:

import dev.unolink.Unolink

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

Nog geen Application-klasse? Maak deze aan en registreer hem in AndroidManifest.xml:

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

Java:

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

Opties

Geef UnolinkOptions mee als derde argument. Elk veld is optioneel.

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

De sleutel is openbaar: hij zit in je app en kan alleen gegevens voor die ene app melden. Zie SDK-sleutels.

Funnelevents

Voeg één regel toe op elk moment dat ertoe doet. Dit worden de stappen in Funnel en Trajecten.

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

Zonder RevenueCat meld je proefperiodes en aankopen zelf. Het bedrag is een BigDecimal, dus prijzen worden nooit afgerond:

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

Je eigen events krijgen een naam en tot 20 eigenschappen:

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

De volledige lijst, met de namen die in het dashboard aankomen, staat in Events.

Gebruikers-ID en RevenueCat

Gebruik je RevenueCat, verbind het dan onder je app → Instellingen → RevenueCat. Roep daarna geen purchase of trialStarted aan: RevenueCat verstuurt zelf proefperiodes, aankopen, verlengingen, opzeggingen en terugbetalingen, en Unolink negeert aankoopaanroepen vanuit de app, zodat niets dubbel telt.

Om die aankopen aan de installatie te koppelen, meld je de eigen app-gebruikers-ID van RevenueCat. Met SDK 0.3.2 of nieuwer houdt één regel die actueel. Roep hem één keer aan bij de start, vóór of na configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink leest de ID bij de start, telkens wanneer de app naar de voorgrond komt en vóór elk event, en verstuurt hem alleen als hij is veranderd. Is RevenueCat nog niet geconfigureerd, dan mislukt het lezen stil en wordt het later opnieuw geprobeerd. Roep na Purchases.sharedInstance.logIn en logOut Unolink.revenueCatUserChanged() aan om de nieuwe ID meteen te versturen.

Zonder dit (of vóór 0.3.2) roep je setUserId aan met de ID van RevenueCat na Purchases.configure, na elke Purchases.logIn en Purchases.logOut, en bij elke start. Gebruik het een of het ander, niet allebei:

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

Voor een gast is dat het anonieme ID van RevenueCat, dus een aankoop die vóór de aanmelding wordt gedaan, wordt meteen aan de installatie gekoppeld. Na logIn is het de ID van het account. Elke ID die een installatie heeft gemeld telt mee, dus de aankoop van de gast blijft gekoppeld. Zie Gasten en accounts.

Unolink slaat de ID zelf nooit op, alleen een eenrichtingshash die voor elk van je apps anders is.

Uitgestelde deep links

Als iemand op Android op een Unolink-link tikt, installeert via Google Play en de app opent, leest de SDK de install referrer van Play en roept je listener één keer aan, op de main thread. Stel de Deeplink en Parameters van de link in het dashboard in (Links → ⋯ → Bewerken).

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

De listener wordt één keer per installatie aangeroepen. Registreer hem direct na configure, of later: een link die binnenkwam voordat je registreerde, wordt toch afgeleverd, ook bij een latere start als er eerder geen listener was.

Open hem na de onboarding

De eerste keer openen begint meestal met de onboarding. Zit het scherm van de link achter de onboarding of het inloggen, open hem dan niet vanuit de listener. Lees de wachtende link zodra de onboarding (of het inloggen) klaar is, open hem en markeer hem daarna als gebruikt:

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

De link wacht tot je hem als gebruikt markeert, ook als de app intussen wordt gesloten (tot 30 dagen na de installatie; 0.3.3+). Een nieuwe gebruiker die halverwege de onboarding stopt, krijgt hem bij de volgende start toch, dus je hoeft hem niet zelf op te slaan. Roep consumeDeferredDeepLink() aan zodra je hem hebt geopend: tot dan geeft getPendingDeferredDeepLink() hem bij elke start terug. Vóór configure en tot Google Play heeft geantwoord (een seconde of twee bij de eerste start) is hij null.

Om zonder installatie via Play te testen, gebruik je debugInstallReferrer (zie Testen). Hoe de install referrer werkt, staat in Uitgestelde deep links op Android.

Andere aanroepen

Hoe de SDK werkt

• Eerste start: leest de install referrer van Play, registreert de installatie en levert daarna de deeplink af als die er is.
• Automatische events: first_open, session_start (bij het starten, of na 30 minuten op de achtergrond) en app_background. Ze zijn gratis.
• Events worden op het apparaat bewaard (tot 1.000) en elke 15 seconden in batches verstuurd zolang de app open is, en als hij naar de achtergrond gaat. Offline wachten ze en probeert de SDK het opnieuw.
• Hij blokkeert nooit, gooit nooit een exception en gebruikt nooit de advertentie-ID (Advertising ID).

Testapparaten

Debuggable builds zijn automatisch testapparaten. Hun gegevens zijn echt, maar verborgen tot je Testapparaten meetellen aanzet in Funnel en Trajecten. Meer in Testen.

Privacy

• Een willekeurige installatie-ID, alleen opgeslagen in de eigen opslag van je app. Een herinstallatie krijgt een nieuwe.
• Appversie, OS-versie, SDK-versie, telefoon of tablet, taal. Het land komt van de netwerkrand. IP-adressen worden nooit opgeslagen.
• Geen advertentie-ID, geen fingerprinting.
• Zet nooit namen, e-mailadressen of andere persoonsgegevens in eigenschappen van events.

Problemen oplossen

• Niets in het dashboard? Zet Testapparaten meetellen aan: debugbuilds zijn standaard verborgen.
• Nog steeds niets? Configureer met UnolinkOptions(logLevel = LogLevel.DEBUG) en filter Logcat op Unolink. Een verkeerde of ingetrokken sleutel wordt als fout gelogd.
• Geen deeplink? Die komt alleen bij installaties via Google Play die van een Unolink-link met een ingestelde deeplink komen, bij de eerste start. Installeer opnieuw om nog eens te testen, of gebruik debugInstallReferrer.

Meer in Problemen oplossen.