SDK для Android

Kotlin, можно вызывать из Java. SDK зависит только от библиотеки Play Install Referrer от Google и AndroidX lifecycle-process. Тариф Pro и выше.

Требования

• Android 6.0+ (minSdk 23).
• Kotlin или Java.
• Ключ SDK: в панели откройте приложение → Настройки → Ключи SDK → Новый ключ. Он показывается один раз, поэтому скопируйте его сразу.

Установка

SDK опубликован в Maven Central, который уже используется в каждом новом Android-проекте. Добавьте одну строку в модуль приложения и синхронизируйте Gradle:

// app/build.gradle.kts
dependencies {
    implementation("dev.unolink:unolink:0.3.3")
}

Настройка

Вызовите configure один раз, в классе Application, до того как запустится что-либо ещё:

import dev.unolink.Unolink

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Unolink.configure(this, "ulk_…")
    }
}

Ещё нет класса Application? Создайте этот и зарегистрируйте его в AndroidManifest.xml:

<application android:name=".MyApp" …>

Java:

public class MyApp extends Application {
    @Override public void onCreate() {
        super.onCreate();
        Unolink.configure(this, "ulk_…");
    }
}

Параметры

Передайте UnolinkOptions третьим аргументом. Все поля необязательны.

Unolink.configure(this, "ulk_…", UnolinkOptions(
    logLevel = LogLevel.DEBUG,
    debug = true,
))

Ключ публичный: он поставляется внутри вашего приложения и может отправлять данные только для этого одного приложения. См. Ключи SDK.

События воронки

Добавьте по одной строке в каждый важный момент. Они станут шагами в Воронке и «Путях».

Unolink.onboardingCompleted()                 // the last onboarding screen is done
Unolink.paywallViewed("onboarding")           // a paywall appeared; placement says which one
Unolink.paywallSkipped("onboarding")          // closed without buying
Unolink.signUp("email")                       // an account was created
Unolink.signUpSkipped()                       // went on as a guest (0.3.2+)

Без RevenueCat сообщайте о пробных периодах и покупках сами. Сумма имеет тип BigDecimal, поэтому цены никогда не округляются:

Unolink.trialStarted(productId = "pro_yearly")
Unolink.purchase(BigDecimal("49.99"), "USD", productId = "pro_yearly")
Unolink.purchaseCancelled(productId = "pro_yearly")   // closed the purchase sheet
Unolink.purchaseFailed(productId = "pro_yearly", reason = "card_declined")

Ваши собственные события принимают имя и до 20 свойств:

Unolink.track("level_up", mapOf("level" to 3))

Полный список с названиями, которые попадают в панель, — в разделе События.

ID пользователя и RevenueCat

Если вы используете RevenueCat, подключите его в приложении → Настройки → RevenueCat. Тогда не вызывайте purchase и trialStarted: RevenueCat сам отправляет пробные периоды, покупки, продления, отмены и возвраты, а Unolink игнорирует вызовы покупок из приложения, чтобы ничего не учитывалось дважды.

Чтобы привязать эти покупки к установке, сообщайте собственный app user ID RevenueCat. В SDK 0.3.2 и новее одна строка поддерживает его в актуальном состоянии. Вызовите её один раз при запуске, до или после configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink считывает ID при запуске, каждый раз, когда приложение выходит на передний план, и перед каждым событием, и отправляет его, только если он изменился. Если RevenueCat ещё не настроен, чтение тихо завершается неудачей и повторяется позже. После Purchases.sharedInstance.logIn и logOut вызывайте Unolink.revenueCatUserChanged(), чтобы сразу отправить новый ID.

Без этого (или до версии 0.3.2) вызывайте setUserId с ID из RevenueCat после Purchases.configure, после каждого Purchases.logIn и Purchases.logOut и при каждом запуске. Используйте что-то одно, а не оба способа сразу:

// after Purchases.configure, logIn and logOut, and on every launch
Unolink.setUserId(Purchases.sharedInstance.appUserID)

