Tracking SDK Standard Android

Tracking SDK Standard (SDK) используется для отслеживания целевых действий пользователя в мобильном приложении и дальнейшего анализа этой информации.

Прежде чем начать

Вам должны быть известны следующие параметры, необходимые для инициализации и использования SDK. Попросите команду SDK выдать их вам.

partnerId - идентификатор партнёра. Например: 123.
endpointUrl - URL API рекламной системы. Например: "https://my.server.com/event".

SDK версия:

Демо приложение: Tracking SDK Example

Репозиторий со стабильным релизом: Tracking SDK Standard

Требования

Kotlin version >= 1.6.20
Android 5.0+ (API Level >= 21)

Установка

kotlin

dependencies {
    //... other dependencies
    implementation 'tech.solutionarchitects.tracking_sdk:standard:{{ version }}'
    
    //... other dependencies
}

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

Инициализация библиотеки выполняется разработчиком в момент запуска приложения или в момент авторизации пользователя вызовом метода TechTracker.initialize(options: TrackerOptions) и передачей в него подготовленного объекта TrackerOptions.

Обратите внимание

SDK имеет доступ только к основному процессу приложения. Если ваше приложение работает с использованием нескольких процессов, зарегистрируйте Сontent Provider SDK, для получения ApplicationContext:

xml

<application>
    <provider
        android:name=".api.context.TechTrackerContextProvider"
        android:authorities="${applicationId}.api.context.TechTrackerContextProvider"
        android:exported="true" />
</application>

code exampletypes

kotlin

