Deferred Deep Links unter Android

Wenn jemand auf Android deinen Unolink-Link öffnet, schickt Unolink die Person zu Google Play und hängt einen Referrer an. Nach dem Installieren und Öffnen deiner App übergibt Google Play diesen Referrer an die App. Er sagt dir, über welchen Link die Person kam, plus den Deeplink und die Parameter, die du für diesen Link festgelegt hast. Diese Seite macht das von Hand, ohne Unolink SDK, in jedem Tarif. Mit dem SDK ist es ein einziger Listener.

1. Dem Link einen Deeplink geben

Öffne im Dashboard deine App, geh zu Links und wähle bei einem Link ⋯ → Bearbeiten. Leg fest:

• Deeplink: wo die App sich öffnen soll, als Pfad (/promo/3for2) oder als URI (myapp://promo/3for2).
• Parameter (optional): bis zu zehn Name-Wert-Paare, zum Beispiel offer = 3for2.

Änderungen gelten innerhalb von Sekunden für neue Klicks.

2. Die Install-Referrer-Bibliothek hinzufügen

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

3. Den Referrer einmal lesen, beim ersten Start

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 oder Expo (nur Android), mit 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

Ruf es nach dem ersten Start einmal auf und merk dir, dass du es getan hast. Google Play hält den Referrer 90 Tage nach der Installation bereit, ein zweites Lesen liefert also dieselben Werte: Öffne den Deeplink nicht zweimal.

Mit dem SDK (0.3.3+) wird das für dich erledigt: Der Link wartet auf dem Gerät, bis du ihn als verbraucht markierst, auch wenn die App zwischendurch geschlossen wird (bis zu 30 Tage). So kannst du ihn nach dem Onboarding oder der Anmeldung öffnen und danach consumeDeferredDeepLink() aufrufen.

Was der Referrer enthält

Der Referrer ist auf 1.000 Zeichen begrenzt. Sind Deeplink und Parameter eines Links länger, fallen zuerst die Parameter weg, dann der Deeplink. Die Klick-Abfrage liefert immer alles.

Wenn deine Google-Play-URL in Unolink schon einen eigenen referrer= hat, lässt Unolink ihn unverändert und fügt nichts hinzu.

Installationen, die nicht über Unolink kamen, haben keine unolink_click_id. Google Play meldet dann etwas wie utm_source=google-play&utm_medium=organic.

Optional: den Klick abfragen

Mit einem API-Schlüssel (ab dem Pro-Tarif) schickst du die Klick-ID an Unolink und bekommst den aktuellen Deeplink und die Parameter des Links, auch wenn sie für den Referrer zu lang waren oder nach dem Klick geändert wurden:

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

Siehe die SDK-API-Referenz.

Testen

Google Play übergibt einen Referrer nur bei Installationen über Google Play, teste also mit einer echten Installation:

1. Lade einen Build in die Google Play Console → Testen → Interner Test hoch und füge dich als Tester hinzu.
2. Deinstalliere die App auf dem Smartphone, öffne dann deinen Unolink-Link (zum Beispiel go.unolink.dev/yourapp/test) und installiere über den Play-Eintrag, der sich öffnet.
3. Öffne die App. Der Referrer sollte deine unolink_click_id enthalten, und der Deeplink-Callback sollte laufen.

Um deinen Parsing-Code ohne Installation zu testen, übergib ihm einen String wie unolink_click_id=clk_01JA0000000000000000000000&unolink_deep_link=%2Fpromo%2F3for2.

iPhone

Auf dem iPhone gibt es keinen Deferred Deep Link. Apple hat keinen Install-Referrer, und die Umwege beruhen auf Fingerprinting, was Unolink nie macht. iPhone-Besucher gehen trotzdem direkt in den App Store, und ihre Klicks werden gezählt.

Zu zählen, was nach der Installation passiert, ist etwas anderes: Mit dem Unolink SDK werden iPhone-Installationen, Onboarding, Paywall-Aufrufe, Testphasen und Käufe gezählt, genau wie unter Android, und das Dashboard ordnet iPhone-Installationen dem Link zu, über den sie kamen, ohne Fingerprinting. Was das iPhone nicht kann: deiner App beim ersten Öffnen den Link übergeben. Für Apples eigene Downloadzahlen pro Kampagne in App Store Connect hinterleg das App-Store-Provider-Token bei deiner App.