/
iOS 4.3.3

iOS 4.3.3

 

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

  • поддержка минимальной версии xcode 14 и выше

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

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

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

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

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

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

  • SDK поддерживает версию xcode версии 14 и выше

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

При подключении SDK в проект для поддержки функции добавления изображений из галереи в опрос необходимо в файле info.plist добавить строку конфигурации запроса разрешения, если эта строка отсутствовала:

<key>NSPhotoLibraryUsageDescription</key> <string>Добавление изображений к форме</string>

 

Актуальная версия UXFeedback SDK iOS расположена по адресу:

GitHub - uxfb/uxfbsdk-ios

Рекомендуем использовать самую свежую версию SDK

1.1 Интеграция в проект

Для интеграции в свой проект необходимо скопировать и добавить UXFeedbackSDK.xcframework в проект в секцию Framework, Libraries and Embedded Content:

1.2 Carthage

Для установки через Carthage необходимо прописать пути библиотек (содержимое Cartfile):

github "uxfb/uxfbsdk-ios"

И добавить UXFeedbackSDK.xcframework в проект в секцию Framework, Libraries and Embedded Content (см выше).

1.3 Cocoapods

Для установки через Cocoapods в Pod файле необходимо добавить путь к спецификации:

source 'https://github.com/uxfb/uxfbsdk-ios.git'

и указать сам pod:

pod 'UXFBSDK', '~> 4.3.0'

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

1.4 Swift Package Manager

Для установки через SPM нужно поставить Starred проекту https://github.com/uxfb, после чего в XCode выполнить: File → Add package → указать путь https://github.com/uxfb/uxfbsdk-ios.git → uxfbsdk-ios

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

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

Для начала работы с UXFeedback необходимо добавить библиотеку:

import UXFeedbackSDK

Затем необходимо выполнить инициализацию, в качестве appID передать, полученный ранее идентификатор приложения. Также необходимо передать настройки sdk, для передачи настроек по умолчанию нужно передать проинициализированный объект UXFBSettings.

Пример инициализации:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let settings = UXFBSettings() UXFeedback.setup(appID: 'appId', settings: settings)         return true     }

