Справочник конфигурации

Все параметры TracehubConfig.Builder и runtime-методы управления SDK на одной странице: состояние, чтение значений, push-токен, собственные домены, HMAC-подпись и TLS-пиннинг.

Параметры Builder

Все параметры задаются до вызова .build().

Обязательные

Метод	Описание
Builder(context, appToken, environment)	Контекст приложения, токен приложения и окружение: Environment.PRODUCTION или Environment.SANDBOX

Логирование

Метод	По умолчанию	Значения
setLogLevel(LogLevel)	INFO	VERBOSE, DEBUG, INFO, WARN, ERROR, SUPPRESS

Слушатели

Метод	Когда вызывается
setOnAttributionChangedListener { attr -> }	При получении или изменении данных атрибуции
setOnSessionTrackingSucceededListener { s -> }	После успешной отправки сессии
setOnSessionTrackingFailedListener { f -> }	При ошибке отправки сессии
setOnEventTrackingSucceededListener { e -> }	После успешной отправки события
setOnEventTrackingFailedListener { f -> }	При ошибке отправки события
setOnDeferredDeeplinkResponseListener { url -> true }	При получении отложенного диплинка; верните true, чтобы SDK открыл ссылку

Идентификаторы

Метод	Описание
setExternalDeviceId("deviceId")	Привязать собственный идентификатор устройства ко всем запросам
setCustomerUserId("userId")	Привязать идентификатор пользователя в вашей системе — ключ связывания устройств одного человека
setDefaultTracker("XYZ123")	Предустановить токен трекера для органических установок
disableAppSetIdReading()	Отключить чтение Android App Set ID
enableDeviceIdsReadingOnce()	Читать GAID только один раз за жизненный цикл SDK

customerUserId

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

// после успешного входа
Tracehub.setCustomerUserId("user-uuid")

// при выходе из учётной записи
Tracehub.clearCustomerUserId()

Значение уходит со всеми последующими запросами SDK и не сохраняется между запусками приложения — задавайте его заново при каждом старте, как только идентификатор известен. clearCustomerUserId() снимает и значение, заданное в TracehubConfig: разлогиненное устройство не должно сообщать прежнего пользователя.

Соответствие требованиям

Метод	Описание
enableCoppaCompliance()	Отключить сбор GAID — для приложений, предназначенных детям до 13 лет
enablePlayStoreKidsCompliance()	Отключить сбор GAID — для приложений в разделе «Для семьи» Google Play
enableFirstSessionDelay()	Не отправлять первую сессию до вызова Tracehub.endFirstSessionDelay() или истечения таймаута (по умолчанию 5 минут)

Сеть и безопасность

Метод	Описание
setUrlStrategyDomains(domains, useSubdomains, isDataResidency)	Переопределить домены эндпоинтов SDK
setSendingInBackground(true)	Продолжать отправку очереди в фоне
setHmacSecretKey("secret")	Подписывать каждый запрос HMAC-SHA256 — см. раздел «HMAC-подпись запросов» ниже
setTlsConfig(TracehubTlsConfig)	TLS-пиннинг публичного ключа и/или дополнительные корневые сертификаты
disableTlsPinning()	Отключить пиннинг (собственные trust-anchors остаются активными)

Данные атрибуции и дистрибуция

Метод	Описание
setStoreInfo(TracehubStoreInfo)	Название и ID магазина для дистрибуции не через Google Play
setSdkPrefix("unity4.38.0")	Префикс SDK в запросах (для SDK-обёрток)

Управление состоянием

Tracehub.disable()   // остановить отслеживание
Tracehub.enable()    // возобновить отслеживание

При выключенном SDK события не учитываются

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

В режиме офлайн SDK накапливает пакеты локально и не отправляет их; при возврате в онлайн очередь отправляется в порядке поступления:

Tracehub.setOfflineMode(true)      // накапливать, не отправлять
Tracehub.setOfflineMode(false)     // отправить очередь и продолжить как обычно

