Установка и инициализация

Tracehub Android SDK отслеживает установки, сессии, события, доход, подписки и диплинки вашего приложения. Эта страница — путь от подключения зависимости до первой отправленной сессии.

SDK написан на Kotlin, но Kotlin в вашем приложении не требуется — Java-проекты поддерживаются полностью. Примеры здесь — на Kotlin; варианты на Java есть в README репозитория SDK (входит в поставку).

Требования

Компонент	Минимальная версия
Android	API 21 (Android 5.0)
Java	8+ (Kotlin в приложении не требуется)
Android Gradle Plugin	8.0
Target SDK	рекомендуется 34+

Подключение репозитория

SDK поставляется архивом с офлайн Maven-репозиторием (папка maven-repo) — архив выдаёт Tracehub при подключении. Распакуйте архив, положите папку maven-repo в удобное место и добавьте репозиторий в settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("/путь/к/maven-repo") }
        google()
        mavenCentral()
    }
}

Транзитивные зависимости (OkHttp, kotlinx-coroutines, Install Referrer, Play Services Ads Identifier) подтянутся из google() / mavenCentral().

Зависимости

Рекомендуемый способ — BOM: версии всех артефактов SDK фиксируются в одном месте.

dependencies {
    implementation(platform("com.tracehub.sdk:sdk-bom:1.0.0"))
    implementation("com.tracehub.sdk:sdk-core")
}

Без BOM укажите версию каждого артефакта вручную: implementation("com.tracehub.sdk:sdk-core:1.0.0").

Транзитивные зависимости

Библиотеки для чтения идентификаторов устройства и реферера установки Google Play приезжают транзитивно — объявлять их в build.gradle своего приложения не нужно:

Библиотека	Зачем нужна
com.google.android.gms:play-services-ads-identifier	Чтение Google Advertising ID (GAID)
com.android.installreferrer:installreferrer	Чтение реферера установки Google Play при первой сессии
kotlinx-coroutines-android	Асинхронность SDK

Если сборка не должна тянуть Play Services (AOSP-only, privacy-варианты), исключите Google-зависимость явно:

implementation("com.tracehub.sdk:sdk-core") {
    exclude(group = "com.google.android.gms", module = "play-services-ads-identifier")
}

При исключённом GAID SDK перейдёт на android_id и один раз напишет WARN в Logcat. Остальные механизмы атрибуции продолжат работать.

Разрешения

Разрешения android.permission.INTERNET и android.permission.ACCESS_NETWORK_STATE объявлены в манифесте SDK и мержатся в манифест приложения автоматически — копировать их не нужно, но и удалять через tools:node="remove" нельзя.

Разрешение `AD_ID` SDK намеренно не объявляет

На Android 13+ (API 33) для чтения Google Advertising ID нужно разрешение com.google.android.gms.permission.AD_ID. Если оно нужно вашему приложению — добавьте его в свой AndroidManifest.xml сами. SDK не делает этого за вас, потому что иначе каждое приложение с SDK было бы обязано отвечать «собираем Advertising ID» в форме Data Safety Google Play, а приложения для детей получали бы отказ при публикации.

<manifest ...>
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
</manifest>

Без этого разрешения на API 33+ SDK один раз за сессию напишет WARN и перейдёт на android_id. Приложениям для детей и приложениям в privacy-ориентированных магазинах разрешение добавлять не нужно — никаких правок SDK не требуется.

Плагины

Плагины расширяют SDK дополнительными источниками реферера установки и идентификаторами устройств. Добавляйте только те, что реально используете.

Плагины регистрируются до `Tracehub.initSdk()`

Плагины подключаются в TracehubConfig.Builder (addInstallReferrerPlugin / addDeviceInfoPlugin / setFbAppId) до инициализации SDK — иначе данные плагина не попадут в первую сессию.

Плагины реферера установки по магазинам

Реферер Google Play SDK читает сам — плагин не нужен. Для остальных магазинов:

Магазин / источник	Плагин	Доп. зависимости	Регистрация
Meta (Facebook/Instagram)	sdk-plugin-meta-referrer	—	.setFbAppId("ВАШ_FB_APP_ID") в конфигурации; плагин активируется автоматически
Huawei AppGallery	sdk-plugin-huawei-referrer	—	.addInstallReferrerPlugin(HuaweiReferrerPlugin()) в конфигурации
Samsung Galaxy Store	sdk-plugin-samsung-referrer	store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:3.0.1 (есть в mavenCentral())	.addInstallReferrerPlugin(SamsungReferrerPlugin()) в конфигурации
Vivo V-Appstore	sdk-plugin-vivo-referrer	—	.addInstallReferrerPlugin(VivoReferrerPlugin()) в конфигурации
Xiaomi GetApps	sdk-plugin-xiaomi-referrer	com.miui.referrer:homereferrer:1.0.0.6	.addInstallReferrerPlugin(XiaomiReferrerPlugin()) в конфигурации
RuStore	sdk-plugin-rustore-referrer	VK Partner Maven-репозиторий + ru.rustore.sdk:installreferrer:10.0.0	.addInstallReferrerPlugin(RuStoreReferrerPlugin()) в конфигурации

Библиотека Samsung лежит в mavenCentral() — отдельный репозиторий для неё не нужен. Для RuStore добавьте репозиторий в settings.gradle.kts:

