Отложенные диплинки на Android

Когда человек на Android открывает вашу ссылку Unolink, Unolink отправляет его в Google Play и прикрепляет реферер. После того как он установит и откроет приложение, Google Play передаст этот реферер приложению. Из него вы узнаете, с какой ссылки пришёл человек, а также диплинк и параметры, заданные для этой ссылки. На этой странице это делается вручную, без Unolink SDK, на любом тарифе. С SDK это один слушатель.

1. Задайте ссылке диплинк

В панели откройте приложение, перейдите в Ссылки и выберите у ссылки ⋯ → Изменить. Задайте:

Диплинк: где должно открыться приложение, в виде пути (/promo/3for2) или URI (myapp://promo/3for2).
Параметры (необязательно): до десяти пар имя/значение, например offer = 3for2.

Изменения применяются к новым кликам в течение нескольких секунд.

2. Добавьте библиотеку Install Referrer

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

3. Прочитайте реферер один раз, при первом запуске

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 или Expo (только Android), с 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

Вызовите это один раз после первого запуска и запомните, что вы это сделали. Google Play хранит реферер 90 дней после установки, поэтому повторное чтение вернёт те же значения: не открывайте диплинк дважды.

С SDK (0.3.3+) это делается за вас: ссылка ждёт на устройстве, пока вы её не используете, даже если приложение за это время закрывали (до 30 дней), поэтому вы можете открыть её после онбординга или входа в аккаунт и вызвать consumeDeferredDeepLink(), когда откроете.

Что содержит реферер

Ключ	Значение
`unolink_click_id`	ID клика, например `clk_01JA…`. Всегда есть у установок через Unolink.
`unolink_link`	Путь ссылки кампании, например `tiktok`. Отсутствует для основной ссылки приложения.
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	UTM-метки ссылки, по которой нажал человек, если они есть.
`unolink_deep_link`	Диплинк ссылки.
`unolink_p_<name>`	Каждый из параметров ссылки.

Длина реферера ограничена 1000 символами. Если диплинк и параметры ссылки длиннее, сначала отбрасываются параметры, затем диплинк. Поиск клика всегда возвращает всё.

Если в вашем URL Google Play в Unolink уже есть свой referrer=, Unolink оставляет его как есть и ничего не добавляет.

У установок, которые пришли не через Unolink, нет unolink_click_id. В этом случае Google Play сообщает что-то вроде utm_source=google-play&utm_medium=organic.

Необязательно: найдите клик

С ключом API (тариф Pro и выше) отправьте ID клика в Unolink, чтобы получить текущие диплинк и параметры ссылки, даже если они были слишком длинными для реферера или изменились после клика:

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

См. справочник SDK API.

Тестирование

Google Play передаёт реферер только для установок из Google Play, поэтому тестируйте на настоящей установке:

Загрузите сборку в Google Play Console → Тестирование → Внутреннее тестирование и добавьте себя как тестировщика.
На телефоне удалите приложение, затем откройте свою ссылку Unolink (например, go.unolink.dev/yourapp/test) и установите приложение со страницы в Play, которая откроется.
Откройте приложение. Реферер должен содержать ваш unolink_click_id, а колбэк диплинка должен сработать.

Чтобы проверить код разбора без установки, передайте ему строку вроде unolink_click_id=clk_01JA0000000000000000000000&unolink_deep_link=%2Fpromo%2F3for2.

iPhone

На iPhone отложенного диплинка нет. У Apple нет реферера установки, а обходные пути основаны на фингерпринтинге, которым Unolink никогда не занимается. Посетители с iPhone по-прежнему попадают прямо в App Store, а их клики учитываются.

Учёт того, что происходит после установки, — другое дело: с Unolink SDK установки на iPhone, онбординг, просмотры пейволла, пробные периоды и покупки учитываются так же, как на Android, а панель сопоставляет установки на iPhone со ссылкой, с которой они пришли, без фингерпринтинга. Чего iPhone не умеет, так это передать ссылку вашему приложению при первом открытии. Чтобы видеть собственные данные Apple о загрузках по кампаниям в App Store Connect, задайте для приложения токен провайдера App Store.