События и доход

Как отправлять события из приложения: простые события, события с доходом, подписки и рекламный доход.

Токен события

Событие идентифицируется токеном — строкой, которую вы придумываете сами (например, purchase или tutorial_complete).

Карточка события появляется в каталоге сама — обычно через несколько секунд после первой отправки из SDK; завести событие заранее нельзя. Если карточки нет, обновите страницу; иногда она появляется только после следующей отправки того же события.

Простое событие

Tracehub.trackEvent(TracehubEvent(eventToken: "tutorial_complete"))

Событие с доходом

let event = TracehubEvent(eventToken: "purchase")
event.setRevenue(4.99, currency: "USD")
Tracehub.trackEvent(event)

Покупку из App Store отправляйте тем же способом: укажите сумму и валюту, а идентификатор транзакции передайте в deduplicationId — см. «Дедупликация».

Дедупликация

Чтобы одно и то же событие (например, повторно доставленная транзакция) не посчиталось дважды, задайте deduplicationId:

let event = TracehubEvent(eventToken: "purchase")
event.setRevenue(4.99, currency: "USD")
event.deduplicationId = order.id
Tracehub.trackEvent(event)

Буфер дедупликации — 10 идентификаторов

SDK хранит кольцевой буфер последних 10 deduplicationId и отбрасывает события с уже виденным идентификатором. Повтор, пришедший после десяти других событий с дедупликацией, отсечён не будет. Размер буфера можно изменить полем config.eventDeduplicationIdsMaxSize (по умолчанию 10).

Параметры события

К событию можно добавить произвольные пары «ключ — значение» двух видов — callback-параметры и partner-параметры:

let event = TracehubEvent(eventToken: "level_up")
event.addCallbackParameter(key: "level",     value: "12")
event.addCallbackParameter(key: "character", value: "mage")
event.addPartnerParameter(key: "segment",    value: "power_user")
Tracehub.trackEvent(event)

Оба набора уходят на серверы Tracehub вместе с событием и сейчас обрабатываются одинаково. Что с ними можно делать в кабинете:

Где	Что доступно
Раздел «События»	ключи и типы отправленных параметров (диалог «Параметры события», только чтение)
Отчёты	фильтр и разбивка по параметру — после включения у него переключателя «Индексировать»
Постбэки	параметры не подставляются
Выгрузка из кабинета (раздел «Экспорт»)	параметры не попадают

Индексация не покрывает историю: по значениям, отправленным до включения «Индексировать», фильтровать и группировать не получится.

S2S API не передаёт дополнительные параметры события

Событие, отправленное серверным API, доходит до кабинета без них — ни фильтра, ни разбивки по таким параметрам не будет. Если значение важно для аналитики, отправляйте это событие из SDK или закладывайте его в токен события.

Идентификатор обратного вызова

callbackId — ваша метка конкретной отправки; она вернётся в обратном вызове успеха:

let event = TracehubEvent(eventToken: "checkout")
event.callbackId = "order-\(orderId)"
Tracehub.trackEvent(event)

Обратные вызовы успеха и ошибки

config.eventSuccessCallback = { result in
    print("Событие '\(result.eventToken)' отправлено, thid: \(result.thid ?? "-")")
    print("callbackId: \(result.callbackId ?? "-")")
}
config.eventFailureCallback = { failure in
    print("Ошибка события '\(failure.eventToken)', повтор: \(failure.willRetry)")
}

Глобальные параметры

Глобальные параметры автоматически добавляются ко всем сессиям и событиям — удобно для сквозных меток вроде идентификатора пользователя или группы A/B-теста:

Tracehub.addGlobalCallbackParameter("u123456", forKey: "user_id")
Tracehub.addGlobalPartnerParameter("premium", forKey: "segment")

Tracehub.removeGlobalCallbackParameter(forKey: "user_id")
Tracehub.removeAllGlobalCallbackParameters()

Tracehub.removeGlobalPartnerParameter(forKey: "segment")
Tracehub.removeAllGlobalPartnerParameters()

Подписки

Подписку через App Store отправляйте отдельным вызовом trackSubscription:

let sub = TracehubSubscription(
    revenue:       4.99,
    currency:      "USD",
    transactionId: transaction.transactionIdentifier
)
sub.transactionDate = transaction.transactionDate.map {
    ISO8601DateFormatter().string(from: $0)
}
sub.salesRegion = Locale.current.region?.identifier
sub.addCallbackParameter(key: "plan", value: "monthly")
Tracehub.trackSubscription(sub)

Рекламный доход

Доход от показов рекламы передавайте через trackAdRevenue:

let adRevenue = TracehubAdRevenue(source: "admob_sdk")
adRevenue.revenue            = 0.0045
adRevenue.currency           = "USD"
adRevenue.adImpressionsCount = 1
adRevenue.adRevenueNetwork   = "AdMob"
adRevenue.adRevenueUnit      = "banner_home"
adRevenue.adRevenuePlacement = "top"
adRevenue.addCallbackParameter(key: "ad_type", value: "banner")
Tracehub.trackAdRevenue(adRevenue)

Распространённые значения source: "admob_sdk", "applovin_max_sdk", "ironsource_sdk", "topon_sdk", "tradplus_sdk", "unity_level_play_sdk", "publisher_defined".

---