Description

Push уведомления это универсальный инструмент распространения информации, данные поступают от сервера к клиенту на основе ряда параметров, запрос на передачу информации происходит по инициативе Банка.

Push уведомления могут использоваться для информационной рассылки сообщений или pin для подтверждения операции при двух-факторной аутентификации аналогично СМС. Push уведомления могут быть доставлены на устройства в которых отсутствует sim-карта, например планшеты.

Кроме того Push-уведомления открывают для маркетинга неограниченные возможности по кастомизации предложений для каждого сегмента клиентов Банка.

Фактически, push является ссылкой на любое действие, которое Банк хочет предложить клиенту, например:

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

iDa Pro to Bank Proxy

www.websequencediagrams.com

participant Mobile as mob
participant iDaPro as pro
participant iDaPiGeon as pig
participant Bank Proxy as bank

mob->pro: registerDevice()
pro->pig: exists()
alt exists true
    pro->pig: updateToken()
else exists false
    pro->bank: checkSubscriptionAuthorized()
    alt checkSubscriptionAuthorized true
        pro->pig: subscribe()
    else checkSubscriptionAuthorized false
        pro->bank: authorizeSubscription()
        bank-->mob: send SMS with code
        pro->bank: verifySubscriptionAuthorization()
        alt code ok
            pro->pig: subscribe()
end

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

Мобильное приложение инициирует регистрацию устройства на iDa Pro
iDa Pro проверяет iDa Pigeon, зарегистрировано ли устройство
Если устройство не зарегистрировано, iDa Pro инициирует запрос к proxy на отправку одноразового пароля
Банк отправляет одноразовый пароль, который вводится в мобильном приложении
Мобильное приложение отправляет в iDa Pro введенный код, который маршрутизируется в системы банка
Если пароль верный, iDa Pro отправляет в iDa PiGeon запрос на регистрацию устройства

checkSubscriptionAuthorized

Проверка наличия подтвержденной подписки

key	type	status	comment
Request:
bankClientId	string	1..1	идентификатор клиента
userId	string	1..1	идентификатор клиента внутри системы Банка (обычно - логин)
deviceId	string	1..1	уникальный код устройства (обычно VENDOR_ID железа телефона)
platform	string	1..1	мобильная платформа {ANDROID, IOS}
Response:
authorized	bool	1..1	флаг, обозначающий, что клиент уже ранее подтвердил (например, через SMS) заинтересованность в подписке
Exception:
BankClientNotExistsException	string	0..1	клиент с запрошенным bankClientId не существует

authorizeSubscription

Запрос на инициацию авторизации подписки (например, отправка секретного переменного кода на мобильный телефон клиента посредствам SMS)

key	type	status	comment
Request:
bankClientId	string	1..1	идентификатор клиента
userId	string	1..1	идентификатор клиента внутри системы Банка (обычно - логин)
deviceId	string	1..1	уникальный код устройства (обычно VENDOR_ID железа телефона)
platform	string	1..1	мобильная платформа {ANDROID, IOS}
Response:
result	string	1..1	флаг, обозначающий, что операция авторизация подписки инициирована {OK, ERROR}
Exception:
BankClientNotExistsException	string	0..1	клиент с запрошенным bankClientId не существует

verifySubscriptionAuthorization

Проверка корректности введенного переменного кода

key	type	status	comment
Request:
bankClientId	string	1..1	идентификатор клиента
userId	string	1..1	идентификатор клиента внутри системы Банка (обычно - логин)
deviceId	string	1..1	уникальный код устройства (обычно VENDOR_ID железа телефона)
verificationCode	string	1..1	код, введенный пользователем для подтверждения подписки
Response:
result	string	1..1	флаг, обозначающий, что операция авторизация пройдена успешна {OK, VERIFICATION_FAILED}
Exception:
BankClientNotExistsException	string	0..1	клиент с запрошенным bankClientId не существует

iDa PiGeon to Bank Proxy

reportNotificationExpired


написать!!!

Доставка банку сообщения о неполучении пользователями сообщений. Данный метод вызывается после истечение срока доставки (timeout), заданного для конкретного сообщения

key	type	status	comment
Request:
userId	string	1..1	список идентификаторов пользователей не получивших сообщение за период жизни timeout сообщения
notificationId	string	1..1	id сообщения, которое не было получено
Response:

Bank Proxy to iDa PiGeon

www.websequencediagrams.com

