iOS

UX Rocket SDK для iOS позволяет организовать сбор аналитических данных о поведении пользователей, а также реализовать персонализацию контента на основе сегментов аудитории. С его помощью можно отслеживать активность в приложении, проводить эксперименты и повышать вовлечённость пользователей.

Подключение библиотеки SDK

SPM (Swift Package Manager)

В Xcode:

1. File → Add Packages
2. Указать адрес репозитория https://git.uxrocket.ru/sdk/ux-rocket-sdk-ios
3. Dependency Rule рекомендуемая версия 2.0.0
4. Нажать Add Package

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

Для инициализации SDK необходимо вызвать метод SDK configure, передав в него параметры авторизации:

• authKey – уникальный код клиента, например «2JIJ67L7CS»
• appRocketId – идентификатор вашего приложения, в примере test_ios_sdk_uxrocket и test_android_sdk_uxrocket
• serverEnvironment – строка подключения к API UX Rocket
• getAdvertisingId - установка рекламных настроек (true / false).

Данный метод с версии SDK 2.0.0 не поддерживается:

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        UXRocket.configure(
            withAuthKey: "2JIJ67L7CS", 
            rocketAppID: "test_ios_sdk_uxrocket", 
            serverEnvironment: .develop,
            enabledAutoTrack: false,
            enabledReferrer: false,
            enabledScrollTracking: false
         )
        return true
    }

Рекомендуется с версии SDK 2.0.0 использовать метод configure:

UXRocket.configure(
        withAuthKey: "2JIJ67L7CS",
        rocketAppID: "test_ios_sdk_uxrocket",
        serverEnvironment: .develop,
        autoTrackingMode: .remote
     )

При первой инициализации SDK, вместе с событием Install, вызывается соответствующий метод SKAdNetwork в зависимости от версии iOS:

Для iOS ниже 15.4: SKAdNetwork.registerAppForAdNetworkAttribution();

Для iOS 15.4 и выше: SKAdNetwork.updatePostbackConversionValue(1);

Это необходимо для корректного отслеживания атрибуции установок через SKAdNetwork.

Установка значений по умолчанию

SDK автоматически каждый раз собирает такие параметры, как разрешение экрана, версия ОС, модель телефона и многое другое. Для установки значений по умолчанию используется метод setDefaultParameters. Параметры, установленные этим методом, будут использоваться в дальнейшем другими методами при отправке данных в UX Rocket.

• Метод setParams принимает id и value для params, которые будут сохранены в SDK и устанавливаться по умолчанию в методах, если параметры с соответствующими id не заполнены.
• Данные хранятся в пределах сессии
• После завершения сессии сохраненные значения удаляются
• Можно сохранять при помощи метода любые значения и переменные
• Корректность значений методом не проверяется

Входные данные от МП:

UXRocket.setDefaultParameters(
    [
          .init(id: 1, value: "Желтый"),
          .init(id: 2, value: "true"),
          .init(id: 3, value: "false")
    ]
)

Геолокация

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

Особенности работы с геолокацией:

• функция setCountryAndCity() принимает значения city и country, когда их надо сменить при изменениях геолокации;
• данные хранятся в пределах сессии;
• после завершения сессии сохраненные значения удаляются;
• корректность значений методом не проверяется.

UXRocket.setCountryAndCity("Russia", "Moscow")

Сбор сведений о поведении пользователя в мобильном приложении

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

Регистрация события:
UXRocket.logEvent(
    event: "контекст события",
    itemName: "надпись на элементе",
    itemIdentificator: "идентификатор или имя элемента",
    parameters: [AttributeParameter] = [] //массив параметров
)

Для ручного указания URL и реферера вызовите метод:
UXRocket.logEvent({
    event: "eventContext",
    itemName: "itemName",
    itemIdentificator: "itemIdentificator",
    currentUrl: "currentUrl",
    referrerUrl: "referrerUrl"
});

Авторазметка

Авторазметка (автотрекинг) событий – это автоматический сбор данных о действиях пользователей в приложении. Он отслеживает, как приложение устанавливается, открывается, и какие действия выполняются пользователями.

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

Значение event определяет тип события. В параметр event передается строка, отражающая тип логируемого события. Перечень типов событий согласовывается на этапе внедрения SDK.

Собираемые события автоматически:

Как активировать сбор событий?

Авторазметка может работать в трех режимах для iOS:

1. remote (Удаленный режим). Авторазметка включается автоматически, но не отправляет данные сразу. Приложение сначала загружает настройки из вашего аккаунта на сервере, а затем начинает собирать и отправлять данные. Все настройки сбора событий управляются через личный кабинет, где можно включать или отключать нужные события.
2. manual (Ручной режим). Разработчик сам настраивает, какие события отслеживать. Например, можно включить отслеживание только кнопок или вкладок, но не списка или скролла. Вы получаете полный контроль над тем, что именно отслеживать.
3. none (Выключено). Авторазметка отключена, и разработчик сам вручную отмечает события в коде. Например, если нужно зафиксировать нажатие кнопки, то придется писать код вручную.

Режим авторазметки представлен в виде перечисления:

public enum AutoTrackingMode {
case remote
case manual(_ config: ConfigAutoTrack)
case none
}

Конфигурация авторазметки в режиме remote:

1. Перейти в События → Типовые события → Типы событий.
2. Создать новое событие, например, OpenPage.
3. В параметрах события выбрать «Отправить в UX Rocket» → «Да».

После этого статус события будет «Активно», и UX Rocket начнет получать события открытия страниц.

Если статус события перевести в «Неактивно», то все события этого типа перестанут отправляться.