maven { url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven") }

Дополнительные зависимости вендоров не включены в плагины (объявлены compileOnly или загружаются в рантайме) — добавляйте их в приложение явно. Если подключить плагин без такой зависимости, он один раз напишет WARN в Logcat и вернёт пустой результат; атрибуция продолжит работать через другие источники. Декларации <queries> для Android 11+ мержатся в манифест из плагинов автоматически.

Особенности RuStore: плагин вернёт пустой результат, если установка прошла без referrerId, реферер уже был получен ранее или с момента получения клика RuStore прошло больше 10 дней. Диагностика — в Logcat с тегом TracehubRuStoreReferrer.

Плагин OAID

Open Anonymous Device Identifier — альтернатива GAID на китайских Android-устройствах. Плагин sdk-plugin-oaid читает OAID через Huawei HMS:

• репозиторий https://developer.huawei.com/repo/ в settings.gradle.kts;
• зависимость com.huawei.hms:ads-identifier:3.4.56.300 в приложении (в плагине она compileOnly).

Маршрут через MSA SDK (не-Huawei китайские OEM) в плагин не входит — для него понадобится собственный DeviceInfoPlugin, см. «Собственные плагины» ниже.

Регистрация — в конфигурации, до инициализации SDK:

val config = TracehubConfig.Builder(...)
    .addDeviceInfoPlugin(OaidPlugin())
    .build()
Tracehub.initSdk(config)

Плагин WebBridge

sdk-plugin-webbridge открывает API SDK для JavaScript-кода внутри WebView: инициализация, события, рекламный доход, согласия, глобальные параметры и чтение атрибуции доступны из веб-слоя.

val bridge = TracehubBridge.register(application, webView)
webView.loadUrl("https://yourapp.example.com")

Плагин Google Play License Verification

sdk-plugin-google-lvl запрашивает лицензионный сервис Google Play и прикладывает подписанный ответ к пакетам SDK — дополнительный сигнал против фрода. Требует разрешения com.android.vending.CHECK_LICENSE в манифесте приложения; регистрируется через .addDeviceInfoPlugin(TracehubLicenseVerification()).

Собственные плагины

Для нестандартных источников реферера и дополнительных параметров устройства есть интерфейсы InstallReferrerPlugin и DeviceInfoPlugin (для Java — callback-варианты JavaInstallReferrerPlugin / JavaDeviceInfoPlugin). Примеры — в README репозитория SDK.

Инициализация

Инициализируйте SDK в Application.onCreate() — до любого другого обращения к его API. Токен приложения (appToken) — в кабинете Tracehub на карточке приложения, см. страницу Быстрый старт.

import com.tracehub.sdk.Tracehub
import com.tracehub.sdk.TracehubConfig
import com.tracehub.sdk.Environment
import com.tracehub.sdk.LogLevel

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        val config = TracehubConfig.Builder(
            context     = this,
            appToken    = "ВАШ_APP_TOKEN",
            environment = Environment.PRODUCTION,  // для тестирования — Environment.SANDBOX
        )
            .setLogLevel(LogLevel.INFO)
            .build()

        Tracehub.initSdk(config)
    }
}

Класс Application нужно зарегистрировать в AndroidManifest.xml — иначе Android его не создаст, onCreate() не выполнится и SDK не инициализируется. Ошибки в Logcat при этом не будет: приложение работает как обычно, просто установки и события не отправляются.

<application android:name=".MyApplication">

Если класс Application в приложении уже есть, второй заводить не нужно — добавьте инициализацию в его onCreate().

В отладочных сборках указывайте Environment.SANDBOX.

Для разработки и тестирования заведите отдельное приложение

Создайте в кабинете второе приложение — например «MyApp Test» — и укажите его токен в отладочных сборках. Так проверки не смешаются с боевыми цифрами вашего приложения.

По тестовым событиям тоже отправляются постбэки

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

Не храните токен строкой в коде

Особенно в публичных репозиториях. Загружайте его из поля BuildConfig или менеджера секретов.

Перед боевым релизом включите HMAC-подпись запросов — она подтверждает, что трафик приходит именно из вашего приложения; события с невалидной подписью отбраковываются антифродом. Подробности — см. страницу Android SDK: справочник конфигурации.

Сессии

Сессии отслеживаются автоматически — SDK нужно лишь сообщать о жизненном цикле приложения. Вызывайте onResume и onPause из каждого Activity; удобнее всего — через базовый класс:

abstract class BaseActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        Tracehub.onResume()
    }

    override fun onPause() {
        super.onPause()
        Tracehub.onPause()
    }
}

Именно эти вызовы управляют определением сессий: новая сессия начинается, когда приложение возвращается на передний план после более чем 30 минут в фоне.

Размер приложения

Артефакт	AAR	Байткод	Классов
sdk-core	362 КБ	860 КБ	214
sdk-plugin-google-lvl	20 КБ	39 КБ	14
sdk-plugin-webbridge	12 КБ	27 КБ	3
sdk-plugin-meta-referrer	8 КБ	13 КБ	4
sdk-plugin-oaid	5 КБ	8 КБ	3

Плагины — тонкие адаптеры над вендорным IPC или JS-мостом. Даже со всеми девятью подключёнными плагинами прибавка к байткоду — меньше 165 КБ поверх sdk-core.

Следующие шаги

• Отправка событий и дохода — см. страницу Android SDK: события и доход.
• Обработка диплинков и чтение атрибуции — см. страницу Android SDK: диплинки и атрибуция.
• Согласия и работа с идентификаторами — см. страницу Android SDK: приватность и идентификаторы.

---