participant Bank as B
participant Pigeon as P
participant "iDa Pro" as Pro
participant Cloud Messaging Service as CM
participant Mobile as M

B->P: pushSend(). В данном сообщении передается \nвся информация о содержимом Push-уведомления
P->CM: Отправка push-уведомления
CM->M: Отправка push-уведомления
M->M: Пользователь открывает push-уведомление

M->Pro: pushIsOpened()
    Pro->P: pushIsOpened()
    P->B: pushIsOpened()

alt В push нет запроса pushGetDetails()
    M->M: Показ содержимого push-уведомления\nв мобильном приложении в\n зависимости от типа уведомления
else В push есть запрос pushGetDetails()
    M->+Pro: pushGetDetails()
    activate M
    Pro->P:pushGetDetails()
    P-->Pro: Детали push
    Pro-->M: Детали push
    deactivate Pro
    M->-M: Показ содержимого push-уведомления\nв мобильном приложении
end

В данном разделе описаны запросы от банковского проксирующего сервера к сервера iDa PiGeon

Пример реализации отправки

Банк инициирует отправку сообщения в iDa PiGeon
iDa PiGeon отправляет сообщение на мобильные устройства. В случае, если устройство не зарегистрировано, отправляет соответствующее сообщение об ошибке
Если на мобильном устройстве открыли уведомление, то приложение отправляет информацию об этом событии
Если для показа уведомление нужны дополнительные детали, то производится соответствующий запрос. Если нет, то показывается содержимое push-уведомления

sendNotification

Request:

<sendNotification>
   <notification>
      <details>
         #
         # details
         #
      </details>
      <id>push_id</id>
      <pushContent>
         #
         # pushContent
         #
      </pushContent>
      <recipients>id_user_1</recipients>
      <recipients>id_user_2</recipients>
      <timeout>1000</timeout>
   </notification>
</sendNotification>

Response:

<sendNotificationResponse xmlns:ns2="http://inbound.sbi.pigeon.idamobile.com/">
   <return>
      <status>OK</status>
      <deliveryStatus>
         <entry>
            <key>id_user_1</key>
            <value>QUEUED</value>
         </entry>
         <entry>
            <key>id_user_1</key>
            <value>INVALID_SUBSCRIPTION</value>
         </entry>
      </deliveryStatus>
   </return>
</sendNotificationResponse>

Отправка PUSH нотификации

key	type	status	comment
Request:
id	string	1..1	уникальный идентификатор
recipients	string	1..1	получатель сообщения
timeout	int	1..1	время жизни сообщения в секундах
pushContent	pushContent	1..1	обязательная часть пуш сообщения
pushDetails	pushDetails	0..1	дополнительные детали запрашиваемые мобильным устройством по необходимости
perishable	bool	0..1	признак только единственной попытки доставки сообщения до клиента
priority	int	0..1	приоритет отправки
Response:
status	status	1..1	статус сервера по доставке
errorMessage	string	0..1	описание возможной ошибки
deliveryStatus	deliveryStatus	0..1	результат отправки сообщения

status

Общее сообщение с результатом выполнения команды

key	comment
OK	операция выполнена успешно
ENTITY_NOT_FOUND	объект, над которым требуется выполнить операцию удален или не существовал
DUPLICATED_ENTITY	идентификатор уже был использован ранее
INTERNAL_SERVER_ERROR	внутренняя ошибка сервера

deliveryStatus

Статус доставки PUSH-уведомления

key	comment
QUEUED	уведомление принято сервером и ожидает отправки (первый признак у сообщения, технического толка)
SENT	уведомление отправлено
SENDING_FAILED	ошибка отправки уведомления
DELIVERED	уведомление доставлено на мобильный
READ	уведомление прочитано пользователем
INVALID_SUBSCRIPTION	неверный код подписки (user_id отменил подписку)
EXPIRED	сообщение не удалось отправить и дальнейшие попытки отправки не предпринимаются из-за истекшего timeout

getNotificationDetails

Получение подробностей уведомления

key	type	status	comment
Request:
id	string	1..1	уникальный идентификатор
Response:
status	status	1..1	статус сервера по доставке
errorMessage	string	0..1	описание возможной ошибки
notification	notification	0..1	тело сообщения

getDeliveryStatus

Данный запрос вызывается, когда банку необходимо проверить параметры доставки сообщения