val options = TrackerOptions(
    bundle = "my.company.example.app",
    partnerId = "YOUR_PARTNER_ID",
    sessionId = "YOUR_SESSION_ID",
    endpointUrl = "https://YOUR_END_POINT",
    debugMode = true,
    headers = mapOf("Authorization" to {
        "Bearer YOUR_AUTHORIZATION_TOKEN"
    }
)
val tracker = TechTracker.initialize(options)

kotlin

TechTracker.initialize(options: TrackerOptions): TechTracker

data class TrackerOptions(
    val bundle: String,
    val partnerId: String,
    val sessionId: String,
    val endpointUrl: String,
    val debugMode: Boolean = false,
    val headers: Map<String, () -> String>? = null
)

bundle - уникальный идентификатор приложения из маркета.
partnerId - Partner ID. Например: 123. Попросите команду SDK выдать это значение вам.
endpointUrl - API URL системы трэкинга. Например: https://my.server.com/event. Попросите команду SDK выдать это значение вам.
sessionId - Уникальный идентификатор сессии, который определяет текущую сессию приложения. Мобильное приложение можно отнести к одному из след. типов:
- Online приложение (ваше приложение использует ваш backend, серверную часть для хранения и доступа к данным) - в этом случае, в качестве значения, используйте ID сессии, которая соответствует сессии на стороне вашей серверной части - это наиболее предпочтительный вариант значения.
- Offline приложение (ваше приложение не использует ваш собственный backend, все бизнес данные хранятся локально). В этом случае у вас нет никакой сессии на серверной стороне. При таком сценарии, можно использовать сгенерированный UUID в качестве значения. ВАЖНО: UUID значение должно генерироваться один раз на моменте старта приложения и не меняться пока приложение остается в памяти. Вы не должны перегенерировать UUID в течении жизненного цикла приложения. Новое значение допустимо только, после удаления вашего приложения из памяти, после нового рестарта приложения.
debugMode - Включает или отключает режим отладки внутри SDK. По умолчанию false. Когда включен, SDK выводит дополнительную информацию в log output консоль.
httpHeaders - (необязательный) Справочник (Map) HTTP заголовков, которые будут вставлены в каждый API вызов, когда вы запускаете TechTracker.event(event: TrackerEvent) метод.

Примечание

Если вы попытаетесь получить доступ к любому методу SDK без инициализации, то будет брошено исключение InitializeException: RuntimeException. Это исключение указывает разработчикам хоста, что они могут использовать SDK только после успешной инициализации.

User ID (UID)

Ваше мобильное приложение может быть:

Anonymous (публичное - не требующее для доступа к функционалу авторизации пользователя). Например: любой пользователь, установивший приложение может воспользоваться всем функционалом, без необходимости регистрировать и аккаунт и без необходимости проходить авторизацию для доступа ко всему функционалу вашего приложения.
AuthN/AuthZ (пользователь должен иметь аккаунт и пройти авторизацию для доступа к функционалу). Например: При старте приложения, пользователь видит 'Sign-in' форму в которой вводит свой логин / пароль. Пока не пройдет авторизацию, пользователь не может зайти на другие экраны.
Комбинированное приложение (часть экранов/функционала доступна пользователю без авторизации, когда как другая часть только после прохождения таковой). Например: Любой не авторизованный пользователь может просматривать каталог продукции, переходить между карточками товаров. Но в случае, если он хочет оформить заказ, то приложение просит пройти авторизацию (Sign-in / Sign-up формы) - и только после этого пользователь сможет заказать товар.

ВАЖНО

Tracking SDK предоставляет TechTracker.uid свойство, которое должно заполняться значением уникального идентификатора пользователя, прошедшего авторизацию.

Установите значение этого поля при каждой успешной попытке авторизации пользователя в вашем приложении.

Вы должны установить null значение, на каждую попытку завершения авторизованной сессии ('Sign-out').

Вы можете ничего не устанавливать в данное поле (полностью его игнорировать), только в одном сценарии: если ваше приложение является Anonymous (публичным) и не требует вообще никакой авторизации пользователей для работы.

Ниже приведен примеры кода в какие моменты и какое значение нужно устанавливать внутри TechTracker.uid свойства:

code exampletypes

kotlin

try {
    val authSession = myAuthService.signIn(username, password)
    if (!authSession.success) {
        tracker.uid = null
        return
    }
    
    tracker.uid = authSession.user.id
    
    // Здесь вы выполняете бизнес логику, специфичную для вашего приложения, когда пользователь 
    // успешно прошел авторизацию.
    // Например: Переход на 'Главный' экран, или навигация в 'Корзину' для оформления заказа и т.п.
} catch (e: Exception) {
    tracker.uid = null
    Log.e(TAG, "ERROR: Unable to sign-in due error", e)
}

try {
    myAuthService.signOut()
} catch (e: Exception) {
    Log.w(TAG, "WARNING: Error occured while sign-out (skipped)", e)
} finally {
    tracker.uid = null
    
    // Пользователь завершил авторизованную сессию ('Sign-out') - здесь вы выполняете вашу бизнес логику, специфичную для этого.
    // Например: Приложение переходит на экран 'Sign-in' (стартовый экран), и т.п.
}

kotlin

object TechTracker {
    var uid: String?
}

uid - (необязательный) Уникальный идентификатор пользователя, прошедшего успешную авторизацию внутри вашего приложения. Устанавливайте это значение в null при каждом завершении авторизации пользователя 'Sign-out'. Можете игнорировать это свойство, если ваше приложение является Anonymous (вообще не использует авторизацию по пользователям).

Отслеживаемые события

Tracking SDK предоставляет API для отправки определенных событий. Для отправки события, вам необходимо передать event объект в качестве параметра при вызове метода TechTracker.event(event: TrackerEvent).

Пример:

code exampletypes

kotlin

val event = Click(
    value = "start registration",
    contentId = "1",
    contentName = "Doll",
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

fun event(event: TrackerEvent)

event - Объект 'событие', которое вы хотите отслеживать (tracking) в вашем приложении. См. Стандартные события.

Стандартные события

Вы можете отправлять (tracking) следующие виды событий:

AddToCart - добавление пользователем товарных позиций в корзину в приложении
Purchase - совершение пользователем покупки каких-либо товарных позиций в приложении
StartView - начало просмотра пользователем контента
StopView - завершение просмотра пользователем контента
Click - нажатие на значимый элемент в приложении (ссылки, кнопки, карточка продукта в списке продуктов и т.д.)
Search - выполнение поиска пользователем (например, поиск товара)
AdImp - просмотр рекламного баннера пользователем
AdClick - нажатие пользователем на рекламный баннер
Scroll - пользователь прокрутил страницу контента

AddToCart

Триггер: добавление пользователем товарных позиций в корзину в приложении.
Данные: список товарных позиций, которые добавляются в корзину.

code exampletypes

kotlin

val event = AddToCart()
event.add(AddToCartItem(
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    deltaQuantity = 1.0F,
    quantity= 2.0F,
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
))
event.add(AddToCartItem(
    sku = SKU(
        skuId = "2",
        skuName = "Ozone"
    ),
    deltaQuantity = 1.0F,
    quantity= 2.0F
))
tracker.event(event)

kotlin

data class AddToCartItem(
    val sku: SKU,
    val deltaQuantity: Float,
    val quantity: Float,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CustomParamsAwareEvent

sku - объект, описывающий товарyную позицию (см. SKU)
deltaQuantity - разница (прибавка или убавка) между текущим количеством товара и новым количеством товара
quantity - количество товара
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

Purchase

Триггер: совершение пользователем покупки каких-либо товарных позиций в приложении.
Данные: список товарных позиций, которые были куплены пользователем.

code exampletypes

kotlin

val event = Purchase()
event.add(PurchaseItem(
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    quantity= 2.0F,
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                        categoryId = "11",
                        categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
))
event.add(PurchaseItem(
    sku = SKU(
        skuId = "2",
        skuName = "Ozone"
    ),
    quantity= 2.0F
))
tracker.event(event)

kotlin

data class PurchaseItem(
    val sku: SKU,
    val quantity: Float,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CustomParamsAwareEvent

sku - объект, описывающий товарyную позицию (см. SKU)
quantity - количество товара
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

StartView

Триггер: начало просмотра пользователем контента.
Данные: список объектов контента, который просматривается пользователем.

Внимание

Если текущий просматриваемый контент является страницей каталога ( например список тизеров товаров ), то НЕ нужно отправлять событие просмотра для каждого представленного в этом каталоге тизера другого контента/товара. Событие просмотра контент должно быть отправлено один раз и только для самого каталога.

code exampletypes

kotlin

val event = StartView(
    contentId = "1",
    contentName = "Lego",
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class StartView(
    val contentId: String,
    val contentName: String,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

contentId - уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - наименование просматриваемого контента
sku - (необязательный) объект, описывающий товарную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

StopView

Триггер: завершение просмотра пользователем контента.
Данные: список объектов контента, который просматривался пользователем.

Внимание

code exampletypes

kotlin

val event = StopView(
    contentId = "1",
    contentName = "Lego",
    value = 0.5F,
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class StopView(
    val contentId: String,
    val contentName: String,
    val value: Float,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

contentId - уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - наименование просматриваемого контента
value - значение от 0 до 1, описывающее сколько контента было просмотрена в процентах
sku - (необязательный) объект, описывающий товарyную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

Click

Триггер: нажатие на значимый элемент в приложении (ссылки, кнопки, карточка продукта в списке продуктов и т.д.).
Данные: объект c описанием того, по какому элементу было произведено нажатие ( URL для внешних ссылок ).

Подсказка

Если действие нажатия на элемент аналогично какому-либо из специализированных событий, то лучше использовать специализированное событие. Например для отслеживания нажатия по кнопкам корзины продуктов, необходимо использовать тип события Добавление товара в корзину / Покупка товара.

code exampletypes

kotlin

val event = Click(
    value = "start registration",
    contentId = "1",
    contentName = "Lego",
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class Click(
    val value: String,
    val contentId: String,
    val contentName: String,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

value - строка c описанием того, по какому элементу был произведен клик ( урл для внешних ссылок ).
contentId - уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - наименование просматриваемого контента
sku - (необязательный) объект, описывающий товарyную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

Search

Триггер: выполнение поиска пользователем (например, поиск товара).
Данные: объект со значением поисковой фразы.

code exampletypes

kotlin

val event = Search(
    value = "Pampers",
    filter = mapOf(
        "age" to listOf("0-1", "1-3"),
        "sex" to listOf("m")
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class Search(
    val value: String,
    val filter: Map<String, List<String>>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

value - поисковая фраза
filter - (необязательный) поисковые фильтры
customParams - (необязательный) пользовательские дополнительные параметры

AdImp

Триггер: просмотр рекламного баннера пользователем.
Данные: объект с описанием рекламного блока, который просматривался пользователем.

code exampletypes

kotlin

val event = AdImp(
    placementId = "1",
    width = 240,
    height = 300,
    clickURL = "https://test.com",
    adType = AdType.banner,
    contentId = "1",
    contentName = "Lego",
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class AdImp(
    val placementId: String,
    val width: Int,
    val height: Int,
    val clickURL: String,
    val adType: AdType,
    val contentId: String? = null,
    val contentName: String? = null,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

enum class AdType {
    banner,
    video,
    native,
    product,
    reach_media,
    other
}

placementId - идентификатор инвентаря, где был показан рекламный блок
width - ширина рекламного блока
height - высота рекламного блока
clickURL - URL адрес, который привязан к рекламному блоку
adType - тип рекламы, по которой происходит клик пользователем (см. описание типа данных)
contentId - (необязательный) уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - (необязательный) наименование просматриваемого контента
sku - (необязательный) объект, описывающий товарyную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

AdClick

Триггер: нажатие пользователем на рекламный баннер.
Данные: объект с описанием рекламного блока, который был нажат пользователем.

code exampletypes

kotlin

val event = AdClick(
    placementId = "1",
    width = 240,
    height = 300,
    clickURL = "https://test.com",
    adType = AdType.banner,
    contentId = "1",
    contentName = "Lego",
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class AdClick(
    val placementId: String,
    val width: Int,
    val height: Int,
    val clickURL: String,
    val adType: AdType,
    val contentId: String? = null,
    val contentName: String? = null,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

enum class AdType {
    banner,
    video,
    native,
    product,
    reach_media,
    other
}

placementId - идентификатор инвентаря, где был показан рекламный блок
width - ширина рекламного блока
height - высота рекламного блока
clickURL - URL адрес, который привязан к рекламному блоку
adType - тип рекламы, по которой происходит клик пользователем (см. описание типа данных)
contentId - (необязательный) уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - (необязательный) наименование просматриваемого контента
sku - (необязательный) объект, описывающий товарyную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

Scroll

Триггер: пользователь прокрутил страницу контента.
Данные: объект со значением прокрутки контента в процентном соотношении от величины всего контента.

code exampletypes

kotlin

val event = Scroll(
    value = 0.6F,
    contentId = "1",
    contentName = "Lego",
    sku = SKU(
        skuId = "1",
        skuName = "Lego",
        price = 35.0,
        currency = "RUB"
    ),
    category = listOf(
        Category(
            categoryId = "1",
            categoryName = "Category Name",
            children = listOf(
                Category(
                    categoryId = "11",
                    categoryName = "SubCategory Name"
                )
            )
        )
    ),
    customParams = mapOf(
        "custom_param1" to "value1",
        "custom_param2" to "value2"
    )
)
tracker.event(event)

kotlin

data class Scroll(
    val value: Float,
    val contentId: String,
    val contentName: String,
    val sku: SKU? = null,
    val category: List<Category>? = null,
    val customParams: Map<String, String>? = null
) : CommonEvent(), TrackerEvent, CustomParamsAwareEvent

value - величина прокрутки страницы, которую смотрит пользователь от 0 до 1
contentId - уникальный идентификатор просматриваемого контента. По умолчанию подразумевается URL страницы контента, если такое разделение на идентифкаторы невозможно, то любой другой иденификатор, явно отличающий один просматриваемый контент от другого.
contentName - наименование просматриваемого контента
sku - (необязательный) объект, описывающий товарyную позицию (см. SKU)
category - (необязательный) таксаномия категорий товара (см. Категория)
customParams - (необязательный) пользовательские дополнительные параметры

Вспомогательные поля

Ниже приводится описание вспомогательных полей и их типов данных, используемых в стандартных событиях.

SKU

Объект, описывающий товарную позицию.

kotlin

data class SKU(
    val skuId: String,
    val skuName: String,
    val price: Float? = null,
    val currency: String? = null,
    val category: List<Category>? = null
)

skuId - уникальный идентификатор товара
skuName - наименование товара
price - (необязательный) цена товара
currency - (необязательный) валюта товара (USD, EUR, RUB и т.д.)
category - (необязательный) таксаномия категорий товара (см. Категория)

Tracking SDK Standard Android ​

Требования ​

Установка ​

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

User ID (UID) ​

Отслеживаемые события ​

Стандартные события ​

AddToCart ​

Purchase ​

StartView ​

StopView ​

Click ​

Search ​

AdImp ​

AdClick ​

Scroll ​

Вспомогательные поля ​

Category ​

SKU ​

Tracking SDK Standard Android

Требования

Установка

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

User ID (UID)

Отслеживаемые события

Стандартные события

AddToCart

Purchase

StartView

StopView

Click

Search

AdImp

AdClick

Scroll

Вспомогательные поля

Category

SKU