В случае использования SceneDelegate для iOS 13 и выше:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {     var window: UIWindow?      func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {         guard let _ = (scene as? UIWindowScene) else { return }    let settings = UXFBSettings()             UXFeedback.setup(appID: 'appId', settings: settings)         {  success in             //обработка инициализации         }     }     ... }

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

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

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

UXFeedback.sdk.settings.debugEnabled = true

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

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

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

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

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

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

override func viewDidLoad() { super.viewDidLoad() UXFeedback.sdk.campaignDelegate = self //может быть передано в методе setup let invocationId = UXFeedback.sdk.startCampaign(event: "event_name") }

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

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

let attributes = UXFBAttributesBuilder() .addValue("stringValue", value: "value") .addValue("intValue", value: 1) .addValue("doubleValue", value: 36.6) .addValue("booleanValue", value: true) .addValue("dateValue", value: Date()) .build() let invocationId = UXFeedback.sdk.startCampaign(eventName: "event", attributes: attributes)

Типы условий для атрибутов и описание их работы:

  • Точное соответствие. Бэкенд возвращает значения атрибутов в виде строк, значения атрибутов клиентского приложения приводятся к строке и происходит сравнение строк.

  • Содержит. Бэкенд возвращает значения атрибутов в виде строк, из клиентского приложения берутся атрибуты с типом строки (без чисел и булевых значений), и проверятся вхождение строк с учетом регистра.

  • Диапазон чисел. Из клиентского приложения берутся числовые значения и проверяется попадание их в диапазон. Если не задана нижняя граница, то проверяется по условию value <= campaign.valueTo, если не задана верхняя граница то проверяется по условию value >= campaign.valueFrom.

  • Диапазон дат. Из клиентского приложения берутся значения дат и проверяется попадание их в диапазон. Если не задана нижняя граница, то проверяется по условию value <= campaign.valueTo, если не задана верхняя граница то проверяется по условию value >= campaign.valueFrom.

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

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

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

let properties: [String: Any] = ["prop1": "value1", "prop2": "value2"] //значение properties типов string|integer|number let invocationId = UXFeedback.sdk.startCampaign(eventName: "event", localProps: properties)

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

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

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

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

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

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

func cancelCampaign() { UXFeedback.sdk.stopCampaign(eventForStop: String? = nil) }

 

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

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

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

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

UXFeedback.sdk.properties = ["email": "IvanIvanov@mail.ru", "userId": 42]

 

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

После инициализации UXFeedback есть возможность настроить собственную тему. Для этого нужно создать объект класса UXFBTheme и присвоить его свойству theme:

let theme = UXFBTheme() theme.iconColor = .blue UXFeedback.sdk.theme = theme

Также можно изменять цвета непосредственно через объект свойство theme:

UXFeedback.sdk.theme.iconColor = .green

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

UXFB FORMS TEMPLATE (Light Dark Themes)  

Значения параметров темы по умолчанию.

var text03Color: UIColor = UIColor.init("#8B90A0") var inputBorderColor: UIColor = UIColor.init("#D3D4D8") var iconColor: UIColor = UIColor.init("#B5B8C2") var btnBgColorActive: UIColor = UIColor.init("#1983C8") var btnBorderRadius: CGFloat = 4 var errorColorSecondary: UIColor = UIColor.init("#F4A0A3") var errorColorPrimary: UIColor = UIColor.init("#E84047") var mainColor: UIColor = UIColor.init("#0076C2") var controlBgColorActive: UIColor = UIColor.init("#DBF1FF") var formBorderRadius: CGFloat = 8 var inputBgColor: UIColor = UIColor.init("#F3F3F3") var text01Color: UIColor = UIColor.init("#232735") var controlBgColor: UIColor = UIColor.init("#F3F3F3") var controlIconColor: UIColor = UIColor.init("#FFFFFF") var btnBgColor: UIColor = UIColor.init("#0076C2") var text02Color: UIColor = UIColor.init("#505565") var btnTextColor: UIColor = UIColor.init("#FFFFFF") var bgColor: UIColor = UIColor.init("#FFFFFF") var iconStarColor: UIColor = UIColor.init("#FECA00") var iconSmile1Color: UIColor = UIColor.init("#FECA00") var iconSmile2Color: UIColor = UIColor.init("#232735") var iconSmile3Color: UIColor = UIColor.init("#E84047") var fontH1: UIFont = .systemFont(ofSize: 22, weight: .semibold) var fontH2: UIFont = .systemFont(ofSize: 17, weight: .semibold) var fontP1: UIFont = .systemFont(ofSize: 17, weight: .regular) var fontP2: UIFont = .systemFont(ofSize: 14, weight: .regular) var fontBtn: UIFont = .systemFont(ofSize: 16, weight: .semibold)

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

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

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

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

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

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

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

UXFeedback.sdk.settings.globalDelayTimer = 900

С версии SDK 2.2.0 изменение настройки GlobalDelay вынесено в ЛК.

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

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

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

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

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

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

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

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

UXFeedback.sdk.settings.slideInUiBlocked = true

 

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

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

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

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

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

slideInUiBlackoutBlur - уровень размытия в процентах от 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 - 5

retryTimeout - 300

retryCount - 3

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

UXFeedback.sdk.settings.socketTimeout = 25 UXFeedback.sdk.settings.retryTimeout = 300 UXFeedback.sdk.settings.retryCount = 10

2.5.6 Поведения при смахивании формы Slide-in. 

Параметр определяет закрыть или свернуть форму при смахивании (swipe) вниз. Если параметр установлен в true, то при смахивании форма опроса будет закрыта.

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

UXFeedback.sdk.settings.closeOnSwipe = true

 

2.5.7 Настройка поворота экрана

Параметр определяет будет ли автоматически поворачивать форма при повороте устройства

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

UXFeedback.sdk.settings.rotateToggle = true

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

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

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

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

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

 

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

func setup(appID: 'appId', settings: UXFBSettings, logDelegate: UXFeedbackLogDelegate )
UXFeedback.sdk.logDelegate = UXFeedbackLogDelegate
extension MainViewController_swift: UXFeedbackLogDelegate{ func logDidReceive(message: String) { } }

 

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

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

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

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

Для отслеживания информации о значениях заполняемых полей разработчику необходимо использовать свойство fieldsEventEnabled

UXFeedback.sdk.settings.fieldsEventEnabled = true

 

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

func setup(appID: 'appId', settings: UXFBSettings, campaignDelegate: UXFeedbackCampaignDelegate )

 

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

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

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

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

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

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

campaignDidSend - вызывается, когда ответы были отправлены на сервер платформы UXFeedback

campaignDidReceiveError - вызывается, когда произошла ошибка при работе с SDK

noCampaignToStart - вызывается, когда не найдено кампаний с указанным eventName

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

extension MainViewController_swift: UXFeedbackCampaignDelegate{ func campaignDidLoad(success: Bool) { } func campaignDidReceiveError(errorString: String) { } func campaignDidShow(campaignId: Int, eventName: String, invocationId: String) { } func campaignDidClose(campaignId: Int, eventName: String, invocationId: String) { } func campaignDidTerminate(campaignId: Int, eventName: String, terminatedPage: Int, totalPages: Int, invocationId: String) { } func campaignDidSend(campaignId: Int, invocationId: String) { } func campaignDidAnswered(campaignId: Int, answers: [String: Any], invocationId: String) { } func noCampaignToStart(eventName: String, invocationId: String) { } }

 

2.7. Отладка

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

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

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

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

UXFeedback.sdk.settings.debugEnabled = true

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

Логи можно просмотреть в output-области XCode:

 

3. Другое

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

Ссылка на автодокументацию будет размещена позднее

3.2 UXFeedback Demo

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

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

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

Сhangelog

Версия SDK

Дата

Изменения

4.3.3

05.26

Исправлено:

  • Плавающий краш при старте кампании

4.3.2

04.26

Исправлено:

  • проверка аттрибутов (точное соответствие, содержит, диапазон дат, диапазон значений)

4.3.1

04.26

Исправлено:

  • Дублирование делегатов

4.3.0

04.26

Исправлено:

  • краш при недоступности хранилища CoreData

  • краш при формировании ссылки по appId

  • логика показа блоков опроса при вводе в текстовое поле

Добавлено:

  • Определение и передача языка на сервер

  • Добавление invocationId в события жизненного цикла кампании

  • Новая логика проверка аттрибутов с типом list

4.2.1

03.26

Исправлено:

  • отображение компонентов для Flutter

4.2.0

02.26

Добавлено:

  • Новый дизайн компонентов

  • Поле описание для заголовков

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

  • Адаптивная высота кампании slideIn

  • Обновление глобальных properties

Исправлено:

  • обработка исключения CoreData

  • обрезание текста опроса

4.1.0

11.25

Добавлено:

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

Исправлено:

  • краш при вызове startCampaign до получения списка кампаний

  • передача пустых ответов недосказанных страниц

  • отображение текста в чекбоксах

4.0.2

10.25

Добавлено:

  • аннотация objc для startCampaign

4.0.1

10.25

Добавлено:

  • аннотация objc для аттрибутов

  • дополнительные проверки при вызове кампании с таргетингом на список аттрибутов

4.0.0

10.25

Добавлено:

  • Метод stopCampaign, добавлен опциональный параметр для остановки конкретной кампании

  • Скелетон при загрузке картинок

  • Хранение картинок в файловом кеше

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

  • Новый контракт получения кампаний

Исправлено:

  • Перекрытие кнопки клавиатурой при маленьком размере popup формы

3.0.3

06.25

Исправлено:

  • оптимизирована работа СДК (утечки памяти и троттлинг)

  • исправлена ошибка некликабельной области над опросом slideIn

  • ошибка появления серого фона при открытии опроса

Добавлено:

  • возможность конфигурирования цвета смайлов и звезд

  • добавлен appId в ответе

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

3.0.2

04.25

Исправлено:

  • ошибка при отправке аттрибутов

  • скролл в попапе

  • тап в числовом рейтиниге

  • фиксы отображения переданных

3.0.1

04.25

Добавлено:

  • делегат noCampaignToStart

Исправлено:

  • скролл в попап форме

3.0.0

03.25

Добавлено:

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

Изменено:

  • переход на декларативный UI

  • стартовое положение ползунков числового рейтинга и nps

Исправлено:

  • ошибка несрабатывание кнопки при первичном заполнении обязательного поля

  • ошибка отсутствия скролла до обязательного поля

2.9.3

02.25

Исправлено:

  • проверка числовых атрибутов по правилу equals

2.9.2

01.25

Исправлено:

  • ошибка при проверке атрибутов в диапазоне

Добавлено:

  • Логгирование списка атрибутов при старте кампании

2.9.1

12.24

Исправлено:

  • переносы строк

2.9.0

12.24

Добавлено:

  • дебаг символы dSYMs

  • передача campaignId в методах FeedbackCampaignDelegate

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

2.8.1

10.24

Исправлено:

  • создание скриншотов на платформе Flutter

2.8.0

09.24

Добавлено:

  • utm метка

Исправлено:

  • перенос текста в опросе

  • настройка slideInUiBlocked

  • поведение поля email

  • проблема при повороте экрана

2.7.0