SDK per Android

Kotlin, utilizzabile da Java. L’SDK dipende solo dalla libreria Play Install Referrer di Google e da AndroidX lifecycle-process. Dal piano Pro in su.

Requisiti

• Android 6.0+ (minSdk 23).
• Kotlin o Java.
• Una chiave SDK: nella dashboard, apri la tua app → Impostazioni → Chiavi SDK → Nuova chiave. Viene mostrata una sola volta, quindi copiala subito.

Installazione

L’SDK è su Maven Central, che ogni nuovo progetto Android usa già. Aggiungi una riga al modulo dell’app e sincronizza Gradle:

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

Configurazione

Chiama configure una sola volta, nella tua classe Application, prima che venga eseguito qualsiasi altro codice:

import dev.unolink.Unolink

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

Non hai ancora una classe Application? Crea questa e registrala in AndroidManifest.xml:

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

Java:

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

Opzioni

Passa UnolinkOptions come terzo argomento. Ogni campo è facoltativo.

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

La chiave è pubblica: viene distribuita dentro la tua app e può solo riportare dati per quell’unica app. Vedi Chiavi SDK.

Eventi del funnel

Aggiungi una riga in ogni momento importante. Diventano i passaggi in Funnel e Percorsi.

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

Senza RevenueCat, riporta tu prove e acquisti. L’importo è un BigDecimal, così i prezzi non vengono mai arrotondati:

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

I tuoi eventi accettano un nome e fino a 20 proprietà:

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

L’elenco completo, con i nomi che arrivano alla dashboard, è in Eventi.

ID utente e RevenueCat

Se usi RevenueCat, collegalo dalla tua app → Impostazioni → RevenueCat. Poi non chiamare purchase né trialStarted: RevenueCat invia da solo prove, acquisti, rinnovi, cancellazioni e rimborsi, e Unolink ignora le chiamate di acquisto dell’app, così nulla conta due volte.

Per collegare quegli acquisti all’installazione, riporta l’app user ID di RevenueCat. Con l’SDK 0.3.2 o successivo, una riga lo tiene aggiornato. Chiamala una volta all’avvio, prima o dopo configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink legge l’ID all’avvio, ogni volta che l’app torna in primo piano e prima di ogni evento, e lo invia solo quando è cambiato. Se RevenueCat non è ancora configurato, la lettura fallisce senza errori e viene ritentata più tardi. Dopo Purchases.sharedInstance.logIn e logOut, chiama Unolink.revenueCatUserChanged() per inviare subito il nuovo ID.

Senza di esso (o prima della 0.3.2), chiama setUserId con l’ID di RevenueCat dopo Purchases.configure, dopo ogni Purchases.logIn e Purchases.logOut, e a ogni avvio. Usa l’uno o l’altro, non entrambi:

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

Per un ospite, è l’ID anonimo di RevenueCat, quindi un acquisto fatto prima della registrazione si collega subito all’installazione. Dopo logIn, è l’ID dell’account. Ogni ID riportato da un’installazione conta, così l’acquisto dell’ospite resta collegato. Vedi Ospiti e account.

Unolink non salva mai l’ID in sé, solo un hash unidirezionale diverso per ciascuna delle tue app.

Deep link differiti

Quando qualcuno tocca un link Unolink su Android, installa da Google Play e apre l’app, l’SDK legge il referrer di installazione di Play e chiama il tuo listener una volta, sul main thread. Imposta Deep link e Parametri del link nella dashboard (Link → ⋯ → Modifica).

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

Il listener viene chiamato una volta per installazione. Registralo subito dopo configure, o più tardi: un link arrivato prima della registrazione viene comunque consegnato, anche a un avvio successivo se prima non c’era nessun listener.

Aprilo dopo l’onboarding

Le prime aperture di solito iniziano dall’onboarding. Se la schermata del link si trova dopo l’onboarding o l’accesso, non aprirlo dal listener. Quando l’onboarding (o l’accesso) è finito, leggi il link in sospeso, aprilo e poi segnalo come consumato:

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

Il link aspetta finché non lo consumi, anche se nel frattempo l’app viene chiusa (fino a 30 giorni dopo l’installazione; 0.3.3+). Un nuovo utente che esce a metà onboarding lo riceve comunque all’avvio successivo, quindi non devi salvarlo tu. Chiama consumeDeferredDeepLink() dopo averlo aperto: fino ad allora, getPendingDeferredDeepLink() lo restituisce a ogni avvio. È null prima di configure e finché Google Play non ha risposto (un secondo o due al primo avvio).

Per testare senza un’installazione da Play, usa debugInstallReferrer (vedi Test). Come funziona il referrer è spiegato in Deep link differiti su Android.

Altre chiamate

Come si comporta

• Primo avvio: legge il referrer di installazione di Play, registra l’installazione, poi consegna il deep link se ce n’è uno.
• Eventi automatici: first_open, session_start (all’avvio, o dopo 30 minuti in background) e app_background. Sono gratis.
• Gli eventi vengono salvati sul dispositivo (fino a 1.000) e inviati a gruppi ogni 15 secondi mentre l’app è aperta, e quando va in background. Offline, aspettano e riprovano.
• Non blocca mai, non lancia mai eccezioni e non usa mai l’Advertising ID.

Dispositivi di test

Le build debuggable sono automaticamente dispositivi di test. I loro dati sono reali ma nascosti finché non attivi Includi dispositivi di test in Funnel e Percorsi. Altro in Test.

Privacy

• Un ID di installazione casuale, salvato solo nello spazio di archiviazione della tua app. Una reinstallazione ne riceve uno nuovo.
• Versione dell’app, versione del sistema operativo, versione dell’SDK, telefono o tablet, lingua. Il paese deriva dall’edge di rete. Gli indirizzi IP non vengono mai salvati.
• Nessun Advertising ID, nessun fingerprinting.
• Non mettere mai nomi, email o altri dati personali nelle proprietà degli eventi.

Risoluzione dei problemi

• Niente nella dashboard? Attiva Includi dispositivi di test: le build di debug sono nascoste per impostazione predefinita.
• Ancora niente? Configura con UnolinkOptions(logLevel = LogLevel.DEBUG) e filtra Logcat per Unolink. Una chiave sbagliata o revocata viene registrata come errore.
• Nessun deep link? Arriva solo per le installazioni da Google Play tramite un link Unolink con un deep link impostato, al primo avvio. Reinstalla per testare di nuovo, oppure usa debugInstallReferrer.

Altro in Risoluzione dei problemi.