¶ SFERRA
¶ Описание
SFERRA — специализированный мобильный браузер с расширенными возможностями, который может использоваться для доступа к web-ресурсам и персонализируется под работу с личным кабинетом организации только после скачивания.
SFERRA позволяет устранить все недостатки адаптивного web-сервиса и превратить его в полный аналог нативного приложения на смартфоне, которое всегда будет актуальным и доступным для клиента.
¶ Состав
SFERRA состоит из следующих частей:
¶ Клиентская часть (Приложение SFERRA)
Приложение для мобильных платформ iOS (14 и выше) и Android (7 и выше), выполняющее следующие функции:
- Отображение ЛК с использованием WebView;
- Получение Push-уведомлений;
- Сбор параметров и формирование отпечатка устройства;
- Предоставление ЛК (WebView) доступа к нативным функциям устройства;
- Подтверждение операций в ЛК с использованием функциональности PayControl.
¶ Серверная часть
Серверной частью SFERRA является набор серверных компонентов ПК PayControl (https://docs.paycontrol.org/en/PayControl/tech/architecture_principles).
¶ PC Server
Интегрируется с серверной частью прикладной системы и выполняет следующие функции:
- Регистрация пользователей в SFERRA;
- Генерация и обновление ключевой информации пользователей SFERRA для использования функциональности PayControl;
- Регистрация адресов устройств для доставки Push-уведомлений;
- Управление процессом подтверждения операций в ЛК;
PC Server должен быть установлена в пределах периметра безопасности прикладной системы.
¶ PC External
Выполняет функции по взаимодействию с мобильным приложением.
PC External представляет собой приложение для развёртывания в рамках существующего сервера приложений. Доступ к функциям PC External со стороны прикладной системы не осуществляется. С ним взаимодействуют с одной стороны PC Server, с другой – клиентская часть (SDK PayControl в приложении SFERRA).
¶ PC Pusher
Выполняет функции по отправке в мобильное приложение push-уведомлений о необходимости подтверждения операций в ЛК.
PC Pusher представляет собой приложение для развёртывания в рамках существующего сервера приложений. Доступ к функциям PC Pusher со стороны прикладной системы не осуществляется. С ним взаимодействует только PC Server.
С использованием PC Pusher направляются только Push-уведомления с информированием о наличии операций для подтверждения. Для направления информационных уведомлений возможно использовать решение PayControl Inform (https://safe-tech.ru/paycontrol-inform/), или аналогичные сервисы.
¶ Принцип работы
После установки на мобильное устройтво, SFERRA представляет из себя "пустое" приложение, которое содержит "под капотом" функциональность приложения PayControl, компонент WebView, а также поддержку нативных функций мобильного устройства.
После перехода по специализированному Deep Link, содержащему ссылку на файл конфигурации, SFERRA выполняет процесс Конфигурирования приложения в рамках которого WebView настраивается на домашнюю страницу ЛК. При последующем открытии приложения, домашняя страница ЛК будет являться главным экраном SFERRA.
После Конфигурирования приложения, ЛК, открытый через WebView SFERRA получает возможность:
- Использовать нативные функции устройства благодаря поддержке соответствующих API;
- Использовать фукциональность PayControl с применением технологии Deep Link.
¶ Конфигурирование приложения
Для конфигурирования приложения SFERRA требуется получение настроек из файла конфигурации, а также создание пользователя PayControl.
¶ Подготовка файла конфигурации
Файл конфигурации должен быть размещен на ресурсе позволяющем получить к нему сетевой доступ со стороны мобильного устройства и иметь следующий формат:
"config":{
"version": 1,
"gost": false,
"homepage":"https://company.site/", //Адрес главной страницы ЛК
"webview_white_list":[ //"Белый список" адресов
"https://partner1.site/",
"https://partner2.site/",
"https://partner3.site/page/"
],
"created_at": 1678700125 //Дата создания конфигурации
}
}
version - версия конфигурации;
gost - режим передачи данных ГОСТ TLS (на текущий момент не используется);
homepage - адрес web-страницы ЛК, которая будет отображаться при входе в приложение SFERRA после конфигурирования;
webview_white_list - список "белых адресов" сайтов, переход по которым будет осуществлен внутри приложения SFERRA. Сайты не входящие в данные список будут открываться в мобильном браузере. В некоторых версиях приложения можно использовать маски вида *.ru. Например, для указания суб-доменов;
created_at - дата создания конфигурации, используется при добавлении новой конфигурации.
¶ Дополнительные возможности
Файл конфигурации может сформирован и подписан согласно стандарта JWT (JSON Web Token).
Описание стандарта JWT - https://jwt.io/introduction
¶ Создание пользователя PayControl и добавление в Deep Link параметра для конфигурирования
Для дальнейшего конфигурирования необходимо выполнить создание пользователя с использованием одного из следующих запросов к PC Server:
- Deep Link - https://repo.paycontrol.org/server/doc/latest/rest-api/en/#-deep-link-to-be-sent-or-shown-online
- Deep Link with Activation Code - https://repo.paycontrol.org/server/doc/latest/rest-api/en/#-deep-link-with-activation-code-to-be-sent-or-shown-online
В параметре url_template необходимо передать значение URL-схемы "SFERRA" и дополнить параметром "appConfig", ссылающийся на конфигурационный файл.
"url_template": "sferra://user_key?key_json=%KEY_URLENCODED%&appconfig=%URL%", где
URL - Адрес файла конфигурации.
Значение, полученное в параметре key_deep_link ответа на запрос необходимо передать пользователю для открытия на мобильном устройстве с приложением SFERRA.
Также, сформированное значение можно передать в QR-коде, в случае работы пользователя в нескольких каналах (инициирует процесс на ПК, а на телефоне настраивает приложение SFERRA).
В зависимости от реализуемого сценария, конфигурирование на стороне мобильного устройства может выполнено одним шагом с персонализацией (формированием ключей PayControl) или в два шага (сначала добавление конфигурации, а после добавления информация для персонализации).
¶ Сценарий конфигурирования
¶ Альтернативный вариант конфигурирования
В данном варианте Deep Link для конфигурации содержит только ссылку на файл конфигурации, а данные для персонализации будут переданы вторым Deep Link. После конфигурирования приложения WebView будет только настроен на домашнюю страницу ЛК. После авторизации в нем, предполагается получение второго Deep Link для создания ключей PayControl для подтверждения транзакций в приложении.
¶ Формирование Deep Link для конфигурирования
Deep Link для конфигурирования должен соответствовать следующему формату:
sferra://config_address?app_config=%URL%, где
URL - адрес размещения файла конфигурации.
Пример:
sferra://config_address?app_config=https%3A%2F%2Fdev.paycontrol.org%2Fsferra-config%2Fsferra-demo-dev.json
Полученный Deep Link можно разместить в личном кабинете пользователя, выслать по электронной почте/смс (используя шортанайзеры), либо отобразить в виде QR-кода.
¶ Формирование Deep Link для персонализации
Для получение Deep Link для персонализации необходимо использовать стандартный запрос создание\обновление пользователя за исключением отсутствием в параметра url_template ссылки на конфигурацию.
- Deep Link - https://repo.paycontrol.org/server/doc/latest/rest-api/en/#-deep-link-to-be-sent-or-shown-online
- Deep Link with Activation Code - https://repo.paycontrol.org/server/doc/latest/rest-api/en/#-deep-link-with-activation-code-to-be-sent-or-shown-online
Пример:
sferra://user_key?key_json=%7B%22pc_key_version%22%3A7%2C%22system_id%22%3A%22f13e4375-e429-496c-ad1e...C%22is_delayed%22%3Afalse%2C%22ext _auth_available_methods%22%3A%5B%22codeword%22%5D%7D
Полученный Deep Link можно разместить в личном кабинете пользователя, выслать по электронной почте/смс (используя шортанайзеры), либо отобразить в виде QR-кода.
¶ Сценарий конфигурирования
¶ Использование нативных функций
SFERRA позволяет ЛК, открытым через WebView приложения, получить доступ к нативным функциям устройства. Для этого реализована поддержка следующих API:
¶ Адресная книга (Контакты)
https://developer.mozilla.org/en-US/docs/Web/API/Contact_Picker_API
Используется нативная реализация, копирующая API представленный в спецификации выше.
¶ Доступ к камере
https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia
Перечень нативных функций в будущем будет расширен
¶ Подтверждение операций
Подтверждение операций при использовании SFERRA осуществляется механизмами PayControl.
Для реализации сценария подтверждения требуется отправить запрос на создание транзакции к серверу PayControl со специализированными параметрами, а также разместить в интерфейсе ЛК Deep Link данной транзакции.
¶ Создание транзакции
Создание транзакции осуществляется путем вызова сервера PayControl - https://repo.paycontrol.org/server/doc/latest/rest-api/en/#create-transaction
Обязательные к использованию с приложением SFERRA параметры запроса:
"app_start_deeplink_template" : "sferra://start_confirmation?user_id=%USER_ID%&transaction_id=%TRANSACTION_ID%"
При передаче данного параметра в ответе на запрос создание транзакции будет возвращен Deep Link, который нужно будет разместить в ЛК для старта подтверждения.
"app_extra" : "{\"app_callback_deeplink\":\"%URL%\"}"
В данном пареметре требуется указать URL страницы ЛК, куда будет перенаправлен пользователь после подтверждения транзакции.
¶ Сценарий подтверждения
¶ Дополнительные возможности
"transaction_type" : "WITH_BACKEND_CHECK"
Данный параметр позволяет не отображать пользователю весь контент транзакции, а лишь запросить ввод пароля или вызов биометрии для подтверждения. Актуально для сценариев, когда данные операции уже показывались пользователю экраном ранее в WebView-форме.
¶ Навигационные ссылки
SFERRA позволяет выполнять обработку навигационных ссылок полученных в Push-уведомлениях и/или DeepLink.
Если полученная ссылка попадает в диапазон "Белого списка", по после перехода по ней будет выполнено открытие WebView SFERRA по указанному адресу.
Для работы функциональности требуется сформировать DeepLink/Push в следущем формате:
- Deeplink
sferra://navigation_url?url=%URL%
Где URL - это адрес, по которому должен быть осуществлен переход.
- Push-уведомление
Android
{
"data":{
"navigation_url":"%URLl%"
"navigation_label" : "%TEXT%"
}
}
Где:
URL - это адрес, по которому должен быть осуществлен переход.
TEXT - текст для всплывающего сообщения в интерфейсе.