Tracking SDK Standard iOS (Swift) ​

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

SDK версия:

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

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

Требования ​

• Swift 5 и выше
• iOS 12 и выше

Установка ​

pod 'SATrackingSDK', '{{ version }}'

или

pod 'SATrackingSDKStandard', :git => 'https://github.com/solutionarchitectstech/ios_tracker_sdk_release.git', :tag => '{{ version }}'

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

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

См. пример: AppDelegate.swift:

TechTracker.initialize(options: TrackerOptions(
    partnerId: "YOUR_PARTNER_ID",
    sessionId: "YOUR_SESSION_ID",
    endpointUrl: "https://YOUR_END_POINT",
    debugMode: true,
    httpHeaders: [
        "Authorization": "YOUR_AUTHORIZATION_TOKEN"
    ]
))

TechTracker.initialize(options: TrackerOptions)

public struct TrackerOptions {
    public init(
        partnerId: String,
        endpointUrl: String,
        sessionId: String,
        debugMode: Bool = false,
        httpHeaders: [String: String] = [:]
    )
}

• 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 - Справочник (Dictionary) HTTP заголовков, которые будут вставлены в каждый API вызов. По умолчанию [:]. когда вы запускаете TechTracker.shared.event(event: TrackerEvent) функцию.

User ID (UID) ​

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

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

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

myAuthService.signIn(username, password) { authSession, error in
    defer {
        TechTracker.shared.uid = authSession.success ? authSession.user.id : nil
    }
  
    if let error = error {
        print("ERROR: Unable to sign-in due error: \(error.localizedDescription)")
        return
    }
  
    // Здесь вы выполняете бизнес логику, специфичную для вашего приложения, когда пользователь 
    // успешно прошел авторизацию.
    // Например: Переход на 'Главный' экран, или навигация в 'Корзину' для оформления заказа и т.п.
}

myAuthService.signOut() { error in
    defer {
        TechTracker.shared.uid = nil
    }
    
    if let error = error {
        print("WARNING: Error occured while sign-out (skipped): \(error.localizedDescription)")
    }
    
    // Пользователь завершил авторизованную сессию ('Sign-out') - здесь вы выполняете вашу бизнес логику, специфичную для этого.
    // Например: Приложение переходит на экран 'Sign-in' (стартовый экран), и т.п.
}

public class TechTracker {
    public var uid: String?
}

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

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

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

Пример:

var event = Click(
    value: "start registration",
    contentId: "1",
    contentName: "Doll",
    category: [
        Category(
            categoryId: "1",
            categoryName: "Category Name",
            children: [
                Category(
                    categoryId: "11",
                    categoryName: "SubCategory Name"
                )
            ]
        )
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event) { error in
    if let error = error {
        print("ERROR: Unable to send event due error: \(error.localizedDescription)")
        return
    }
    print("DEBUG: Done - your event has been sent successfully.")
}

public func event(
    path: String = "",
    event: TrackerEvent,
    block: @escaping (Error?) -> Void = { _ in }
)

• path - Например: my_company/tracking. По умолчанию "". Если вы добавите этот аргумент при вызове функции, то SDK отправит событие на след. URL: https://my.server.com/event/my_company/tracking, так как при инициализации SDK использовался https://my.server.com/event в качестве endpointUrl параметра. Если вы инициализируете SDK, используя полный URL, например: https://my.server.com/event/my_company/tracking. В этом случае, просто игнорируйте передачу аргумента path при вызове функции event().
• event - Объект 'событие', которое вы хотите отслеживать (tracking) в вашем приложении. См. Стандартные события.
• block - Callback функция (closure), которай вызывается после попытки отправки события. По умолчанию пустой блок.

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

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

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

AddToCart ​

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

let event = AddToCart(
    items: [
        AddToCartItem(
            sku: SKU(
                skuId: "1",
                skuName: "Lego",
                price: 35.0,
                currency: "RUB"
            ),
            deltaQuantity: 1.0,
            quantity: 2.0,
            category: [
                Category(
                    categoryId: "1",
                    categoryName: "Category Name",
                    children: [
                        Category(
                            categoryId: "11",
                            categoryName: "SubCategory Name"
                        )
                    ]
                )
            ],
            customParams: [
                "custom_param_1_1": "value_1_1",
                "custom_param_1_2": "value_1_2"
            ]
        ),
        AddToCartItem(
            sku: SKU(
                skuId: "2",
                skuName: "Ozone"
            ),
            deltaQuantity: 1.0,
            quantity: 2.0,
        )
    ]
)

TechTracker.shared.event(event: event)

public struct AddToCart: TrackerEvent {
    public init(items: [AddToCartItem] = [])
}

public struct AddToCartItem: CustomParamsAware {
    public init(
        sku: SKU,
        deltaQuantity: Float,
        quantity: Float,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

Purchase ​

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

let event = Purchase(
    items: [
        PurchaseItem(
            sku: SKU(
                skuId: "1",
                skuName: "Lego",
                price: 35.0,
                currency: "RUB"
            ),
            quantity: 2.0,
            category: [
                Category(
                    categoryId: "1",
                    categoryName: "Category Name",
                    children: [
                        Category(
                            categoryId: "11",
                            categoryName: "SubCategory Name"
                        )
                    ]
                )
            ],
            customParams: [
                "custom_param_1_1": "value_1_1",
                "custom_param_1_2": "value_1_2"
            ]
        ),
        PurchaseItem(
            sku: SKU(
                skuId: "2",
                skuName: "Ozone"
            ),
            quantity: 2.0
        )
    ]
)

TechTracker.shared.event(event: event)

public struct Purchase: TrackerEvent {
    public init(items: [PurchaseItem] = [])
}

public struct PurchaseItem: CustomParamsAware {
    public init(
        sku: SKU,
        quantity: Float,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

StartView ​

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

let event = StartView(
    contentId: "1",
    contentName: "Lego",
    sku: SKU(
        skuId: "1",
        skuName: "Lego",
        price: 35.0,
        currency: "RUB"
    ),
    category: [
        Category(
            categoryId: "1",
            categoryName: "Category Name",
            children: [
                Category(
                    categoryId: "11",
                    categoryName: "SubCategory Name"
                )
            ]
        )
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event)

public struct StartView: TrackerEvent, CustomParamsAware {
    public init(
        contentId: String,
        contentName: String,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

StopView ​

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

let event = StopView(
    contentId: "1",
    contentName: "Lego",
    value: 0.5
    sku: SKU(
        skuId: "1",
        skuName: "Lego",
        price: 35.0,
        currency: "RUB"
    ),
    category: [
        Category(
            categoryId: "1",
            categoryName: "Category Name",
            children: [
                Category(
                    categoryId: "11",
                    categoryName: "SubCategory Name"
                )
            ]
        )
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event)

public struct StopView: TrackerEvent, CustomParamsAware {
    public init(
        contentId: String,
        contentName: String,
        value: Float,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

Click ​

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

let event = Click(
    value: "start registration",
    contentId: "1",
    contentName: "Lego",
    sku: SKU(
        skuId: "1",
        skuName: "Lego",
        price: 35.0,
        currency: "RUB"
    ),
    category: [
        Category(
            categoryId: "1",
            categoryName: "Category Name",
            children: [
                Category(
                    categoryId: "11",
                    categoryName: "SubCategory Name"
                )
            ]
        )
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event)

public struct Click: TrackerEvent, CustomParamsAware {
    public init(
        value: String,
        contentId: String,
        contentName: String,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

Search ​

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

let event = Search(
    value: "Pampers",
    filter: [
      "age": ["0-1", "1-3"],
      "sex": ["m"]
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event)

public struct Search: TrackerEvent, CustomParamsAware {
    public init(
        value: String,
        filter: [String: [String]]? = nil,
        customParams: [String: String]? = nil
    )
}

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

AdImp ​

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

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

TechTracker.shared.event(event: event)

public struct AdImp: TrackerEvent, CustomParamsAware {
    public init(
        placementId: String,
        width: Int,
        height: Int,
        clickURL: String,
        adType: AdType,
        contentId: String? = nil,
        contentName: String? = nil,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

public enum AdType: String {
    case banner
    case video
    case native
    case product
    case reach_media
    case other
}

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

AdClick ​

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

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

TechTracker.shared.event(event: event)

public struct AdClick: TrackerEvent, CustomParamsAware {
    public init(
        placementId: String,
        width: Int,
        height: Int,
        clickURL: String,
        adType: AdType,
        contentId: String? = nil,
        contentName: String? = nil,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

public enum AdType: String {
    case banner
    case video
    case native
    case product
    case reach_media
    case other
}

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

Scroll ​

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

let event = Scroll(
    value: 0.6,
    contentId: "1",
    contentName: "Lego",
    sku: SKU(
        skuId: "1",
        skuName: "Lego",
        price: 35.0,
        currency: "RUB"
    ),
    category: [
        Category(
            categoryId: "1",
            categoryName: "Category Name",
            children: [
                Category(
                    categoryId: "11",
                    categoryName: "SubCategory Name"
                )
            ]
        )
    ],
    customParams: [
        "custom_param1": "value1",
        "custom_param2": "value2"
    ]
)

TechTracker.shared.event(event: event)

public struct Scroll: TrackerEvent, CustomParamsAware {
    public init(
        value: Float,
        contentId: String,
        contentName: String,
        sku: SKU? = nil,
        category: [Category]? = nil,
        customParams: [String: String]? = nil
    )
}

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

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

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

Category ​

Таксаномия категорий просматриваемого контента либо товара.

public struct Category {
    public init(
        categoryName: String,
        categoryId: String? = nil,
        children: [Category]? = nil
    )
}

• name - имя категории
• categoryId - (необязательный) уникальный идентификатор категории
• children - (необязательный) вложеннный массив дочерних подкатегорий для данной категории

SKU ​

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

public struct SKU {
    public init(
        skuId: String,
        skuName: String,
        price: Float? = nil,
        currency: String? = nil,
        category: [Category]? = nil
    )
}

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