Псевдонимы: switchToOfflineMode() / switchBackToOnlineMode().

Чтение значений SDK

Все геттеры асинхронные, обратные вызовы выполняются в фоновом потоке:

Tracehub.isEnabled { enabled -> }                          // включено ли отслеживание
Tracehub.getSdkVersion { version -> }                      // версия SDK, например "android1.0.0"
Tracehub.getThid { thid -> }                               // идентификатор устройства Tracehub (null, если ещё не получен)
Tracehub.getThidWithTimeout(timeoutMs = 5_000L) { thid -> }
Tracehub.getAttribution { attr -> }                        // см. страницу [Android SDK: диплинки и атрибуция](/sdk/android/deeplinks/)
Tracehub.getGoogleAdId { gaid -> }                         // GAID (требует Play Services)
Tracehub.getAmazonAdId { amzid -> }                        // Amazon Advertising ID
Tracehub.getLastDeeplink { uri -> }                        // последний обработанный диплинк

Детали реферера Google Play читаются через Tracehub.getGooglePlayInstallReferrer(context, listener).

Push-токен

SDK принимает push-токен устройства — передавайте его при каждом обновлении от Firebase:

class MyFirebaseMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        Tracehub.setPushToken(token)
    }
}

Отчёт по удалениям приложения сейчас недоступен

SDK принимает push-токен устройства методом setPushToken; метрика удалений в кабинете не рассчитывается. Вызов безопасен и на другие данные не влияет — учитывайте это, когда планируете состав метрик.

Собственные домены

Весь трафик SDK можно направить через свой домен — например, через прокси в вашем контуре:

TracehubConfig.Builder(...)
    .setUrlStrategyDomains(
        domains         = listOf("analytics.eu.mycompany.com"),
        useSubdomains   = false,
        isDataResidency = true,
    )

При isDataResidency = true SDK шлёт трафик только на указанные домены — резервного переключения на стандартные домены Tracehub нет. При isDataResidency = false указанные домены используются первыми, а стандартный домен Tracehub остаётся резервным на случай их недоступности.

Адрес эндпоинта не определяет место хранения данных

Флаг isDataResidency управляет только выбором домена, по которому SDK отправляет запросы. Региональные префиксы в адресах (eu., us., in.) — часть исторической схемы доменов и на хранение не влияют. Условия хранения и обработки данных зафиксированы в договоре с Tracehub — если у вас есть требования к юрисдикции хранения, согласуйте их до начала интеграции.

HMAC-подпись запросов

При включении каждый исходящий запрос SDK несёт заголовок X-Tracehub-Signature, подписанный HMAC-SHA256. Секрет никогда не передаётся по сети — только дайджест.

Включите перед боевым релизом

Сервер Tracehub проверяет подпись: события с невалидной подписью отбраковываются антифродом, а запрос с неверной подписью может быть отклонён с кодом HTTP 401. Считайте setHmacSecretKey обязательным шагом интеграции, а не опцией.

Секрет — в кабинете Tracehub: раздел «Приложения» → карточка приложения → вкладка «SDK». Секрет выдаётся на приложение и является приватным: не встраивайте его в веб-страницы и не делите между приложениями.

Кто	Что может
Владелец, администратор организации	Выпустить секрет и перевыпустить его
Остальные участники, в том числе внешние (агентства)	Только увидеть значение секрета, если есть доступ к приложению

Секрет виден всем, у кого есть доступ к приложению

Внешний участник не может сменить секрет, но видит его значение — учитывайте это, когда выдаёте агентству доступ к приложению.

TracehubConfig.Builder(context, "ВАШ_APP_TOKEN", Environment.PRODUCTION)
    .setHmacSecretKey("ваш-секрет")
    .build()

Формат заголовка:

X-Tracehub-Signature: v1:{appToken}:{unixTimestampSecs}:{hexSignature}

