Deep links adiados no Android

Quando alguém no Android abre seu link do Unolink, o Unolink manda a pessoa para o Google Play e anexa um referrer. Depois que ela instala e abre seu app, o Google Play entrega esse referrer ao app. Ele diz de qual link a pessoa veio, além do deep link e dos parâmetros que você definiu nesse link. Esta página faz isso à mão, sem o SDK do Unolink, em qualquer plano. Com o SDK, é um único listener.

1. Dê um deep link ao link

No painel, abra seu app, vá em Links e escolha ⋯ → Editar em um link. Defina:

• Deep link: onde o app deve abrir, como um caminho (/promo/3for2) ou uma URI (myapp://promo/3for2).
• Parâmetros (opcional): até dez pares de nome e valor, por exemplo offer = 3for2.

As edições valem para novos cliques em poucos segundos.

2. Adicione a biblioteca Install Referrer

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

3. Leia o referrer uma vez, na primeira abertura

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 ou Expo (só Android), com 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

Chame isso uma vez depois da primeira abertura e guarde que você já fez isso. O Google Play mantém o referrer por 90 dias depois da instalação, então uma segunda leitura retorna os mesmos valores: não abra o deep link duas vezes.

Com o SDK (0.3.3+), isso já é feito para você: o link espera no aparelho até você consumi-lo, mesmo que o app seja fechado nesse meio-tempo (até 30 dias), então você pode abri-lo depois do onboarding ou do login e chamar consumeDeferredDeepLink() quando tiver aberto.

O que o referrer contém

O referrer é limitado a 1.000 caracteres. Se o deep link e os parâmetros de um link forem mais longos, os parâmetros ficam de fora primeiro, depois o deep link. A consulta de cliques sempre retorna tudo.

Se a URL do Google Play no Unolink já tiver seu próprio referrer=, o Unolink a deixa como está e não adiciona nada.

Instalações que não vieram pelo Unolink não têm unolink_click_id. Nesse caso, o Google Play informa algo como utm_source=google-play&utm_medium=organic.

Opcional: consulte o clique

Com uma chave de API (plano Pro ou superior), envie o ID do clique ao Unolink para obter o deep link e os parâmetros atuais do link, mesmo que fossem longos demais para o referrer ou tenham mudado depois do clique:

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

Veja a referência da API do SDK.

Como testar

O Google Play só passa um referrer em instalações feitas pelo Google Play, então teste com uma instalação real:

1. Envie uma build para Google Play Console → Testes → Teste interno e adicione você mesmo como testador.
2. No celular, desinstale o app, depois abra seu link do Unolink (por exemplo go.unolink.dev/yourapp/test) e instale pela página do Play que ele abrir.
3. Abra o app. O referrer deve conter seu unolink_click_id, e o callback do deep link deve rodar.

Para testar seu código de leitura sem instalar, passe a ele uma string como unolink_click_id=clk_01JA0000000000000000000000&unolink_deep_link=%2Fpromo%2F3for2.

iPhone

Não existe deep link adiado no iPhone. A Apple não tem referrer de instalação, e as alternativas dependem de fingerprinting, algo que o Unolink nunca faz. Os visitantes de iPhone continuam indo direto para a App Store, e os cliques deles são contados.

Contar o que acontece depois da instalação é outra história: com o SDK do Unolink, instalações, onboarding, visualizações de paywall, testes grátis e compras no iPhone são contados, assim como no Android, e o painel associa as instalações no iPhone ao link de onde vieram, sem fingerprinting. O que o iPhone não consegue é passar o link para o seu app na primeira abertura. Para os números de downloads por campanha da própria Apple no App Store Connect, defina o token de provedor da App Store no seu app.