/
Android 4.3.1

Android 4.3.1

 

 

Ключевые отличия от SDK 1.x:

  • реализовано гибкое конфигурирование SDK

  • добавлена поддержка актуальных версий Android SDK

  • проведена оптимизация внутренней архитектуры

  • синхронизированы методы работы с SDK на платформах Android/iOS

  • реализовано Demo приложение для возможности тестирования на стороне клиента с примерами интеграций SDK

Предварительные условия

  • Для начала работы необходимо создать App ID в личном кабинете (см. инструкцию для пользователя)

  • SDK поддерживает версию Android API 21 и выше

1. Инсталляция

При подключении SDK в проект в результирующих пользовательских разрешениях могут быть добавлены следующие разрешения:

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

1.1. Добавление SDK в проект

  1. Для подключения SDK необходимо в файле build.gradle проекта указать репозиторий для  загрузки файла библиотеки:

allprojects { repositories { // ... maven { url "https://nexus.uxfeedback.ru/repository/android-sdk-new/" } } }

 

  1. В файле

build.gradle проекта необходимо добавить зависимость:

dependencies { // ... implementation 'ru.uxfeedback:sdk:4.0.0' }

Вместо 3.0.3 в строке выше необходимо указать номер версии, которую вы хотите использовать

1.1.1. ProGuard (обфускация кода): 

Для обфускатора proguard в SDK используются стандартные правила, которые описаны в файле consumer-rules.pro.

Вы можете указать правила вручную используя следующие правила для обфускации:

-keep class feedback.shared.sdk.api.network.entities.* { *; } -keep class com.google.gson.examples.android.model.** { <fields>; } -keep class * extends com.google.gson.TypeAdapter -keep class * implements com.google.gson.TypeAdapterFactory -keep class * implements com.google.gson.JsonSerializer -keep class * implements com.google.gson.JsonDeserializer

2. Использование SDK

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

Для инициализации SDK и создания экземпляра объекта SDK необходимо вызвать статический метод UxFeedback.setup.

В качестве значения appId необходимо указать App ID, полученный в личном кабинете.

Обратите внимание, что App ID обычно отличается для тестовых и продуктовых сред.

class YourApplication: Application(){ override fun onCreate() { super.onCreate() UxFeedback.setup(this, 'appId') } }

  • Инициализацию следует производить в потомке объекта Application, в методе onCreate. Поскольку SDK требуется доступ к сущности Activity, необходимо инициализировать SDK до её создания.

  • Инициализацию следует выполнять только один раз, повторные вызовы UxFeedback.setup игнорируются.

  • SDK самостоятельно обрабатывает повороты экрана при изменении жизненного цикла Activity

 

После инициализации, для получения экземпляра UxFeedback необходимо обращаться к свойству UxFeedback.sdk.

  • Вызов метода setup не является безопасным. Поэтому его стоит оборачивать в методы try/catch. Если во время вызова метода setup произошло исключение то полеUxFeedback.sdk равно null

Вы можете изменить некоторые настройки SDK используя свойства экземпляра UxFeedback

Пример использования:

UxFeedback.sdk?.settings.debugEnabled = true

В особых случаях допускается инициализировать в SDK в Activity (до вызова метода onResume по lifecycle).

2.2. Управление показом форм

Android SDK позволяет показывать формы опросов (кампании) основываясь на событиях (events), которые происходят в приложении.

2.2.1. Показ формы

Для показа формы необходимо вызвать метод startCampaign, для которого в качестве обязательного параметра следует использовать наименование события. Аналогичное наименования события должно быть указано в настройках кампании, задаваемых при её создании или редактировании через личный кабинет.

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

Пример использования:

someBtn.setOnClickListener(new View.OnClickListener() { public void onClick(View v) { // ... UxFeedback.sdk?.startCampaign('someEvent') } });

Показ формы необходимо вызывать только когда текущая activity находится в foreground.

Метод возвращает строку которая является уникальным идентификатором запущеной кампании, этот идентификатор возвращается в callbacks в виде параметра invocationId

2.2.2. Показ формы с дополнительными атрибутами

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

val attributes = UxFbAttributes() .addValue("stringValue", "Value") .addValue("floatValue", 2f) .addValue("doubleValue", 34) .addValue("booleanValue", true) .addValue("dateValue", Date()) UxFeedback.sdk?.startCampaign("dnd", attributes)

2.2.3. Типы дополнительных атрибутов

Для типа условия точное соответствие значения атрибутов в кампании возвращаются бэкендом в виде строки, значения атрибутов, получаемые из клиентского приложения преобразовываются к строке и сравниваются как строки.

Для типа условия содержит значения атрибутов в кампании также возвращаются бэкендом в виде строки, в сравнении участвуют только атрибуты переданные из клиентского приложения в виде строки, числа и булевые значения к строке не приводятся.

Даты от клиента приводим к строке вида 'YYYY-MM-DD'

Для типа условия диапазон чисел значения оставляем в том формате, как передано.

Для типа условия диапазон дат приводим полученное от бэкенда в объект даты. Полученные от клиента значения приводим к объекту даты и проверяем на принадлежность диапазону.

 

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

В случае если не задана начальная граница, проверка успешна если app.value <= campaign.valueTo

В случае если не задана конечная граница, проверка успешна если app.value >= campaign.valueFrom

2.2.4. Показ формы с передачей локальных properties

При показе формы существует также возможность передать локальные дополнительные параметры.

val properties: Map<String, String> = mapOf( "key1" to "value1", "key2" to "value2" ) UXFeedback.sdk?.startCampaign(eventName = "someEvent", properties = properties)

Описание работы локальных properties:

Локальные properties похожи на глобальные, но передаются в рамках вызова опроса и являются специфичными только для конкретного вызова.

Локальные properties передаются вместе с глобальными с ответом пользователя на вопросы формы.

2.2.5. Остановка показа формы

Показ формы может быть остановлен в любой момент. Для этого необходимо вызвать метод stopCampaign с пустой строкой в параметре.

В методе может быть указан параметр eventName который остановит показ определенной кампании

В этом случае окно формы будет закрыто, результаты опроса будут отправлены. Кроме того будет вызван метод uxFbOnTerminateCampaign листенера UXFbOnEventsListener

Пример использования:

someBtn.setOnClickListener(new View.OnClickListener() { public void onClick(View v) { // ... UxFeedback.sdk?.stopCampaign("") } });

 

2.3. Отправка дополнительных параметров

SDK предоставляет функцию отправки вместе с ответом пользователя на вопросы формы дополнительных данных. Например: userId , email, region или любые другие.

Для того чтобы отправить дополнительный параметр следует заполнить стандартную коллекцию типа MutableMap<String, String> , указав ключ и значение дополнительного параметра в свойстве properties SDK. Отправка дополнительных параметров осуществляется после инициализации, но до вызова метода startCampaign.

Пример использования:

UxFeedback.sdk?.properties?.put("key1","value1") UxFeedback.sdk?.properties?.put("key2","value2")

 

2.4. Настройка дизайна форм

В ресурсах SDK по умолчанию определены две темы: UXFBDarkTheme и UXFBLightTheme.

По умолчанию будет использована UXFBLightTheme.

Для того чтобы загрузить тему из ресурсов надо вызвать метод UxFbTheme.fromStyle

UxFeedback.sdk?.theme = UxFbTheme.fromStyle(R.style.UXFBDarkTheme)

Темы по умолчанию:

 

Разработчик может создать собственную тему, а также может наследоваться от существующих.

Параметры цветов необходимо взять из файла, который сформируют дизайнеры по ссылке: 

UXFB FORMS TEMPLATE (Light Dark Themes)  

Может переопределять свойства темы. Доступные для изменения свойства приведены ниже:

val bgColor: FeedbackColor val iconColor: FeedbackColor val text01Color: FeedbackColor val text02Color: FeedbackColor val text03Color: FeedbackColor val mainColor: FeedbackColor val errorColorPrimary: FeedbackColor val errorColorSecondary: FeedbackColor val btnBgColor: FeedbackColor val btnBgColorActive: FeedbackColor val btnTextColor: FeedbackColor val inputBgColor: FeedbackColor val inputBorderColor: FeedbackColor val controlBgColor: FeedbackColor val controlBgColorActive: FeedbackColor val controlIconColor: FeedbackColor val iconStarColor: FeedbackColor val iconSmile1Color: FeedbackColor val iconSmile2Color: FeedbackColor val iconSmile3Color: FeedbackColor val bgDisabledColor: FeedbackColor val fgDisabledColor: FeedbackColor val borderDisabledColor: FeedbackColor

UxFbColor - принимает значения в формате HexString (RGB, ARGB) или colorInt. При изменении одного из свойств второе рассчитывается автоматически.

UxFbDimen - принимает значения в dp или px. При изменении одного из свойств второе рассчитывается автоматически. Пересчет производится в зависимости от аппаратных характеристик устройства.

 

Пример использования:

UxFeedback.sdk?.theme?.bgColor?.hexString="#D81B60" UxFeedback.sdk?.theme?.bgColor?.intValue=Color.Black
UxFeedback.sdk?.theme?.formBorderRadius?.dpValue=14 UxFeedback.sdk?.theme?.formBorderRadius?.pxValue=140

 

Если в приложении будет изменен шрифт (через стиль), то этот же шрифт автоматически будет применен и для SDK.

2.5. Прочие настройки

Изменение настроек может быть вызвано в любом методе.

2.5.1. Время между показами кампаний

Если наступило событие, которое удовлетворяет условиям показа нескольких кампаний, то первой будет показана самая новая по дате создания кампания. Вторая кампания будет показа после прошествии указанного в этой настройке количества секунд.

Значение по умолчанию: 1800

При тестирование на вашей среде используйте минимальное значение globaldelay 1 секунду

Пример изменения настройки:

UxFeedback.sdk?.settings.startGlobalDelayTimer = 900

С версии SDK 2.2.0 изменение настройки GlobalDelay доступно через ЛК

Приоритет обработки значений следующий:

  1. Если значение получено в ответе на запрос кампаний к показу, то должно быть использовано значение атрибута showCampaignsIntervalAndroid/showCampaignsIntervalIos в зависимости от платформы.

  2. Если значение не получено, но задано в настройках при интеграции SDK, должно быть использовано заданное значение.

  3. Если значение не получено и не задано, то должно быть использовано значение по-умолчанию.

2.5.2. Блокировка интерфейса при показе формы в режиме slideIn

Настройка определяет блокируется ли основной интерфейс приложения при появлении формы. Если true - взаимодействие с интерфейсом приложения недоступно во время показа формы.  

Значение по умолчанию: false

Пример изменения настройки:

UxFeedback.sdk?.settings.slideInUiBocked = true

 

2.5.3. Настройки фона при показе формы в режиме slideIn

Разработчик может определять следующие параметры фона.

Настройки будут применены, только если значение настройки slideInUiBocked = true

slideUiBlackoutColor - цвет фона в hexString - #DDDC71

slideUiBlackoutOpacity - уровень прозрачности в процентах от 0 до 100

slideUiBlackoutBlur - уровень размытия в процентах от 0 до 100

Настройки могут быть установлены независимо друг от друга.

Значение по умолчанию:

slideInUiBlackoutColor - невидимый (прозрачный)

slideInUiBlackoutOpacity - 0

slideInUiBlackoutBlur - 0

Настройки могут быть установлены независимо друг от друга.

Пример изменения настройки:

UxFeedback.sdk?.settings.slideInUiBlackoutColor = #EEEB60 UxFeedback.sdk?.settings.slideInUiBlackoutOpacity = 10 UxFeedback.sdk?.settings.slideInUiBlackoutBlur = 10

 

2.5.4. Настройки фона при показе формы в режиме popUp

Разработчик может определять следующие параметры фона.

popupUiBlackoutColor - цвет фона в hexString - #DDDC71

popupUiBlackoutOpacity - уровень прозрачности в процентах от 0 до 100

popupUiBlackoutBlur - уровень размытия в процентах от 0 до 100

Настройки могут быть установлены независимо друг от друга.

Значения по умолчанию:

popupUiBlackoutColor - невидимый (прозрачный)

popupUiBlackoutOpacity - 0

popupUiBlackoutBlur - 0

Пример изменения настройки:

UxFeedback.sdk?.settings.popupUiBlackoutColor = #DDDC71 UxFeedback.sdk?.settings.popupUiBlackoutOpacity = 20 UxFeedback.sdk?.settings.popupUiBlackoutBlur = 20

 

2.5.5. Настройки обмена данными

Разработчик может изменять отдельные сетевые настройки, такие как:

socketTimeout - время ожидания при установлении соединения SDK к серверу UxFeedback в секундах

retryTimeout - время ожидания ответа сервера UxFeedback при успешном соединении в секундах

retryCount - количество повторных попыток отправки данных в штуках. Повторная попытка наступает если за время retryTimeout не удалось отправить данные. Если за заданный retryCount отправить данные не удалось, дальнейшие попытки прекращаются.

Значения по умолчанию:

socketTimeout - 25

retryTimeout - 300

retryCount - 10

Пример изменения настройки:

UxFeedback.sdk?.settings.socketTimeout = 25 UxFeedback.sdk?.settings.retryTimeout = 300 UxFeedback.sdk?.settings.retryCount = 10

 

2.5.6. Работа в нескольких процессах

Изначально SDK настроено на работу только в основном процессе.

Для указания процесса отличного от основного используется свойство processName в UxFbSettings

Пример:

UxFbSettings.getDefault().apply{ processName = :SecondProcess }

2.5.6. Поддержка кроссплатформенных решений

Для кроссплатформенных решений, при использовании SDK, иногда требуется, отличное от нативного использования, поведение. Для этого были реализованы настройки (свойства) targetPlatform и targetPlatformVersion в UxFbSettings

Пример:

UxFbSettings.getDefault().apply{

targetPlatform = UxFbTargetPlatform.FLUTTER (По умолчанию всегда NATIVE)

targetPlatformVersion = “1.0”

}

2.5.7. Тонкая настройка обработки жизненного цикла Activity

Для показа форм SDK автоматически выбирает Activity приложения и использует его для отображения. По умолчанию используется методы onStart и onStop жизненного цикла для определения текущего Activity. Для некоторых случаев (например как показ двух Activity) необходимо чтобы методы были изменены на onResume onPause либо SDK вообще не реагировал на определенную Activity была введена аннотация UxFbLifecycleActivity

которую следует разместить над классом Activity и указать требуемое поведение посредством аргумента UxFbLifecycleRule

Возможные варианты:

enum class UxFbLifecycleRule { /** * Activity обрабатывается в методе onStart жизненного цикла */ ON_START, /** * Activity обрабатывается в методе onResume жизненного цикла */ ON_RESUME, /** * Activity не обрабатывается (показ кампаний для такого Activity невозможен) */ SKIP }

  • Если пометить activity аннотацией не представляется возможным и изменить поведение необходимо то дополнительно был добавлен Extension applyToActivity для класса аннотации UxFbLifecycleActivity который позволяет в коде помечать указывать поведение SDK с конкретным Activity, пример вызова: UxFbLifecycleActivity(ON_RESUME).applyToActivity(this@MainActivity)

  • В UxFbSettings добавлено поле defaultLifecycleActivityRule с типом UxFbLifecycleRule, которое устанавливает поведение по умолчанию для всех Activity, за которыми следит SDK (то есть будет обработка на соответствующих методах показа Activity).

2.6. Контроль поведения SDK

2.6.1. Отслеживание отправки сообщений в журнал

Разработчик может в приложении использовать сообщения, генерируемые SDK. Например, с целью отладки.

Для этого в пользовательском приложении следует создать объект имплементирующий интерфейс UxFbOnLogListener

Экземпляр можно передать как при инициализации SDK в методе UxFeedback.setup, так и после, указав его в свойстве UxFeedback.logListener

Вызовом метода uxFbOnLog можно управлять через свойство UXFbSettings.debugEnabled.

Пример использования:

class YourApplication: Application(){ override fun onCreate() { super.onCreate() UxFeedback.setup(this, 'appId', UXFbSettings.getDefault(), campaignListener, logListener) } }

 

val logListener = object: UxFbOnLogListener{ override fun uxFbOnLog(message: String) { Toast.makeText(this@MainActivity, message, Toast.LENGTH_SHORT).show() } }

 

2.6.2. Отслеживание событий в SDK

Разработчик может использовать события, генерируемые SDK, чтобы управлять поведением собственного приложения.

Для этого в пользовательском приложении следует создать объект имплементирующий интерфейс UxFbOnEventsListener

Экземпляр можно передать как при инициализации SDK в методе UxFeedback.setup, так и после, указав его в свойстве UxFeedback.campaignListener

Пример использования:

class YourApplication: Application(){ override fun onCreate() { super.onCreate() UxFeedback.setup(this, 'appId', UXFbSettings.getDefault(), campaignListener) } }

 

SDK использует следующие события:

uxFbOnReady - вызывается при успешной инициализации SDK

uxFbOnStartCampaign - вызывается когда кампания стартовала, должно быть показано окно опроса.

uxFbOnFinishCampaign- вызывается когда кампания завершилась, т.е. пользователь прошел до последней страницы и закрыл её.

uxFbOnFieldsEvent - вызывается при завершении кампании, в map содержится пара идентификатор и значение для всех полей пройденной кампании (можно управлять UXFbSettings.fieldsEventEnabled).

uxFbOnTerminateCampaign - вызывается когда кампания была прервана закрытием диалога со стороны пользователя/приложения, не дошли до конца опроса. То есть все, что не закрыли по кнопке.

uxFbNoCampaignToStart - вызывается, если при вызове startCampaign нет кампании для показа по переданному событию

Пример использования:

val eventListener = object: UxFbOnEventsListener { override fun uxFbOnReady() { Toast.makeText(this@MainActivity, "uxFbOnReady", Toast.LENGTH_SHORT).show() } override fun uxFbOnStartCampaign(campaignId: Int, eventName: String) { Toast.makeText(this@MainActivity, "uxFbOnStartCampaign: " + campaignId, Toast.LENGTH_SHORT).show() } override fun uxFbOnFinishCampaign(campaignId: Int, eventName: String) { Toast.makeText(this@MainActivity, "uxFbOnFinishCampaign: " + campaignId, Toast.LENGTH_SHORT).show() } override fun uxFbOnFieldsEvent( campaignId: Int, eventName: String, fieldValues: Map<String, Array<String>> ) { Toast.makeText(this@MainActivity, "uxFbOnFieldsEvent: " + campaignId, Toast.LENGTH_SHORT).show() } override fun uxFbOnTerminateCampaign( campaignId: Int, eventName: String, terminatedPage: Int, totalPages: Int ) { Toast.makeText(this@MainActivity, "campaignId: " + campaignId, Toast.LENGTH_SHORT).show() } override fun uxFbNoCampaignToStart(eventName: String) { Toast.makeText(this@MainActivity, "uxFbNoCampaignToStart: " + eventName, Toast.LENGTH_SHORT).show() } }

 

2.7. Отладка

2.7.1. Включение режима debug

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

В продуктивной среде включение этого параметра не рекомендуется.

Пример использования:

UxFeedback.sdk?.settings.debugEnabled = true

2.7.2. Просмотр журналов

Для просмотра сообщений при включенном режиме отладки необходимо воспользоваться стандартной утилитой Logcat. Установите в качестве фильтра строку UxFeedback.

2.8. Автодокументация

2.9. UxDemoApplication

Рекомендуем посмотреть в код нашего тестового приложения UxDemoApplication, чтобы увидеть как SDK интегрируется в проект.

Подробности установки в http://README.md

https://github.com/uxfb/demo-sdk-android

3.0. Changelog

Версия SDK

Дата

Изменения

4.3.1

04.26

Исправлено:

  • Множественный показ

  • Фон на radiobuttons и checkbox

4.3.0

04.26

Исправлено:

  • Fix NullPointerException при закрытии дилога(редко)

Добавлено:

  • Передача уникального id вызова в ответе startCampaign() и колбэках жизненного цикла

4.2.1

03.26

Исправлено:

  • Баг с немутабельной мапой properties

4.2.0

02.26

Добавлено:

  • Обновление форм и компонентов

  • Изменение показа slideIn диалога

  • Передача локальных параметров в кампанию

4.1.3

02.26

Исправлено:

  • Костыль для скриншотов Flutter

4.1.2

11.25

Исправлено:

  • Передаются не все данные в ответе

4.1.1

11.25

Исправлено:

  • Удален старый костыль для TLS

4.1.0

11.25

Добавлено:

  • Поддержка изображений в блоках опросов

  • Обработка жизненного цикла Activity другим способом кроме аннотаций

Исправлено:

  • Баги

4.0.0

09.25

Добавлено:

  • Новая архитектура запроса кампаний

Исправлено:

  • Баги

3.0.4

07.25

Исправлено:

  • текст комментария уезжает под клавиатуру

3.0.3

05.25

Исправлено:

  • скриншоты для flutter

  • renderscript

3.0.2

04.25

Добавлено:

  • Реализовать выбор значения в числовом рейтинге и NPS по тапу на цифру

Исправлено:

  • slide in после скрытия клавиатуры остается в середине экрана

  • поведение тапа на элементы за формой опроса

3.0.1

04.25

Добавлено:

  • логирование атрибутов при старте

  • перемешивание ответов для checkbox

Изменено:

  • обработка исключений при вызове метода setup (вызывающая сторона сама должна обрабатывать исключения)

Исправлено:

  • проблема с транзитивными зависимостями версии 3.0.0

  • баг с атрибутами и задержкой при старте кампании

  • аннотация поворота экрана activity (по умолчанию)

  • мелкие ui баги

  • мелкие баги в логике

3.0.0

03.25

Большой рефакторинг

Добавлено:

  • форматирование заголовков

Изменено:

  • переход на compose и отказ от легаси зависимостей

2.9.3

03.25

Отказ от kotlin-reflect

2.9.2

02.25

Исправлено:

  • Баг c registerForActivityResult

2.9.1

02.25

Исправлено:

  • Баг c registerForActivityResult

2.9.0

12.24

Исправлено:

  • Баги. Логика показа

Добавлено:

  • новый блок в опросах - звезды ⭐️

2.8.2

10.24

Исправлено:

  • Crash class cast Exception

2.8.1