Как правильно получать Android Referrer и сохранять атрибуцию

Короткий ответ: используйте официальную библиотеку Google Play Install Referrer (com.android.installreferrer), сразу парсите и URL‑decode строку referrer, отправляйте UTM‑параметры в аналитику и/или сервер‑side Conversion API — это минимизирует потерю атрибуции при задержках установки и deep linking.

Что такое Android Referrer и зачем он нужен

Android Referrer — строка, которую Google Play передаёт приложению при первой установке. В ней обычно передают UTM‑метки (utm_source, utm_medium, utm_campaign и др.). Если не принимать и не фиксировать эти параметры корректно, установки будут считаться «прямыми», что ломает кампании и ROI‑аналитику.

Как правильно настроить Install Referrer (пошагово)

1. Добавьте зависимость в build.gradle (app):

implementation 'com.android.installreferrer:installreferrer:2.2'

2. Инициализация и чтение referrer в Kotlin (выполняйте при первом запуске приложения):

val client = InstallReferrerClient.newBuilder(context).build()
client.startConnection(object : InstallReferrerStateListener {
  override fun onInstallReferrerSetupFinished(responseCode: Int) {
    if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
      val details = client.installReferrer
      val raw = details.installReferrer // URL‑encoded строка
      val clickTs = details.googlePlayInstantReferrerClickTimestampSeconds
      val installTs = details.installBeginTimestampSeconds
      val decoded = URLDecoder.decode(raw, "UTF-8")
      // Разбить decoded на пары key=value и отправить в аналитику/сервер
      sendToAnalytics(decoded, clickTs, installTs)
    } else {
      // FEATURE_NOT_SUPPORTED, SERVICE_UNAVAILABLE и т.п. — применить fallback
    }
  }
  override fun onInstallReferrerServiceDisconnected() { /* ретрай */ }
})
// В onDestroy:
client.endConnection()

• Парсите параметры через готовый парсер query string, а не простым split, чтобы избежать ошибок с кодированием.
• Отправляйте данные сразу при первом запуске — это снижает риск потери при долгой задержке установки.

Ошибки, тестирование и лучшие практики

• Декодирование: строка приходит URL‑encoded — используйте URLDecoder.decode(..., "UTF-8") или проверенные парсеры.
• Retry и fallback: если responseCode != OK, сохраняйте попытки и применяйте fallback (например, Play Campaign API или аналитический SDK).
• Attribution SDK: AppsFlyer/Adjust могут самостоятельно запрашивать referrer; интегрируйте корректно, чтобы не было дублирования событий.
• Server‑side: отправляйте referrer‑UTM на сервер (Conversion API), связывайте install event с серверной аналитикой для LTV и ретаргетинга.
• Согласие пользователя: учитывайте Consent Mode (EEA) и не отправляйте персональные данные без нужного согласия.

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

• Сгенерировать тестовую установку через adb: adb shell am start -a android.intent.action.VIEW -d "http://play.google.com/store/apps/details?id=your.app&referrer=utm_source%3Dtest"
• Смотреть логи: adb logcat | grep InstallReferrer

Частые ошибки

• Неправильное декодирование: приводит к %3D вместо = — решение: URLDecoder.decode.
• Вызов installReferrer в нескольких местах: дублирование событий — централизуйте чтение и отправку.
• Не сохраняют clickTimestamp: теряется cohort‑анализ LTV.
• Ожидание более 7 дней: referrer хранится до 7 дней, но лучше отправлять сразу.

FAQ

• Нужно ли поддерживать старые Broadcast Receiver?
  Нет: Google рекомендует Install Referrer API; legacy CampaignTrackingReceiver устарел.
• Сколько времени хранится referrer в Play?
  До 7 дней, но лучше отправлять значения при первом запуске.
• Что делать, если InstallReferrer возвращает FEATURE_NOT_SUPPORTED?
  Реализуйте fallback: попытка повторного подключения, затем использование аналитического SDK или данных Play Console (TrafficSourceParams) на сервере.

С такой настройкой вы минимизируете потери атрибуции: корректный парсинг, немедленная отправка и server‑side совпадут с большинством рекламных сценариев.