Ротация: новый ключ начинает действовать сразу после перевыпуска в кабинете, старый работает ещё 48 часов — выпустите обновление приложения с новым ключом в это окно, и трафик не потеряется. Обращаться в поддержку для выпуска или смены секрета не нужно. SDK читает ключ один раз при инициализации, поэтому ротация вступает в силу при следующем запуске приложения с обновлённой сборкой.

Что учесть при внедрении:

• Запрос с невалидной подписью отклоняется с кодом 401 и повторно не отправляется. Проверьте секрет на тестовом устройстве до релиза: с неверным или устаревшим ключом события в кабинет не попадут.
• Если системные часы устройства расходятся с серверными больше допуска (по умолчанию 5 минут), запросы будут отклоняться до восстановления времени.
• В гибридных (WebView) интеграциях подпись задаётся в нативной конфигурации SDK вызовом setHmacSecretKey; из JavaScript через WebBridge этот параметр не передаётся.

TLS-пиннинг публичного ключа

Пиннинг привязывает HTTPS-соединения SDK к конкретному набору SHA-256-отпечатков публичных ключей (SPKI) — скомпрометированный корневой сертификат в хранилище устройства не поможет злоумышленнику перехватить трафик SDK. Пиннинг выключен по умолчанию: без setTlsConfig(...) SDK доверяет системному хранилищу сертификатов Android.

TracehubTlsConfig даёт два независимых механизма:

Механизм	Метод	Роль
Trust-anchors	addTrustAnchorFromPem(pem) / addTrustAnchorFromDer(der)	Добавить CA-сертификаты, которых нет в Android, — прежде всего корень Минцифры (Russian Trusted Root CA)
Пины ключей	addHostPin(host, primary, backup)	Требовать в цепочке сервера один из двух указанных SPKI-отпечатков

val tls = TracehubTlsConfig.Builder()
    .addHostPin(
        "*.tracehub.ru",
        primarySpki = "sha256/ОСНОВНОЙ_ОТПЕЧАТОК=",
        backupSpki  = "sha256/РЕЗЕРВНЫЙ_ОТПЕЧАТОК=",
    )
    .build()

TracehubConfig.Builder(context, "ВАШ_APP_TOKEN", Environment.PRODUCTION)
    .setTlsConfig(tls)
    .build()

Маска *.tracehub.ru покрывает ровно одну метку поддомена — рабочие эндпоинты SDK.

В примере выше стоят условные значения: отпечатки вычисляются на вашей стороне. Снимите отпечаток с нужного хоста этой командой:

openssl s_client -servername app.tracehub.ru -connect app.tracehub.ru:443 \
    < /dev/null 2>/dev/null \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform der \
  | openssl dgst -sha256 -binary \
  | base64

Пиннинг требует сопровождения — включайте его осознанно

Сертификаты эндпоинтов Tracehub регулярно обновляются вместе с промежуточными сертификатами в цепочке, в том числе внепланово. Перепроверяйте отпечатки перед каждым релизом и всегда задавайте резервный пин (backupSpki). Если пины разойдутся с цепочкой сервера, SDK потеряет связь до выхода обновления приложения. Функция необязательная и по умолчанию выключена — включайте её, если в команде есть процесс отслеживания смены сертификатов и оперативного выпуска обновлений.

Для окружений, несовместимых с пиннингом (корпоративные прокси с инспекцией трафика, отладочные прокси под MDM), используйте .disableTlsPinning() — он выключает проверку пинов, но сохраняет добавленные trust-anchors, поэтому хосты с сертификатами Минцифры продолжают работать. При отключённом пиннинге с настроенными пинами SDK пишет WARN при инициализации.

Корень Минцифры не входит в Android

Если эндпоинт отдаёт сертификат, выпущенный Минцифры, без addTrustAnchorFromPem(...) соединение упадёт с SSLHandshakeException ещё до проверки пинов. Положите корневой сертификат в ресурсы приложения и добавьте его якорем доверия.