Порядок подключения СберВизор в мобильное-приложение (Android)
Мы рекомендуем придерживаться описанного порядка и настроек при подключении сервиса СберВизор.
Инициализация библиотеки на Android
Для подключения мобильного приложения на базе Android к SberVisor (старое название "СберАналитика") нужно скачать и включить в свой проект SDK (https://sberbank.ru/dl/sa/androidsdk.zip).
SDK для Android представляет из себя подключаемый .aar модуль.
Как подключить
implementation(name: 'clickstreamlib-X.X.X', ext: 'aar')
implementation('com.squareup.okhttp3:okhttp:4.9.1')
implementation('com.fasterxml.jackson.core:jackson-databind:2.9.8')
Описание классов:
Все основные сущности SDK находятся в пакете ru.sberbank.mobile.clickstream
Основные классы:
| Класс | Описание | Пакет |
| SberbankAnalytics | Базовый класс сбербанк аналитики | ru.sberbank.mobile.clickstream.boundary |
| AnalyticsProfileCollector | Класс для хранения информации о профиле пользователя в отправляемых данных | ru.sberbank.mobile.clickstream.meta |
| AnalyticsMetaCollector | Класс для хранения метаинформации об отправляемых данных | ru.sberbank.mobile.clickstream.meta |
| SberbankAnalyticsEvent | Событие для его передачи в систему аналитики | ru.sberbank.mobile.clickstream.models.data |
| SberbankAnalyticsConstants | Ключи для настройки события | ru.sberbank.mobile.clickstream |
| DefaultNetworkFactory | Класс для работы аналитики с сетью. Реализует интерфейс NetworkFactory. | ru.sberbank.mobile.clickstream.factory |
Блок импорта основных классов
import ru.sberbank.mobile.clickstream.SberbankAnalyticsConstants; import ru.sberbank.mobile.clickstream.boundary.ISberbankAnalytics; import ru.sberbank.mobile.clickstream.boundary.SberbankAnalytics; import ru.sberbank.mobile.clickstream.configuration.SberbankAnalyticsConfigurator; import ru.sberbank.mobile.clickstream.configuration.SberbankAnalyticsDefaultConfigurator; import ru.sberbank.mobile.clickstream.configuration.SberbankAnalyticsDefaultConfiguratorManager;
import ru.sberbank.mobile.clickstream.factory.DefaultNetworkFactory; import ru.sberbank.mobile.clickstream.network.AnalyticsEventSender; import ru.sberbank.mobile.clickstream.network.OkHttpAnalyticsEventSender; import ru.sberbank.mobile.clickstream.network.parser.AnalyticsJacksonParser; import ru.sberbank.mobile.clickstream.meta.AnalyticsMetaCollector; import ru.sberbank.mobile.clickstream.meta.AnalyticsProfileCollector; import ru.sberbank.mobile.clickstream.models.data.SberbankAnalyticsEvent;
Принцип использования
Создать необходимые объекты AnalyticsMetaCollector, AnalyticsProfileCollector, DefaultNetworkFactory
Создать экземпляр класса SberbankAnalytics.Builder, передав в конструктор контекст приложения
У Builder вызвать set-методы для созданных объектов и необходимых опций
Вызвать метод buildи получить экземплярSberbankAnalytics
Создать экземпляр класса SberbankAnalyticsEvent и настроить событие
Отправить созданное событие c помощью метода sendEventилиSberbankAnalytics.sendSensetiveEvent
Пример использования (в Application классе)
//Инициализация необходимых объектов
AnalyticsMetaCollector metaCollector = new AnalyticsMetaCollector();
AnalyticsProfileCollector profileCollector = new AnalyticsProfileCollector();
DefaultNetworkFactory networkFactory = new DefaultNetworkFactory();
//Создание объекта аналитики
ISberbankAnalytics sberbankAnalytics = new SberbankAnalytics.Builder(this)
.setAnalyticsMetaCollector(metaCollector, profileCollector)
.setNetworkFactory(networkFactory)
.setAnalyticsDbEnabled(false)
.setCustomUrl("https://someurl")
.build();
//Добавление мета и профайл данных в коллекторы
Map<String, String> profileData = new HashMap<>();
profileData.put("someKey", "someValue");
Map<String, String> metaData = new HashMap<>();
metaData.put("someKey", "someValue");
profileCollector.update(profileData);
metaCollector.update(metaData);
...
// Создание объекта события
SberbankAnalyticsEvent event = new SberbankAnalyticsEvent("eventName");
Map<String, String> eventParams = new HashMap<>();
eventParams.put("someParamKey", "someParamValue");
event.addData(eventParams);
//Отправление события
sberbankAnalytics.sendEvent(event);
Настройка основных параметров класса SberbankAnalytics:
Настройка объекта аналитики производится вызовом методов класса SberbankAnalytics.Builder. Настройки указываются через следующие методы конфигуратора:
| Настройка | Метод | Описание | Тип значения |
| Коллектор мета-данных и данных профиля | setAnalyticsMetaCollector | Задает хранилище мета-данных для отправки | AnalyticsMetaCollector + AnalyticsProfileCollector |
| Сетевой слой аналитики | setNetworkFactory | Предоставляет возможность задать свою фабрику для сетевого слоя аналитики. Рекомендуется использовать DefaultNetworkFactory. | NetworkFactory |
| Адрес для отправки событий | setCustomUrl | Адрес сервера сервиса, куда будут отправляться события. Задается так как может отличаться. | Строка |
| Использование БД для хранения событий | setAnalyticsDbEnabled | включает БД для хранения нечувствительных событий; false - отключает БД, т.е. вообще никакие события не будут сохраняться в БД | Логическое значение |
| Время хранения событий в базе данных при ее использовании | setClearDaysCount | Предоставляет возможность установить количество дней, в течение которых события будут храниться в БД | Число |
Настройка общих параметров для всех отправляемых событий
Событие состоит из блоков с редко меняющейся информацией metaиprofile. Для их настройки используются специализированные коллекторы. Важно - в текущей версии SDK задавать данные коллекторов меты и профиля (методы update) нужно послевыполнения методаSberbankAnalytics.Builder! Иначе данные коллекторов не попадут в пакеты.
Коллекторы профиля и метаинформации
Коллекторы служат для хранения необходимой для пакета информации. Для этого используются классы AnalyticsProfileCollectorиAnalyticsMetaCollector. После создания и настройки их необходимо передать в SberbankAnalytics.Builder. Настройка коллекторов производится вызовом метода update с передачей Map\<string, string> в качестве аргумента.
Параметры, задаваемые с помощью meta коллектора
| Ключ параметра | Описание | Способ заполнения | Обязателен? |
| systemLanguage | Системный язык на устройстве | import java.util.Locale; Locale.getDefault().toString() | да |
| screenSize | Размер экрана устройства | DisplayMetrics metrics = context.getResources().getDisplayMetrics(); metrics.heightPixels + "x" + metrics.widthPixels; | да |
| sberId | Уникальный код SberId, выдаваемый партнерупродукту системой SberbankID | При инициализации | да |
| platform | Платформа в которой работает sdk | = "MOBILE" | да |
| operationSystemVersion | Версия операционной системы | String.valueOf(android.os.Build.VERSION.SDK_INT) | да |
| operationSystem | Тип операционной системы | "Android" | да |
| deviceVendor | Производитель устройства | String.valueOf(Build.MANUFACTURER) | да |
| deviceModel | Модель устройства | String.valueOf(Build.MODEL) | да |
| deviceMemorySize | Количество памяти в устройстве | import android.os.Environment; String.valueOf(Environment.getExternalStorageDirectory().getTotalSpace()) | да |
| browser | Не несет полезной нагрузки, но нужно заполнить | "Android" | да |
| apiKey | Уникальный идентификатор продукта (выдается командой Сбервизор) | При инициализации | да |
Пример указания параметра
AnalyticsMetaCollector metaCollector = new AnalyticsMetaCollector();
/** Передача в аналитику коллектора метаинформации */
builder.setAnalyticsMetaCollector(metaCollector, profileCollector);
/** Заполнение метаинформации */
Map<String, String> metaMap = new Hashmap<>();
metaMap.put("apiKey", "45834096-5765746893075477-6576")
metaCollector.update(metaMap);
Параметры, задаваемые с помощью profile коллектора
| Ключ параметра | Описание | Способ заполнения | Будет автоматизировано в будущих версиях |
| deviceId | Уникальный ID установки приложения на устройство | mProfileCollector.update | вероятно |
| sessionId | ID сессии | mProfileCollector.update | |
| appId | Идентификатор клиента в системе партнера | mProfileCollector.update | |
| subId | Идентификатор, который выдает единый сервис sberbank в процессе авторизации через SberbankID | mProfileCollector.update | |
| adId | Дополнительный Идентификатор клиента партнера Рекламный идентификатор. iOS - IDFA Android - gaid | mProfileCollector.update | |
| appVersion | Версия приложения | mProfileCollector.update | вероятно |
| applicationLanguage | Язык в приложении | context.getResources(). getConfiguration(). locale.getLanguage() | да |
Указание параметров в профайл-коллекторе аналогично мета-коллектору.
Настройка события
В качестве события используется класс SberbankAnalyticsEvent, который принимает Map\<String, String> для настройки. Строго определенные ключи хранятся в классе SberbankAnalyticsConstants.
Те ключи, которые не соответствуют ключам из класса SberbankAnalyticsConstants попадают в свойства события, которые представляют собой элемент "Ключ-значение".
| идентификатор параметра события | Описание параметра | Ключ**из SberbankAnalyticsConstants** | Способ заполнения |
| eventAction | Название события | Отсутствует, так как задается в конструкторе | Ручной, в зависимости от бизнеса |
| eventType | Тип события | EVENT_TYPE | Ручной, в зависимости от бизнеса |
| value | Значение события | VALUE | Ручной, в зависимости от бизнеса |
| eventCategory | Категория события | EVENT_CATEGORY | Ручной, в зависимости от бизнеса |
| geoLatitude | Широта устройства | GEO_LATITUDE | LocationManager manager = (LocationManager) context.getSystemService(Context.LOCATION_SERVICE); if (manager.isProviderEnabled(LocationManager.GPS_PROVIDER)) { return manager.getLastKnownLocation(LocationManager.GPS_PROVIDER); } else if (manager.isProviderEnabled(LocationManager.NETWORK_PROVIDER)) { return manager.getLastKnownLocation(LocationManager.NETWORK_PROVIDER); } else if (manager.isProviderEnabled(LocationManager.PASSIVE_PROVIDER)) { return manager.getLastKnownLocation(LocationManager.PASSIVE_PROVIDER); } String.valueOf(location.getLatitude()) |
| geoLongitude | Долгота устройства | GEO_LONGITUDE | // Аналогично geoLatitude String.valueOf(location.getLongitude() |
| cellularProvider | Интернетпровайдер | CELLULAR_PROVIDER | TelephonyManager manager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE); String carrierName = manager.getNetworkOperatorName(); |
| batteryLevel | Уровень заряда аккумулятора | BATTERY_LEVEL | import android.os.BatteryManager; // Intent.ACTION_BATTERY_CHANGED int level = batteryIntent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1); int scale = batteryIntent.getIntExtra(BatteryManager.EXTRA_SCALE, -1); String.valueOf(100 * level / (float) scale) |
| connectionType | Тип интернет соединения | CONNECTION_TYPE | "CELLULAR" | "WIFI" |
| appVersion | Версия приложения | APP_VERSION | |
| internalIP | IP адрес устройства | INTERNAL_IP |
Настройка отправляемого события:
SberbankAnalyticsEvent event = new SberbankAnalyticsEvent("eventName");
Map<String, String> eventParams = new HashMap<>();
eventParams.put(SberbankAnalyticsConstants.EVENT_TYPE, UserActionEventType.CLICK);
eventParams.put(SberbankAnalyticsConstants.VALUE, "someValue");
eventParams.put("someParamKey", "someParamValue");
event.addData(eventParams);
Разметка приложения
Разметка приложения представляет собой вызов метода sendEventилиsendSensetiveEvent при совершении целевого действия. Метод sendSensetiveEvent используется для отправки событий, содержащих чувствительную для пользователя информацию. При его использовании событие не будет сохранено в БД, а при поступлении такого события все накопленные до этого момента события будут отправлены немедленно.
Пример отправки события
ISberbankAnalytics sberbankAnalytics = new SberbankAnalytics.Builder(this)
.setAnalyticsMetaCollector(metaCollector, profileCollector)
.setNetworkFactory(networkFactory)
.setAnalyticsDbEnabled(true)
.setCustomUrl("https://someurl")
.build();
SberbankAnalyticsEvent event = new SberbankAnalyticsEvent("event");
sberbankAnalytics.sendEvent(event);
В качестве параметров события помимо кастомных используются:
EVENT_NAME - имя события
EVENT_TYPE - тип события, опционально
EVENT_VALUE - значение события, опционально
Доступные типы событий (из UserActionEventType):
CLICK - клик по элементу пользовательского интерфейса
SHOW - показ экрана
COPY - копирование информации из поля
DELETE - удаление информации из поля
FOCUS - фокусировка на элементе
INPUT - ввод информации в редактируемое поле
PASTE - вставка информации в редактируемое поле
START_DRAGGING - начало движения слайдера
STOP_DRAGGING - конец движения слайдера
UNFOCUS - смена фокусировки внимания с элемента
UNKNOWN - неизвестный тип
Использование совместно с SberID SDK (Sberbank SDK)
Если у вас в проекте уже используется Sberbank SDK, то вам не не нужно подключать SberVisor SDK (он уже встроен), так как иначе будет конфликт имен. Нужно следовать инструкции, за исключением подключения самого файла SDK.
Использование proguard
-dontwarn com.squareup.okhttp3.** -keep class com.squareup.okhttp3.* { *;}
Зафиксированные проблемы и их решения
| № | Зафиксированная проблема | Решение |
|---|---|---|
| 1 | зависимости от Yandex . Metrica | |
| 2 | При подставке продовского адреса в конфигурации, Вылетает ошибка 2022-03-18 18:26:40.023 4537-4654/ru.sberins.insureapp.android.debug W/System.err: java.util.concurrent.ExecutionException: java.lang.NullPointerException: Attempt to invoke virtual method 'java.util.SortedMap ru.sberbank.mobile.clickstream.db.processor.entities.SberbankAnalyticsMetaDBEntity.getMetaMap()' on a null object reference | Отключить БД в AndroidSDK с помощью метода setAnalyticsDbEnabled( false ) |
| 3 | Конфликт с Sberbank SDK | Исключить AndroidSDK из проекта , но все import’ы оставить, так как Sberbank SDK уже содержит все классы Andriod SDK. |