Для гостя это анонимный ID RevenueCat, поэтому покупка, сделанная до регистрации, сразу привязывается к установке. После logIn это ID аккаунта. Учитываются все ID, которые сообщала установка, поэтому покупка гостя остаётся привязанной. См. Гости и аккаунты.

Unolink никогда не хранит сам ID, только односторонний хеш, который у каждого вашего приложения свой.

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

Когда человек нажимает на ссылку Unolink на Android, устанавливает приложение из Google Play и открывает его, SDK читает реферер установки Play и один раз вызывает ваш слушатель в главном потоке. Задайте Диплинк и Параметры ссылки в панели (Ссылки → ⋯ → Изменить).

Unolink.setDeferredDeepLinkListener { link ->
    // link.deepLink: "/promo/3for2" or "myapp://promo/3for2", or null
    // link.params:   mapOf("offer" to "3for2")
    // link.linkSlug: "tiktok", or null for your app's main link
    // link.clickId:  "clk_01JA…"
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

Слушатель вызывается один раз на установку. Зарегистрируйте его сразу после configure или позже: ссылка, пришедшая до регистрации, всё равно будет доставлена, в том числе при одном из следующих запусков, если до этого слушатель не был задан.

Откройте её после онбординга

Первое открытие обычно начинается с онбординга. Если экран ссылки находится за онбордингом или входом в аккаунт, не открывайте его из слушателя. Когда онбординг (или вход) завершён, прочитайте ожидающую ссылку, откройте её, а затем отметьте как использованную:

// when onboarding (or sign-in) is done, and on every launch after that until it's consumed
Unolink.getPendingDeferredDeepLink()?.let { link ->
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

Ссылка ждёт, пока вы её не используете, даже если приложение за это время закрывали (до 30 дней после установки; 0.3.3+). Новый пользователь, который бросил онбординг на середине, всё равно получит её при следующем запуске, так что хранить её самим не нужно. Вызовите consumeDeferredDeepLink(), когда откроете её: до этого getPendingDeferredDeepLink() возвращает её при каждом запуске. Он возвращает null до configure и пока Google Play не ответил (секунда-другая при первом запуске).

Чтобы протестировать без установки из Play, используйте debugInstallReferrer (см. Тестирование). Как работает реферер, описано в разделе Отложенные диплинки на Android.

Другие вызовы

Как он работает

• Первый запуск: читает реферер установки Play, регистрирует установку, затем доставляет диплинк, если он есть.
• Автоматические события: first_open, session_start (при запуске или после 30 минут в фоне) и app_background. Они бесплатны.
• События хранятся на устройстве (до 1000) и отправляются пакетами каждые 15 секунд, пока приложение открыто, а также когда оно уходит в фон. Без сети они ждут и отправляются повторно.
• Он никогда не блокирует, никогда не выбрасывает исключений и никогда не использует Advertising ID.

Тестовые устройства

Debuggable-сборки автоматически считаются тестовыми устройствами. Их данные настоящие, но скрыты, пока вы не включите Включать тестовые устройства в Воронке и «Путях». Подробнее в разделе Тестирование.

Конфиденциальность

• Случайный ID установки, который хранится только в собственном хранилище вашего приложения. При переустановке создаётся новый.
• Версия приложения, версия ОС, версия SDK, телефон или планшет, язык. Страна определяется на границе сети. IP-адреса никогда не хранятся.
• Без Advertising ID, без фингерпринтинга.
• Никогда не передавайте имена, email или другие персональные данные в свойствах событий.

Решение проблем

• В панели ничего нет? Включите Учитывать тестовые устройства: debug-сборки по умолчанию скрыты.
• Всё равно ничего? Настройте с UnolinkOptions(logLevel = LogLevel.DEBUG) и отфильтруйте Logcat по Unolink. Неверный или отозванный ключ записывается в лог как ошибка.
• Нет диплинка? Он приходит только для установок из Google Play по ссылке Unolink с заданным диплинком, при первом запуске. Переустановите приложение, чтобы проверить снова, или используйте debugInstallReferrer.

Подробнее в разделе Решение проблем.