eCommerce, web-view и идентификатор пользователя в SDK Статистики от SberAds
В SDK eCommerce-событие отправляют методом trackEcom (Android) или trackEcomm (iOS, React Native): имя события плюс объект из полей currencyCode, action, products, impressions, promotions. Для связи с JS-счётчиком в web-view на Android и iOS подключают код из справки. Параметры publisherId, publisherScope, phone, email обновляют методом updateOptions, id авторизованного пользователя — syncUserId (при выходе передают null или nil).
Цифры
Формат eCommerce-события
| Поле | Что передают | На React Native |
|---|---|---|
| currencyCode | трёхбуквенный код валюты ISO 4217; иная валюта даёт нулевые значения вместо валюты и суммы | обязателен |
| action | данные о действии, объект действия | необязательно |
| products | список описаний товаров, с которыми произведено действие | необязательно |
| impressions | список товаров, относящихся к показу (impressions) | необязательно |
| promotions | данные о рекламной акции | необязательно |
Названия классов объекта разные: ECommerceEvent на Android, TrackerTop100ECommerce на iOS, TrackerTop100EcommParams на React Native.
Поля вложенных объектов (по примерам)
Отдельных таблиц с описанием полей на страницах SDK нет, набор виден из примеров.
| Объект | Поля из примеров | Обязательное |
|---|---|---|
| Товар | id, name, list, brand, category, coupon, position, price, quantity, variant | id (первый параметр конструктора) |
| Действие | id, coupon, revenue, affiliation, tax, shipping, list, step, option | id (первый параметр) |
| Акция | id, name, creative, position | id (первый параметр) |
В Android-примерах у name и list товара стоит комментарий «Optional».
Типы значений в примерах
| Поле | Android | iOS | React Native |
|---|---|---|---|
| price | число (BigDecimal в Kotlin) | строка | строка |
| position | число | строка | строка |
| quantity | число | в примерах Swift не передаётся | число |
| step | число | строка | строка |
Примеры названий событий
| Платформа | Названия в примерах |
|---|---|
| Android | impressions, promoClick, click, add, detail |
| iOS | impressions, promoClick, click, add, purchase |
| React Native | purchase |
Методы обновления и идентификатор пользователя
| Задача | Android | iOS | React Native |
|---|---|---|---|
| Отправить eCommerce | Kraken.trackEcom | TrackerTop100.trackEcomm | NativeTrackerTop100.trackEcomm |
| Связать SDK и JS-счётчик в web-view | JavaScript-интерфейс «kraken» с getData | WKUserScript с getDataToWebView | в справке не нашли |
| Обновить параметры | Kraken.updateOptions: телефон, email, publisherId, publisherScope, projectId | TrackerTop100.updateOptions с объектом TrackerTop100Settings.Params | в справке не нашли |
| Передать id пользователя | Kraken.syncUserId: userId и projectId; null при выходе | TrackerTop100.syncUserId: userId и projectId; nil при выходе | в справке не нашли |
Подробности
eCommerce-данные в приложении
Чтобы передать действие пользователя, собирают объект в формате eCommerce и отправляют вместе с названием события. Объекты товара, действия и акции создают конструкторами SDK. Первым параметром товара, действия и акции указывают идентификатор.
- Android: товары, действие и акции собирают в ECommerceEvent (методы setParams и setPromoParams для акции), затем вызывают Kraken.trackEcom с названием и результатом.
- iOS: собирают TrackerTop100ECommerce из товаров, действия и акций и вызывают TrackerTop100.trackEcomm с названием события (обязательно) и данными (опционально).
- React Native: данные собирают построителями (action, product, promo и параметры), затем вызывают NativeTrackerTop100.trackEcomm. Название события обязательно, данные опциональны.
В примерах на Android показаны показ товара (impressions), клик по акции (promoClick), клик по товару, добавление в корзину и показ информации о товаре (detail). На iOS — те же показ, клик по акции, клик по товару и добавление в корзину, плюс покупка (purchase); для покупки в действии указан id и этап оформления с выбором. В React Native один общий пример покупки: действие, товар, показанный товар, акция и параметры с валютой USD. В примерах Android и iOS валюта RUB.
Данные в web-view
Нужны, если события SDK и JS-счётчика надо связать.
- Android: в Activity создают WebView, включают JavaScript и добавляют JavaScript-интерфейс с именем «kraken», который отдаёт строку из getData.
- iOS: при создании web-view в конфигурацию добавляют скрипт WKUserScript, источником которого служит результат getDataToWebView; скрипт выполняется после загрузки HTML (в конце документа), только для главного фрейма.
- React Native: страницы в справке нет.
Как именно JS-счётчик использует эти данные, на страницах не описано.
Обновление параметров счётчика
Метод updateOptions обновляет параметры, относящиеся к projectId: publisherId, publisherScope, phone, email.
- Android: метод принимает телефон, email, publisherId, publisherScope и projectId; аргумент, который менять не нужно, передают как null.
- iOS: метод принимает объект TrackerTop100Settings.Params с обновлёнными параметрами; в примере указаны projectId, publisherId, publisherScope, phone и email.
Идентификатор авторизованного пользователя
Метод syncUserId принимает идентификатор пользователя и идентификатор проекта и отправляет их в счётчик. Так можно переопределить user_id, заданный в настройках счётчика при инициализации. Если пользователь разлогинился, userId передают как null (Android) или nil (iOS).
Чтобы смотреть статистику в разрезе пользователей, им присваивают уникальные идентификаторы и включают их в данные, которые уходят в счётчик: так активности в приложении соотносятся с пользователями.
Важно знать
- В React Native первым аргументом построителя действия стоит 'purchase' (то же, что название события), а в Android и iOS первый параметр действия — идентификатор покупки (пример: TRX#54321 и b52314). Что именно означает первый аргумент для React Native, справка не поясняет.
- Типы значений различаются по платформам (число или строка) для price, position и step. Какой тип принимает счётчик в каждом случае, справка не говорит: это видно только из примеров.
- Полного перечня допустимых названий событий на страницах SDK нет, есть только названия из примеров. Описания полей товара, действия и акции даны лишь на веб-странице eCommerce (в соседней статье); для SDK таблиц нет.
- Android: в начале примера impressions в тексте страницы строка с вызовом Kraken.trackEcom содержит лишнюю скобку; в примере detail создана переменная action, которая в вызов не попадает. Ориентироваться стоит на смысл, не на копирование.
- На странице Android-метода обновления параметров после слов «Пример использования метода» кода нет. Остальное про метод есть.
- Для iOS-метода обновления в справке не сказано, обязателен ли projectId и что будет с незаполненными полями; для Android сказано: ненужный аргумент передают как null.
- Хешируются ли телефон и email при обновлении через updateOptions, в справке не нашли (при активации SDK хеши считаются автоматически).
- Для React Native страниц про web-view, updateOptions и syncUserId в справке не нашли. В параметрах настроек React Native есть setAuthUserId (подробнее в статье про параметры SDK).