SDK Android

Kotlin, utilisable depuis Java. Le SDK ne dépend que de la bibliothèque Play Install Referrer de Google et d’AndroidX lifecycle-process. Forfait Pro et plus.

Prérequis

• Android 6.0+ (minSdk 23).
• Kotlin ou Java.
• Une clé SDK : dans le tableau de bord, ouvrez votre app → Paramètres → Clés SDK → Nouvelle clé. Elle n’est affichée qu’une fois, copiez-la à ce moment-là.

Installation

Le SDK est sur Maven Central, que tout nouveau projet Android utilise déjà. Ajoutez une ligne au module de l’app et synchronisez Gradle :

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

Configuration

Appelez configure une seule fois, dans votre classe Application, avant que quoi que ce soit d’autre ne s’exécute :

import dev.unolink.Unolink

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

Pas encore de classe Application ? Créez celle-ci et déclarez-la dans AndroidManifest.xml :

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

Java :

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

Options

Passez UnolinkOptions en troisième argument. Chaque champ est facultatif.

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

La clé est publique : elle est livrée dans votre app et ne peut envoyer des données que pour cette app. Voir Clés SDK.

Événements d’entonnoir

Ajoutez une ligne à chaque moment qui compte. Elles deviennent les étapes de Entonnoir et Parcours.

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

Sans RevenueCat, remontez vous-même les essais et les achats. Le montant est un BigDecimal, les prix ne sont donc jamais arrondis :

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

Vos propres événements prennent un nom et jusqu’à 20 propriétés :

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

La liste complète, avec les noms qui arrivent dans le tableau de bord, se trouve dans Événements.

Identifiant utilisateur et RevenueCat

Si vous utilisez RevenueCat, connectez-le dans votre app → Paramètres → RevenueCat. N’appelez alors pas purchase ni trialStarted : RevenueCat envoie lui-même les essais, achats, renouvellements, annulations et remboursements, et Unolink ignore les appels d’achat de l’app pour que rien ne compte deux fois.

Pour relier ces achats à l’installation, signalez le propre identifiant utilisateur d’app de RevenueCat. Avec le SDK 0.3.2 ou plus récent, une seule ligne le tient à jour. Appelez-la une fois au lancement, avant ou après configure :

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink lit l’identifiant au lancement, chaque fois que l’app passe au premier plan et avant chaque événement, et ne l’envoie que s’il a changé. Si RevenueCat n’est pas encore configuré, la lecture échoue sans bruit et est retentée plus tard. Après Purchases.sharedInstance.logIn et logOut, appelez Unolink.revenueCatUserChanged() pour envoyer le nouvel identifiant tout de suite.

Sans elle (ou avant la 0.3.2), appelez setUserId avec l’identifiant de RevenueCat après Purchases.configure, après chaque Purchases.logIn et Purchases.logOut, et à chaque lancement. Utilisez l’un ou l’autre, pas les deux :

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

Pour un invité, c’est l’identifiant anonyme de RevenueCat, donc un achat fait avant l’inscription est relié à l’installation tout de suite. Après logIn, c’est l’identifiant du compte. Chaque identifiant signalé par une installation compte, donc l’achat de l’invité reste relié. Voir Invités et comptes.

Unolink ne stocke jamais l’identifiant lui-même, seulement un hachage à sens unique, différent pour chacune de vos apps.

Liens profonds différés

Quand quelqu’un appuie sur un lien Unolink sur Android, installe depuis Google Play et ouvre l’app, le SDK lit le referrer d’installation de Play et appelle votre listener une fois, sur le thread principal. Définissez le Deep link et les Paramètres du lien dans le tableau de bord (Liens → ⋯ → Modifier).

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

Le listener est appelé une fois par installation. Enregistrez-le juste après configure, ou plus tard : un lien arrivé avant l’enregistrement est quand même transmis, y compris lors d’un lancement ultérieur si aucun listener n’avait été défini.

L’ouvrir après l’onboarding

Les premières ouvertures commencent généralement par l’onboarding. Si l’écran du lien se trouve derrière l’onboarding ou la connexion, ne l’ouvrez pas depuis le listener. Une fois l’onboarding (ou la connexion) terminé, lisez le lien en attente, ouvrez-le, puis consommez-le :

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

Le lien attend que vous le consommiez, même si l’app est fermée entre-temps (jusqu’à 30 jours après l’installation ; 0.3.3+). Un nouvel utilisateur qui quitte l’app au milieu de l’onboarding le retrouve au lancement suivant : inutile de le stocker vous-même. Appelez consumeDeferredDeepLink() une fois que vous l’avez ouvert : d’ici là, getPendingDeferredDeepLink() le renvoie à chaque lancement. Il vaut null avant configure et tant que Google Play n’a pas répondu (une seconde ou deux au premier lancement).

Pour tester sans installation depuis Play, utilisez debugInstallReferrer (voir Tests). Le fonctionnement du referrer est expliqué dans Liens profonds différés Android.

Autres appels

Fonctionnement

• Premier lancement : lit le referrer d’installation de Play, enregistre l’installation, puis transmet le deep link s’il y en a un.
• Événements automatiques : first_open, session_start (au lancement, ou après 30 minutes en arrière-plan) et app_background. Ils sont gratuits.
• Les événements sont stockés sur l’appareil (jusqu’à 1 000) et envoyés par lots toutes les 15 secondes tant que l’app est ouverte, ainsi que lorsqu’elle passe en arrière-plan. Hors ligne, ils attendent et réessaient.
• Il ne bloque jamais, ne lève jamais d’exception et n’utilise jamais l’Advertising ID.

Appareils de test

Les builds debuggables sont automatiquement des appareils de test. Leurs données sont réelles mais masquées tant que vous n’activez pas Inclure les appareils de test dans Entonnoir et Parcours. Plus d’informations dans Tests.

Confidentialité

• Un identifiant d’installation aléatoire, stocké uniquement dans le stockage propre à votre app. Une réinstallation en obtient un nouveau.
• La version de l’app, la version de l’OS, la version du SDK, téléphone ou tablette, la langue. Le pays vient de la périphérie du réseau. Les adresses IP ne sont jamais stockées.
• Pas d’Advertising ID, pas de fingerprinting.
• Ne mettez jamais de noms, d’e-mails ou d’autres données personnelles dans les propriétés des événements.

Dépannage

• Rien dans le tableau de bord ? Activez Inclure les appareils de test : les builds de debug sont masqués par défaut.
• Toujours rien ? Configurez avec UnolinkOptions(logLevel = LogLevel.DEBUG) et filtrez Logcat sur Unolink. Une clé erronée ou révoquée est consignée comme erreur.
• Pas de deep link ? Il n’arrive que pour les installations depuis Google Play via un lien Unolink avec un deep link défini, au premier lancement. Réinstallez pour tester à nouveau, ou utilisez debugInstallReferrer.

Plus d’informations dans Dépannage.