Deep link differiti su Android

Quando qualcuno su Android apre il tuo link Unolink, Unolink lo manda su Google Play e aggiunge un referrer. Dopo che ha installato e aperto la tua app, Google Play passa quel referrer all’app. Ti dice da quale link è arrivato, più il deep link e i parametri che hai impostato su quel link. Questa pagina lo fa a mano, senza l’SDK Unolink, con qualsiasi piano. Con l’SDK basta un listener.

1. Assegna un deep link al link

Nella dashboard, apri la tua app, vai su Link e scegli ⋯ → Modifica su un link. Imposta:

• Deep link: dove deve aprirsi l’app, come path (/promo/3for2) o come URI (myapp://promo/3for2).
• Parametri (facoltativi): fino a dieci coppie nome/valore, ad esempio offer = 3for2.

Le modifiche si applicano ai nuovi clic entro pochi secondi.

2. Aggiungi la libreria Install Referrer

// app/build.gradle.kts
dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
}

3. Leggi il referrer una volta, al primo avvio

Kotlin:

import android.content.Context
import android.net.Uri
import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerStateListener

fun readUnolinkReferrer(context: Context, onLink: (deepLink: String?, params: Map<String, String>) -> Unit) {
    val prefs = context.getSharedPreferences("unolink", Context.MODE_PRIVATE)
    if (prefs.getBoolean("referrer_read", false)) return

    val client = InstallReferrerClient.newBuilder(context).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(code: Int) {
            if (code == InstallReferrerClient.InstallReferrerResponse.OK) {
                val referrer = client.installReferrer.installReferrer
                val query = Uri.parse("https://unolink.invalid/?$referrer")
                if (query.getQueryParameter("unolink_click_id") != null) {
                    val params = query.queryParameterNames
                        .filter { it.startsWith("unolink_p_") }
                        .associate { it.removePrefix("unolink_p_") to query.getQueryParameter(it).orEmpty() }
                    onLink(query.getQueryParameter("unolink_deep_link"), params)
                }
            }
            prefs.edit().putBoolean("referrer_read", true).apply()
            client.endConnection()
        }

        override fun onInstallReferrerServiceDisconnected() = Unit
    })
}

Java:

InstallReferrerClient client = InstallReferrerClient.newBuilder(context).build();
client.startConnection(new InstallReferrerStateListener() {
    @Override public void onInstallReferrerSetupFinished(int code) {
        if (code == InstallReferrerClient.InstallReferrerResponse.OK) {
            try {
                String referrer = client.getInstallReferrer().getInstallReferrer();
                Uri query = Uri.parse("https://unolink.invalid/?" + referrer);
                String clickId = query.getQueryParameter("unolink_click_id");
                String deepLink = query.getQueryParameter("unolink_deep_link");
                // Route to deepLink if clickId != null; parameters are unolink_p_<name>.
            } catch (RemoteException e) {
                // Play Store unavailable: try again on the next launch.
            }
        }
        client.endConnection();
    }
    @Override public void onInstallReferrerServiceDisconnected() { }
});

React Native o Expo (solo Android), con react-native-device-info:

import DeviceInfo from "react-native-device-info"

const referrer = await DeviceInfo.getInstallReferrer() // e.g. "unolink_click_id=clk_…&unolink_deep_link=%2Fpromo"
const query = new URLSearchParams(referrer)
const deepLink = query.get("unolink_click_id") ? query.get("unolink_deep_link") : null

Chiamalo una volta dopo il primo avvio e ricordati di averlo fatto. Google Play conserva il referrer per 90 giorni dopo l’installazione, quindi una seconda lettura restituisce gli stessi valori: non aprire il deep link due volte.

Con l’SDK (0.3.3+) se ne occupa lui: il link aspetta sul dispositivo finché non lo consumi, anche se nel frattempo l’app viene chiusa (fino a 30 giorni), quindi puoi aprirlo dopo l’onboarding o l’accesso e chiamare consumeDeferredDeepLink() una volta fatto.

Cosa contiene il referrer

Il referrer è limitato a 1.000 caratteri. Se il deep link e i parametri di un link sono più lunghi, vengono tolti prima i parametri, poi il deep link. La ricerca del clic restituisce sempre tutto.

Se il tuo URL di Google Play in Unolink ha già un suo referrer=, Unolink lo lascia com’è e non aggiunge nulla.

Le installazioni che non sono passate da Unolink non hanno unolink_click_id. Google Play riporta allora qualcosa come utm_source=google-play&utm_medium=organic.

Facoltativo: cerca il clic

Con una chiave API (dal piano Pro in su), invia l’ID del clic a Unolink per ottenere il deep link e i parametri attuali del link, anche se erano troppo lunghi per il referrer o sono cambiati dopo il clic:

curl https://api.unolink.dev/v1/clicks/clk_01JA… -H "X-Unolink-Key: ulk_…"

Vedi il Riferimento API dell’SDK.

Come testarlo

Google Play passa un referrer solo per le installazioni da Google Play, quindi testa con un’installazione reale:

1. Carica una build in Google Play Console → Test → Test interno e aggiungi te stesso come tester.
2. Sul telefono, disinstalla l’app, poi apri il tuo link Unolink (ad esempio go.unolink.dev/yourapp/test) e installa dalla scheda di Play che si apre.
3. Apri l’app. Il referrer dovrebbe contenere il tuo unolink_click_id, e la callback del deep link dovrebbe essere eseguita.

Per testare il tuo codice di parsing senza installare, passagli una stringa come unolink_click_id=clk_01JA0000000000000000000000&unolink_deep_link=%2Fpromo%2F3for2.

iPhone

Su iPhone non ci sono deep link differiti. Apple non ha un referrer di installazione, e le soluzioni alternative si basano sul fingerprinting, che Unolink non fa mai. I visitatori da iPhone vanno comunque direttamente all’App Store, e i loro clic vengono contati.

Contare cosa succede dopo l’installazione è un’altra cosa: con l’SDK Unolink, installazioni iPhone, onboarding, visualizzazioni del paywall, prove e acquisti vengono contati, come su Android, e la dashboard abbina le installazioni iPhone al link da cui provengono, senza fingerprinting. Quello che iPhone non può fare è passare il link alla tua app alla prima apertura. Per i dati sui download per campagna di Apple stessa in App Store Connect, imposta il token fornitore App Store nella tua app.