key	type	status	comment
Request:
id	string	1..1	уникальный идентификатор
Response:
status	status	1..1	статус сервера по доставке
errorMessage	string	0..1	описание возможной ошибки
deliveryStatus	deliveryStatus	1..1	результат отправки сообщения

deleteSubscription

Данный запрос вызывается в случае, когда банку необходимо отписать пользователя user_id от push-увеломлений. При этом стирается все токены устройств (если их было несколько)

key	type	status	comment
Request:
user	string	1..1	уникальный идентификатор пользователя
Response:
status	status	1..1	статус сервера по доставке
errorMessage	string	0..1	описание возможной ошибки

checkSubscriptionExists

Request:

<checkSubscriptionExists>
    <user>login_1</user>
</checkSubscriptionExists>

Response:

<checkSubscriptionExistsResponse xmlns="http://inbound.sbi.pigeon.idamobile.com/">
   <return>
      <status>OK</status>
      <exists>true</exists>
   </return>
</checkSubscriptionExistsResponse>

Проверка состояния подписки нескольких пользователей

key	type	status	comment
Request:
user	string	1..1	уникальный идентификатор пользователя
Response:
status	status	1..1	статус сервера по доставке
errorMessage	string	0..1	описание возможной ошибки
exists	bool	1..1	наличие пользователя в базе получателей пушей

Data Structs

Серверная часть в решении iDa Light является базовой составляющей и отвечает за хранение, преобразование и отображение всей информации. При запуске сервер загружает из СУБД большинство данных и производит их кэширования для ускорения работы и уменьшения нагрузки на СУБД

pushContent

<pushContent>
   <badge>0</badge>
   <details>
      <entry>
         <key>target</key>
         <value>nil</value>
      </entry>
   </details>
   <sound>default</sound>
   <text>Текст для отображения в шторке телефона</text>
   <type>UNIVERSAL</type>
</pushContent>

Дополнительные детали по пушу или экран ошибки

key	type	status	comment
badge	int	1..1	бэйджик на иконке App с количеством сообщений. перезаписывается при каждом новом пуше
sound	string	0..1	по умолчанию default
text	string	1..1	текст для пуша в шторке мобильного
type	pushType	1..1	тип сообщения
target	string	1..1	в зависимости от типа пуша передается id формы, точки, код подтверждения… или nil

pushType

В рамках сервиса отправки пуш уведомлений поддерживаются следующие типы сообщений

key	target	comment
UNIVERSAL		универсальное пуш-уведомление
PRODUCT	product_id	переход на экран деталей продукта в мобильном приложении
FORM	form_id	переход на экран формы в мобильном приложении
SHOW_MAP	map_id	переход на экран карты с выбранной точкой на карте
URL	url	переход на URL-адрес страницы
PIN_CODE	string	код подтверждения платежа
MESSAGE		переход в раздел `PERSONAL_NEWS` в мобильном приложении

pushDetails

<details>
   <entry>
     <key>logo_url</key>
     <value>http://www.idamob.ru/ic.png</value>
   </entry>
   <entry>
     <key>push_description</key>
     <value>Текстовый блок с некоторым описанием</value>
   </entry>
   <entry>
     <key>name</key>
     <value>Заголовок сообщения</value>
   </entry>
   <entry>
     <key>currency</key>
     <value>100000000</value>
   </entry>
   <entry>
     <key>fxAmount</key>
     <value>RUR</value>
   </entry>
   <entry>
     <key>Период</key>
     <value>3 года</value>
   </entry>
   <entry>
     <key>Процент</key>
     <value>3%</value>
   </entry>
</details>

Дополнительные детали по пушу или экран ошибки

key	type	status	comment
logoUrl	string	0..1	ссылка на логотип или картинку, отображается на форме 64х64
name	string	1..1	заголовок пуш-сообщения в одну строку
pushDescription	string	0..1	многострочный текст для деталей пуш-сообщения в шапке экрана
tags	MarkerDTO	0..1	массив маркеров-деталей для показа списком
amount	AmountDTO	0..1	сумма в валюте для деталей пуш-уведомления

MarkerDTO

key	type	status	comment
key	string	1..1	идентификатор маркера
value	string	0..1	информация, привязанная к маркеру

AmountDTO

key	type	status	comment
currency	string	1..1	текстовый код валюты по ISO 4217
fxAmount	int	1..1	сумма помноженная на 100 для отображения копеек

FAQ

Порядок установки серверной части iDa Mobile