Когда включен manual-режим, можно настроить, какие события отслеживать. Настройки хранятся в структуре ConfigAutoTrack и включают:

Пример для manual-режима авторазметки:

// Создаем конфигурацию авторазметки
let config = ConfigAutoTrack(
    enabledAutoTrackButtons: true, 
    enabledTabs: true,             
    enabledList: true,              
    enabledMenu: true,
    enabledScrollTracking: true, 
    enabledReferrer: true,   
    enabledOpenPage: true,   
    nameGroup: "TestGroup" 
)

// Инициализируем UXRocket в manual-режиме с заданной конфигурацией
UXRocket.configure(
    withAuthKey: "2JIJ67L7CS",
    rocketAppID: "test_ios_sdk_uxrocket",
    serverEnvironment: .develop,
    autoTrackingMode: .manual(config) // Передаем конфигурацию авторазметки
)

Набор атрибутов события

Большинство параметров собирает сам SDK, они описаны в таблице ниже. Ряд событий, связанных с таргетингом, нужно передавать явно при вызове метода logEvent. Значение parameters является массивом пар ключ (int) и значение (string). Массив может принимать до 30 пар ключ-значение. Метод logEvent следует вызывать при взаимодействии пользователя с элементом интерфейса. Перечень отслеживаемых элементов согласовывается с маркетологом на этапе внедрения SDK. Пример вызова:

UXRocket.logEvent(
                  event: "button",
                  itemName: "buttonTitle",
                  itemIdentificator: "itemIdentifier",
                  parameters: [.init(id: 2, value: "Красный")]
        )

Список параметров, которые необходимо передавать явно

Список параметров, собираемых SDK автоматически

Передача данных при работе с корзиной

Корзина автоматически не размечается. Для организации логирования событий работы с корзиной товаров добавлены следующие поля:

• productCode – идентификатор товара
• productPrice – цена товара
• productCount – количество товара
• cartSum – сумма товаров в корзине

Указанные параметры также требуют явной передачи в методе UXRocket.logEvent и позволяют реализовать различные сценарии работы с корзиной – добавление товара в корзину, удаление товара из корзины, очистка корзины, оплата товаров и прочее. Пример вызова:

// добавление товара в корзину
UXRocket.logEvent(
            event: "add_to_cart",
            itemName: "add_item_button pressed",
            itemIdentificator: "add_item_button",
            productCode: newItem.name,
            productPrice: newItem.price,
            productCount: items.count,
            cartSum: total)

//отправка корзины в оплату
UXRocket.logEvent(
            event: "cart_checkout",
            itemName: "checkout_button pressed",
            itemIdentificator: "checkout_button",
            productCode: "All Items",
            productPrice: nil,
            productCount: items.count,
            cartSum: total)

Применение вариантов таргетинга

При отрисовке страницы мобильного приложения необходимо получить варианты таргетинга. Для этого надо вызвать метод «getUIConfiguration» и проанализировать его ответ. В ответе содержится несколько массивов variantAttrs. Из этих массивов нужно взять данные для персонализации. Для дальнейшего поиска элементов, изменение которых требуется отслеживать, разработчик должен назначить им персональные идентификаторы, например id или name. Перечень отслеживаемых элементов согласовывается с маркетологом на этапе внедрения SDK. Для каждого элемента массива на странице ищется элемент интерфейса с идентификатором равным значению поля item. Если такой элемент найден, то его атрибутам следует присвоить значения, содержащиеся во вложенном массиве attributes.

Пример:

[
    {
        "id": 7,
        "variants": [
            {
                "id": 50,
                "element_id": 24,
                "variant_attrs": [
                    {
                        "item": "FourthVC_LeftButton",
                        "attributes": [
                            {
                                "attribute": "text",
                                "value": [
                                    {
                                        "value": "Много текста, держи еще два,
                                        "state": ["highlighted"]
                                    },
                                    {
                                        "value": "Тут будет не так много текста"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },
            {
                "id": 52,
                "element_id": 25,
                "variant_attrs": [
                    {
                        "item": "FourthVC_RightButton",
                        "attributes": [
                            {
                                "attribute": "text",
                                "value": "Push me, please!"
                            },
                            {
                                "attribute": "text-color",
                                "value": "#000000"
                            }
                        ]
                    }
                ]
            }

        ],
        "actions": [
            {
                "id": 23,
                "name": "ClickButton",
                "item": "ViewController_FirstButton",
                "action_type": 1,
                "counting_type": 1
            },
            {
                "id": 24,
                "name": "SecondSumLabel",
                "item": "FourthVC_SecondSumLabel",
                "action_type": 0,
                "counting_type": 2
            },
            {
                "id": 25,
                "name": "ClickImage",
                "item": "FourthVC_ImageView",
                "action_type": 1,
                "counting_type": 1
            }
        ]
    }
]

В указанном примере, помимо прочего, для элемента интерфейса с идентификатором «FourthVC_RightButton» необходимо:

• атрибуту "text" присвоить значение "Push me, please!"
• атрибуту "text-color" присвоить значение"#000000"

Аналогичным образом необходимо обработать пришедшие в ответе метода массивы «actions». Каждый элемент массива указывает на целевое действие (например, тап по кнопке), настроенное маркетологом для сохранения.

Пример:

UXRocket.getUIConfiguration(
                forItem: vcIdentifier,
                parameters: [.init(id: 2, value: "2")]
            ) { response in
                self.alert.dismiss(animated: true)

                guard let response = response else { return }

                UXRocket.customizeItems(elementsToCustomize, with: response)
                UXRocket.logCampaignEvent(viewControllerID: vcIdentifier, totalValue: Int(self.secondSumLabel.text ?? "150") ?? 150)
            }