Общие шаги

Произвести установку СУБД PostgresSQL
При помощи утилиты pgAdmin (обычно входит в дистрибутив PostgreSQL) подключиться к СУБД
Создать новую роль (пользователя)
Создать новую БД с указанием созданной в п.3 роли в качестве владельца создаваемой БД
Установить Apache Tomcat, при желании - настроить работу Apache Tomcat с протоколом SSL (можно выполнить позднее)
В файле /tomcat/conf/server.xml сконфигурировать секцию GlobalNamingResources>
Запустить Apache Tomcat (в случае с linux - ./tomcat/bin/startup.sh, в случае с windows вомпользоваться специальной системной службой)

Установка iDa PiGeon

Скопировать файл pigeon.war в папку /tomcat/webapps и дождаться пока будет автоматически создана подпапка /PiGeon
Открыть через pgAdmin требуемую БД и проверить, что добавились таблицы

Порядок обновления серверной части iDa Mobile (*.war)

Получить новую сборку в виде файла *.war
Открыть файл *.war при помощи ZIP-архиватора и перейти в подпапку *.war\WEB-INF\classes\META-INF
Открыть файл persistence.xml и внести соответствующие правки, необходимые для подключения к БД (параметры: hibernate.connection.url, hibernate.connection.username, hibernate.connection.password).
Заменить в *.war файле persistence.xml на тот, который был отредактирован в п.3
Убедится, что серверй приложений Tomcat запущен (в linux - ps -ef|grep tomcat). Если не запущен - запустить его (в linux - ./tomcat/bin/startup.sh).
Перейти в папку tomcat/webapps
В случае наличия в ней старой версии iDa - удалить файл *.war и дождаться пока папка обновляемого приложения удалится автоматически (~ 15 секунд)
Скопировать в папку /tomcat/webapps/ полученный в п.4 файл *.war
Дождаться пока в папке /tomcat/webapps появится папка с наименованием приложения (~ 15 секунд)
Осуществить проверку работы приложения при помощи настроенного мобильного клиента

Пример wsdl

pigeon server - http://dev.idamob.ru/pigeon/services/SBIInboundWebService?wsdl

Открываемые порты

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

Apple : support.apple.com/en-us/HT203609 Google : accesses the GCM servers on ports 5228-5230

Конфигурирование сервиса

<Environment name="apnsCertificatePath" value="/var/cert/unimegabank.p12" type="java.lang.String"/>
<Environment name="apnsPassword" value="12345" type="java.lang.String"/>
<Environment name="apnsIsProduction" value="false" type="java.lang.Boolean"/>

<Environment name="gcmAuthKey" value="XXXXXXXXXXXXXXXXXXXXXXXXXXX" type="java.lang.String"/>

<Environment name="dbUrl" value="jdbc:postgresql://localhost/pigeon" type="java.lang.String"/>
<Environment name="dbUsername" value="test" type="java.lang.String"/>
<Environment name="dbPassword" value="testpassword" type="java.lang.String"/>

<Environment name="sbiOutboundWebServiceURL" value="http://dev.idamob.ru/sbi-outbound-stub/services/SBIOutboundStub" type="java.lang.String"/>

<Environment name="overrideSubscriptions" value="false" type="java.lang.Boolean"/>

<Environment name="caseInsensitiveIds" value="false" type="java.lang.Boolean"/>

<Environment name="deviceExpiredPeriodMillis" value="2592000000" type="java.lang.Long"/>

Все настройки сервиса задаются через файл конфигурирования Apache Tomcat, который расположен по адресу $TOMCAT_HOME/conf/server.xml путём добавления в тэг следующих параметров:

key	comment
apnsCertificatePath	настройка подключения к APNS. сертификат сгенерированный для Apple, генерится при наличии доступа в кабинет разработчика Apple
gcmAuthKey	настройка подключения к Google Cloud Messaging
dbUrl	настройка соединения с СУБД
sbiOutboundWebServiceURL	адрес банковской WSDL, отвечающей за приём уведомления о доставке нотификаций
overrideSubscriptions	перегрузка подписок. При активации данного параметра при регистрации нового устройства, старые устройства данного бользователя будут отписываться от рассылки
caseInsensitiveIds	регистро-независимость внешних идентификаторов пользователей
deviceExpiredPeriodMillis	Удалять подключенные пользовательские подписки, на которые не было успешной доставки более N миллисекунд