PayControl Inform — различия между версиями

Материал из PayControl Wiki
Перейти к: навигация, поиск
(Новая страница: «{{В работе}} '''PayControl Inform 2.0''' (сокр. PC Inform) является модулем для платформы PayControl, обеспечиваю…»)
 
(→‎Android)
 
(не показано 35 промежуточных версий 2 участников)
Строка 1: Строка 1:
−
{{В работе}}
 
 
'''PayControl Inform 2.0''' (сокр. PC Inform) является модулем для платформы PayControl, обеспечивающим высокопроизводительную доставку push-уведомлений до клиентских устройств с обеспечением безопасности передаваемых через уведомление данных.
 
'''PayControl Inform 2.0''' (сокр. PC Inform) является модулем для платформы PayControl, обеспечивающим высокопроизводительную доставку push-уведомлений до клиентских устройств с обеспечением безопасности передаваемых через уведомление данных.
−
=Описание взаимодействия с PC Inform=
+
 
−
==Отправка уведомления на iOS==
+
Конечному устройству информация может передаваться в двух вариантах:
 +
* Только push-уведомление;
 +
* Push-уведомление и полезная нагрузка (payload).
 +
=Установка=
 +
Руководство по установке приведено в статье [[PayControl Inform. Installation guide]].
 +
=Настройка=
 +
Параметры конфигурации PCInform распологаются в файле ''configuration/pushgate.conf''
 +
 
 +
{|class="wikitable"
 +
!Переменная
 +
!Пример
 +
!Описание
 +
|-
 +
|DB_DSN ||postgres://inform_user:techpassw@127.0.0.1/inform_db||Источник данных (строка подключения к БД)
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Push Secretary'''
 +
|-
 +
|PUSH_SECRETARY_WORKER_NUM||4||Количество процессов Push_secretary
 +
|-
 +
|PUSH_SECRETARY_LISTEN||0.0.0.0:80||Прослушиваемый порт
 +
|-
 +
|PUSH_SECRETARY_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Apple-pusher'''
 +
|-
 +
|APNS_AUTH_TYPE||key||Тип аутентификации:
 +
* с помощью ключа (значение <code>key</code>)
 +
* сертификата (значение <code>cert</code>)).
 +
Сертификат имеет ограниченный срок действия и требует периодической замены.
 +
|-
 +
|APNS_KEY||/var/app/configuration/apns/<KEY-FILENAME>.p8||Путь к файлу ключа. Если используется идентификация с помощью сертификата, необходимо заполнить значением <code>dummy</code>
 +
|-
 +
|APNS_KEY_ID||A3B5C7EDF8||Идентификатор ключа APNS. Если используется идентификация с помощью сертификата, необходимо заполнить значением <code>dummy</code>
 +
|-
 +
|APNS_TEAM_ID||P0R89S7TXZ||Идентификатор разработчика APNS. Если используется идентификация с помощью сертификата, необходимо заполнить значением <code>dummy</code>
 +
|-
 +
|APNS_TOPIC||org.paycontrol.app|| Идентификатор приложения. Если используется идентификация с помощью сертификата, необходимо заполнить значением <code>dummy</code>
 +
|-
 +
|APNS_CERT||/var/app/configuration/apns/<CERT-FILENAME>.pem || Файл сертификата для аутентификации на APNS для отправки push-уведомлений. Если используется идентификация с помощью ключа, необходимо заполнить значеним <code>dummy</code>
 +
|-
 +
|APPLE_PUSHER_USE_SANDBOX||0||Использование sandbox-шлюза для отправки пушей на dev приложения
 +
|-
 +
|APPLE_PUSHER_PREFETCH_COUNT||2500||Количество забираемых сообщений из очереди
 +
|-
 +
| APPLE_PUSHER_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Google-pusher'''
 +
|-
 +
|FCM_SENDER_ID||431994891053|| ID Отправителя Google firebase
 +
|-
 +
|FCM_API_KEY||AAAAZJTm6y0:APA91bF1OQYv9T2opZtI... ...0e8tLxCmBzhda||Ключ для аутентификации на Google Firebase для отправки push-уведомлений
 +
|-
 +
| GOOGLE_PUSHER_PREFETCH_COUNT||2500 ||Количество забираемых сообщений из очереди
 +
|-
 +
| GOOGLE_PUSHER_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Payloader'''
 +
|-
 +
|PAYLOADER_WORKER_NUM||3||Количество процессов payloader
 +
|-
 +
| PAYLOADER_LISTEN||0.0.0.0:8080||Прослушиваемый порт
 +
|-
 +
|PAYLOADER_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Housekeeper'''
 +
|-
 +
|AGING_PERIOD||3600||Cрок жизни записи push-уведомления перед очисткой БД housekeeper'ом
 +
|-
 +
|HOUSEKEEPING_DELAY||3600||Периодичность очистки БД
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Callbacker'''
 +
|-
 +
|CALLBACKER_PREFETCH_COUNT||2500||Количество забираемых сообщений из очереди
 +
|-
 +
|CALLBACKER_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|colspan="3" style="text-align: center;"|'''Status-porter'''
 +
|-
 +
|STATUS_PORTER_PREFETCH_COUNT||2500||Количество забираемых сообщений из очереди
 +
|-
 +
|STATUS_PORTER_LOG_LEVEL||INFO||Уровень логирования
 +
|-
 +
|}
 +
==Количество экземпляров сервиса==
 +
Конфигурирование количества запуска других служб доступно в статье, описывающей установку, раздел [[PayControl Inform. Installation guide#Enable services|Enable services]].
 +
==Аутентификация для отправки Push==
 +
===Google Firebase===
 +
Аутентификационные данные прописываются в ''configuration/pushgate.conf'', параметры
 +
* FCM_SENDER_ID;
 +
* FCM_API_KEY.
 +
===APNS===
 +
Аутентификация с помощью сертификата. Путь к сертификату прописывается в значении APNS_CERT в файле ''configuration/pushgate.conf''. Для аутентификации используется .pem-файл. Для конвертирования из .p12-файла используется команда:
 +
<syntaxhighlight lang="bash">openssl pkcs12 -in filename.p12 -out filename.pem -nodes</syntaxhighlight>
 +
==Адреса серверов для отправки Push==
 +
===Apple Push Notification Service===
 +
{| class="wikitable"
 +
!Адрес
 +
!Порт
 +
|-
 +
|api.push.apple.com||443
 +
|}
 +
===Google Firebase===
 +
{| class="wikitable"
 +
!Адрес
 +
!Порт
 +
|-
 +
|fcm-xmpp.googleapis.com||5235
 +
|}
 +
 
 +
=Описание интерфейса взаимодействия с PC Inform=
 +
Интерфейс общения с сервером представляет собой HTTP RESTful интерфейс.
 +
==Отправка уведомления==
 
===Запрос===
 
===Запрос===
−
Пример отправки запроса при помощи утилиты [[wikipedia:ru:curl]]
+
{{REST endpoint|http://<hostname>/api/notification/|POST}}
 +
Данные для отправки уведомления передаются в формате JSON и содержат следующие параметры:
 +
* device_token – идентификатор устройства для отправки уведомления;
 +
* device_type – тип устройства ("apple"/"google");
 +
* message – данные уведомления, которое отправляется на устройство через FCM/APNs;
 +
* payload – (опционально) дополнительная полезная нагрузка («пэйлоад»);
 +
* callback_url – (опционально) адрес, по которому будет осуществляться callback;
 +
* time_to_live – время жизни уведомления в секундах (0 - сервер FCM/APNs не будет пытаться отправить повторно);
 +
* priority – приоритет ("high" или "normal");
 +
* collapse_key – значение параметра FCM collapse_key/ APNs apns-collapse-id;
 +
 
 +
Примеры отправки запроса при помощи утилиты [[wikipedia:ru:curl|cURL]]:
 +
====Android и iOS через Firebase====
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
$ curl \
+
curl \
 
     -H "Content-Type: application/json" \
 
     -H "Content-Type: application/json" \
 
     -X POST \
 
     -X POST \
−
     -d '{"device_token": "XXXXXXXXXX", "device_type": "apple", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890", "message": {"aps": {"alert": "Hello from APNs", "badge": "1"}}}' \
+
     -d '{"device_token": "XXXXXXXXXX", "device_type": "google", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url" : "http://<callbackhost>/callback.php", "message": {"notification":{"title": "Hello from Firebase", "body": "This is notification"}}}' \
−
     http://127.0.0.1/api/notification/
+
     http://<hostname>/api/notification/
 
</syntaxhighlight>
 
</syntaxhighlight>
−
где:
+
 
−
* message - payload, который отправляется на устройство через APNs
+
====iOS====
−
* payload - дополнительный payload, который отправляется устройству по запросу к сервису `payloader`
 
−
* time_to_live - время жизни уведомления в секундах (0 - сервер APNs не будет пытаться отправить повторно)
 
−
* priority - приоритет ("high" или "normal")
 
−
* collapse_key - значение параметра apns-collapse-id, отправляемого в APNs
 
−
===Ответ===
 
−
В ответ сервис выдает UUID-идентификатор созданного запроса на уведомление в сообщении вида:
 
−
<syntaxhighlight lang="json">
 
−
{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}
 
−
</syntaxhighlight>
 
−
==Отправка уведомления на Android==
 
−
===Запрос===
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
$ curl \
+
curl \
−
    -H "Content-Type: application/json" \
+
-H "Content-Type: application/json" \
−
    -X POST \
+
-X POST \
−
    -d '{"device_token": "XXXXXXXXXX", "device_type": "google", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890", "message": {"title": "Hello from Firebase", "body": "This is notification"}}' \
+
-d '{"device_token": "XXXXXXXX", "device_type": "apple", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890","payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url" : "http://<callbackhost>/callback.php", "message": {"aps": {"alert": "Hello from APNs", "badge": "1"}}}' \
−
    http://127.0.0.1/api/notification/
+
http://<hostname>/api/notification/
 
</syntaxhighlight>
 
</syntaxhighlight>
−
где:
 
−
* message - payload, который отправляется на устройство через Firebase Cloud Messaging
 
−
* payload - дополнительный payload, который отправляется устройству по запросу к сервису `payloader`
 
−
* time_to_live - время жизни уведомления в секундах (0 - сервер FCM не будет пытаться отправить повторно)
 
−
* priority - приоритет ("high" или "normal")
 
−
* collapse_key - значение параметра collapse_key, отправляемого в FCM
 
 
===Ответ===
 
===Ответ===
 +
В ответ сервис возвратит идентификатор созданного запроса на уведомление в формате UUID вида:
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
 
{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}
 
{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}
 
</syntaxhighlight>
 
</syntaxhighlight>
−
==Информация о доставке Push-уведомления==
+
===Передача uuid на мобильное устройство===
 +
Идентификатор сообщения (в формате UUID) будет принудительно (с версии apple-pusher 1.0.014 и google-pusher 1.0.009) направляться в Push-уведомлении, в параметре '''pcinform_uuid'''. Примеры:
 +
====Android====
 +
<syntaxhighlight lang="json">{ 
 +
  "notification":{ 
 +
      "title":"PayContol",
 +
      "body":"Требуется подтверждение операции",
 +
      "sound":"default"
 +
  },
 +
  "data":{ 
 +
      "f1":1,
 +
      "f2":"s2",
 +
      "pcinform_uuid":"4df3823b-4767-44a9-87e9-d7e722ef5b1d"
 +
  }
 +
}</syntaxhighlight>
 +
====iOS====
 +
<syntaxhighlight lang="json">{ 
 +
  "aps":{ 
 +
      "alert":"Требуется подтверждение операций",
 +
      "badge":1,
 +
      "sound":"default"
 +
  },
 +
  "pcinform_uuid":"a2e35fa5-9131-48ca-b8d4-b6bd1c044f5b"
 +
}</syntaxhighlight>
 +
 
 +
==Информация о состоянии Push-уведомления==
 
===Запрос===
 
===Запрос===
−
По данному uuid можно впоследствии получить информацию по доставке уведомления запросом:
+
{{REST endpoint|http://<hostname>/api/notification/<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx>|GET}}
 +
<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx> - идентификатор созданного запроса на уведомление.
 +
 
 +
Пример отправки запроса при помощи утилиты cURL:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
$ curl http://127.0.0.1/api/notification/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
+
curl http://<hostname>/api/notification/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
 
</syntaxhighlight>
 
</syntaxhighlight>
 
===Ответ===
 
===Ответ===
 +
Возможные значения параметра "status":
 +
{|class="wikitable"
 +
!Значение
 +
!Значение передаваемое в составе коллбэка
 +
!Описание
 +
|-
 +
|NEW||0||Задача на отправку уведомления создана
 +
|-
 +
|NOTIFICATION_SENT||1||Уведомление отправлено
 +
|-
 +
|NOTIFICATION_SENDING_ERROR||2||Ошибка отправки уведомления
 +
|-
 +
|PAYLOAD_SENT||3||Полезная нагрузка отправлена
 +
|-
 +
|PAYLOAD_SENDING_ERROR||4||Ошибка передачи полезной нагрузки
 +
|-
 +
|CALLBACK_DONE||5||Коллбэк отправлен
 +
|-
 +
|CALLBACK_ERROR||6||Ошибка отправки коллбэка
 +
|}
 
Пример ответа:
 
Пример ответа:
−
<syntaxhighlight lang="json">{"uuid": "4e813216-2deb-4846-87d9-5f21f2754ac8", "device_token": "cyd7Pj2uY2k:APA91bG1MMxsOjyEgUThqkuf55zExXKSPq1DBNyLKLjW-h-Hte3Alb9fXaOrgjC1CqubEGEp-80JCAp_59Qsdad4Xaez7ht4oJe8PGvtJmQxTEs2SWaMZyctxVjI_v-us18d2v-WEaNu", "payload": null, "callback_url": null, "created_at": "2018-11-19 11:04:30.880346", "updated_at": "2018-11-19 11:04:31.460938", "status": "notification_sent"}</syntaxhighlight>
+
<syntaxhighlight lang="json">{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "device_token": "XXXXXXXXXX", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url": "http://<callbackhost>/callback.php", "created_at": "2018-11-19 14:53:51.780572", "updated_at": "2018-11-19 14:53:52.344391", "status": "notification_sent"}</syntaxhighlight>
−
==Получения пэйлоада==
+
 
−
# Опиание запроса на получения пэйлоада
+
==Получение полезной нагрузки==
 
===Запрос===
 
===Запрос===
 +
{{REST endpoint|http://<hostname>/api/payload/|POST}}
 +
Получение приложенных данных осуществляется мобильным устройством с помощью отправки HTTP POST запроса.
 +
 +
Пример отправки запроса при помощи утилиты cURL:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
$ curl -i \
+
curl -i \
−
    -H "Content-Type: application/json" \
+
  -H "Content-Type: application/json" \
−
    -X POST \
+
  -X POST \
−
    -d '{"auth_token": "XXXXXXXXXX", "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}' \
+
  -d '{"auth_token": "XXXXXXXXXX", "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}' \
−
    http://127.0.0.1:8080/api/payload/
+
  http://<hostname>/api/payload/
 
</syntaxhighlight>
 
</syntaxhighlight>
 
где:
 
где:
−
* auth_token - авторизационный токен, вычисляемый как *HMAC(sha256(`device_token`), `uuid`)*
+
* auth_token - авторизационный токен, вычисляемый как HMAC-SHA256(sha256(<device_token>), <uuid>)
−
* uuid - uuid запроса на уведомление
+
* uuid - идентификатор запроса на уведомление
 +
====Пример расчёта auth_token (Android)====
 +
[[Файл:PCInform HMAC calculation.png|мини|справа|PCInform HMAC calculation]]
 +
Например, для идентификатора транзакции:
 +
<pre>c03a6d7f-5b5c-49af-be5c-6ea380080cb7</pre>
 +
и идентификатора для уведомлений:
 +
<pre>fu37vBAcNxY:APA91bGMpZIh7zcksU2cjNVE8ZRhFyo6Xxac-K8Gp3ZOgVkZdanH5xHHpGkaFN1o2khW86pkU2nrC4EUmSaxRKpAYCA9v5h3YtMm-KaWbMUNHn3IWdzn3lFQRFWOtzD9GTl2qlQMezYS</pre>
 +
должно вычисляться следующее значение HMAC:
 +
<pre>4f84bc0f9fffc793aa6a2e6b010737c3a5294fd2853111bcef4728af486f8263</pre>
 +
Например, корректное значение можно сформировать на сайте https://www.freeformatter.com/hmac-generator.html
 +
====Пример расчёта auth_token (iOS)====
 +
[[Файл:PCInform HMAC calculation iOS.png|мини|справа|PCInform HMAC calculation iOS]]
 +
Например, для идентификатора транзакции:
 +
<pre>f811fd85-eddc-40fd-ac8d-1bd8f1186a78</pre>
 +
и идентификатора для уведомлений:
 +
<pre>3b14bfec592ddc722b1c9f005dcaedfebf03fcc8b92358eb7a0d8b4069f7129c</pre>для которого HEX-значение SHA-256 будет равным:
 +
<pre>65dfe2ca14542abad02b859b997858a2da8e85d25b7bb3c12dd93eb6c3a6a5d5</pre>
 +
должно вычисляться следующее значение HMAC:
 +
<pre>c3756d24960ce4e33b1a134e5be5a235a55671c4fb0f8a9b5cfb94b7d8726d50</pre>
 +
Например, корректное значение можно сформировать на сайте https://cryptii.com/pipes/hmac
 +
 
 
===Ответ===
 
===Ответ===
−
* Если токен невалидый, то сервис возвращает 401
+
* Если токен некорректный, то сервис возвращает 401
−
* Если токен, валидный, но пэйлоада нет, то сервис возвращает 204
+
* Если токен корректный, но полезной нагрузки нет, то сервис возвращает 204
−
* Если токен валидный и пэйлоад есть, то сервис возвращает его с кодом 200
+
* Если токен корректный и полезная нагрузка есть, то сервис возвращает его с кодом 200. Пример:<syntaxhighlight lang="json">{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA=="}</syntaxhighlight>
 +
 
 
==Callback==
 
==Callback==
−
Callbacker с использованием callback-адреса, указанного при создании задачи, выполняет HTTP-вызов в Прикладную систему для уведомления о статусе получения уведомления.
+
PC Inform с использованием callback-адреса, указанного при создании задачи, выполняет HTTP POST вызов в Прикладную систему для уведомления о статусе получения уведомления.
−
После callback-вызова Callbacker вносит информацию в БД о статусе задачи «callback выполнен».
+
 
−
Если в задаче не был указан callback-адрес, то callback не выполняется.
+
Обратный вызов прикладной системы выполняется при условии, что при создании транзакции указан адрес, на который будет отправляться callback.
 +
 
 +
Отправка callback'а происходит после запроса на получение полезной нагрузки.
 +
 
 +
Пример отправляемых в callback данных:
 +
<syntaxhighlight lang="json">
 +
{"task_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "status": 3}
 +
</syntaxhighlight>
 +
где:
 +
* task_uuid - идентификатор запроса на уведомление;
 +
* status - числовое значение статуса задачи. Возможные варианты описаны в разделе [[#Информация о состоянии Push-уведомления|Информация о состоянии Push-уведомления]].
 +
 
 +
=Переключение PayControl на использование PCInform=
 +
Для переключения PayControl на использование PCInform нужно:
 +
* Установить PCInform вместо PCIS Internal с помощью SQL-запроса к БД PCS:<syntaxhighlight lang="sql">
 +
update pc_system set pc_is_internal_url='[pc-inform]http://<PCINFORM_HOSTNAME/IP>/api/notification/';</syntaxhighlight>
 +
* Установить шаблоны пушей для всего сервера PayControl (таблица pc_sys_property). Пример SQL-запросов для PostgreSQL:<syntaxhighlight lang="sql">
 +
insert into pc_sys_property values (nextval('pc_setting_seq'), 'ANDROID_PUSH_PAYLOAD_TEMPLATE', '{"messages":[{"notification":{"tag":"%USER_ID%","title":"PayControl","body":"%PUSH_TEXT%","icon":"paycontrol_push","sound":"default"},"data":{"type":"PayControl_v2"}},{"data": {"type": "PayControl_v2", "userid": "%USER_ID%"}}]}');
 +
insert into pc_sys_property values (nextval('pc_setting_seq'), 'IOS_PUSH_PAYLOAD_TEMPLATE', '{"messages":[{"aps":{"alert":"%PUSH_TEXT%","sound":"%PUSH_SOUND%","badge":%PUSH_IOS_BADGE%},"type":"%PUSH_TYPE%","userid":"%USER_ID%"}]}');
 +
</syntaxhighlight>
 +
* Перезапустить PayControl.
 +
=Журналирование=
 +
Запись событий функционирования PCInform осуществляется в файл ''/var/log/messages''.
 +
 
 +
[[Категория:Документация]]
 +
[[Категория:Серверная часть]]
 +
[[Категория:PayControl Inform]]

Текущая версия на 12:42, 8 декабря 2020

PayControl Inform 2.0 (сокр. PC Inform) является модулем для платформы PayControl, обеспечивающим высокопроизводительную доставку push-уведомлений до клиентских устройств с обеспечением безопасности передаваемых через уведомление данных.

Конечному устройству информация может передаваться в двух вариантах:

  • Только push-уведомление;
  • Push-уведомление и полезная нагрузка (payload).

Установка

Руководство по установке приведено в статье PayControl Inform. Installation guide.

Настройка

Параметры конфигурации PCInform распологаются в файле configuration/pushgate.conf

Переменная Пример Описание
DB_DSN postgres://inform_user:techpassw@127.0.0.1/inform_db Источник данных (строка подключения к БД)
Push Secretary
PUSH_SECRETARY_WORKER_NUM 4 Количество процессов Push_secretary
PUSH_SECRETARY_LISTEN 0.0.0.0:80 Прослушиваемый порт
PUSH_SECRETARY_LOG_LEVEL INFO Уровень логирования
Apple-pusher
APNS_AUTH_TYPE key Тип аутентификации:
  • с помощью ключа (значение key)
  • сертификата (значение cert)).

Сертификат имеет ограниченный срок действия и требует периодической замены.

APNS_KEY /var/app/configuration/apns/<KEY-FILENAME>.p8 Путь к файлу ключа. Если используется идентификация с помощью сертификата, необходимо заполнить значением dummy
APNS_KEY_ID A3B5C7EDF8 Идентификатор ключа APNS. Если используется идентификация с помощью сертификата, необходимо заполнить значением dummy
APNS_TEAM_ID P0R89S7TXZ Идентификатор разработчика APNS. Если используется идентификация с помощью сертификата, необходимо заполнить значением dummy
APNS_TOPIC org.paycontrol.app Идентификатор приложения. Если используется идентификация с помощью сертификата, необходимо заполнить значением dummy
APNS_CERT /var/app/configuration/apns/<CERT-FILENAME>.pem Файл сертификата для аутентификации на APNS для отправки push-уведомлений. Если используется идентификация с помощью ключа, необходимо заполнить значеним dummy
APPLE_PUSHER_USE_SANDBOX 0 Использование sandbox-шлюза для отправки пушей на dev приложения
APPLE_PUSHER_PREFETCH_COUNT 2500 Количество забираемых сообщений из очереди
APPLE_PUSHER_LOG_LEVEL INFO Уровень логирования
Google-pusher
FCM_SENDER_ID 431994891053 ID Отправителя Google firebase
FCM_API_KEY AAAAZJTm6y0:APA91bF1OQYv9T2opZtI... ...0e8tLxCmBzhda Ключ для аутентификации на Google Firebase для отправки push-уведомлений
GOOGLE_PUSHER_PREFETCH_COUNT 2500 Количество забираемых сообщений из очереди
GOOGLE_PUSHER_LOG_LEVEL INFO Уровень логирования
Payloader
PAYLOADER_WORKER_NUM 3 Количество процессов payloader
PAYLOADER_LISTEN 0.0.0.0:8080 Прослушиваемый порт
PAYLOADER_LOG_LEVEL INFO Уровень логирования
Housekeeper
AGING_PERIOD 3600 Cрок жизни записи push-уведомления перед очисткой БД housekeeper'ом
HOUSEKEEPING_DELAY 3600 Периодичность очистки БД
Callbacker
CALLBACKER_PREFETCH_COUNT 2500 Количество забираемых сообщений из очереди
CALLBACKER_LOG_LEVEL INFO Уровень логирования
Status-porter
STATUS_PORTER_PREFETCH_COUNT 2500 Количество забираемых сообщений из очереди
STATUS_PORTER_LOG_LEVEL INFO Уровень логирования

Количество экземпляров сервиса

Конфигурирование количества запуска других служб доступно в статье, описывающей установку, раздел Enable services.

Аутентификация для отправки Push

Google Firebase

Аутентификационные данные прописываются в configuration/pushgate.conf, параметры

  • FCM_SENDER_ID;
  • FCM_API_KEY.

APNS

Аутентификация с помощью сертификата. Путь к сертификату прописывается в значении APNS_CERT в файле configuration/pushgate.conf. Для аутентификации используется .pem-файл. Для конвертирования из .p12-файла используется команда: 

openssl pkcs12 -in filename.p12 -out filename.pem -nodes

Адреса серверов для отправки Push

Apple Push Notification Service

Адрес Порт
api.push.apple.com 443

Google Firebase

Адрес Порт
fcm-xmpp.googleapis.com 5235

Описание интерфейса взаимодействия с PC Inform

Интерфейс общения с сервером представляет собой HTTP RESTful интерфейс.

Отправка уведомления

Запрос

Адрес конечной точки http://<hostname>/api/notification/
HTTP-метод POST

Данные для отправки уведомления передаются в формате JSON и содержат следующие параметры:

  • device_token – идентификатор устройства для отправки уведомления;
  • device_type – тип устройства ("apple"/"google");
  • message – данные уведомления, которое отправляется на устройство через FCM/APNs;
  • payload – (опционально) дополнительная полезная нагрузка («пэйлоад»);
  • callback_url – (опционально) адрес, по которому будет осуществляться callback;
  • time_to_live – время жизни уведомления в секундах (0 - сервер FCM/APNs не будет пытаться отправить повторно);
  • priority – приоритет ("high" или "normal");
  • collapse_key – значение параметра FCM collapse_key/ APNs apns-collapse-id;

Примеры отправки запроса при помощи утилиты cURL:

Android и iOS через Firebase

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"device_token": "XXXXXXXXXX", "device_type": "google", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url" : "http://<callbackhost>/callback.php", "message": {"notification":{"title": "Hello from Firebase", "body": "This is notification"}}}' \
    http://<hostname>/api/notification/

iOS

curl \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"device_token": "XXXXXXXX", "device_type": "apple", "time_to_live": 3, "priority": "high", "collapse_key": "1234567890","payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url" : "http://<callbackhost>/callback.php", "message": {"aps": {"alert": "Hello from APNs", "badge": "1"}}}' \
 http://<hostname>/api/notification/

Ответ

В ответ сервис возвратит идентификатор созданного запроса на уведомление в формате UUID вида: 

{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}

Передача uuid на мобильное устройство

Идентификатор сообщения (в формате UUID) будет принудительно (с версии apple-pusher 1.0.014 и google-pusher 1.0.009) направляться в Push-уведомлении, в параметре pcinform_uuid. Примеры:

Android

{  
   "notification":{  
      "title":"PayContol",
      "body":"Требуется подтверждение операции",
      "sound":"default"
   },
   "data":{  
      "f1":1,
      "f2":"s2",
      "pcinform_uuid":"4df3823b-4767-44a9-87e9-d7e722ef5b1d"
   }
}

iOS

{  
   "aps":{  
      "alert":"Требуется подтверждение операций",
      "badge":1,
      "sound":"default"
   },
   "pcinform_uuid":"a2e35fa5-9131-48ca-b8d4-b6bd1c044f5b"
}

Информация о состоянии Push-уведомления

Запрос

Адрес конечной точки http://<hostname>/api/notification/<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx>
HTTP-метод GET

<xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx> - идентификатор созданного запроса на уведомление.

Пример отправки запроса при помощи утилиты cURL: 

curl http://<hostname>/api/notification/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

Ответ

Возможные значения параметра "status":

Значение Значение передаваемое в составе коллбэка Описание
NEW 0 Задача на отправку уведомления создана
NOTIFICATION_SENT 1 Уведомление отправлено
NOTIFICATION_SENDING_ERROR 2 Ошибка отправки уведомления
PAYLOAD_SENT 3 Полезная нагрузка отправлена
PAYLOAD_SENDING_ERROR 4 Ошибка передачи полезной нагрузки
CALLBACK_DONE 5 Коллбэк отправлен
CALLBACK_ERROR 6 Ошибка отправки коллбэка

Пример ответа: 

{"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "device_token": "XXXXXXXXXX", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA==", "callback_url": "http://<callbackhost>/callback.php", "created_at": "2018-11-19 14:53:51.780572", "updated_at": "2018-11-19 14:53:52.344391", "status": "notification_sent"}

Получение полезной нагрузки

Запрос

Адрес конечной точки http://<hostname>/api/payload/
HTTP-метод POST

Получение приложенных данных осуществляется мобильным устройством с помощью отправки HTTP POST запроса.

Пример отправки запроса при помощи утилиты cURL: 

curl -i \
   -H "Content-Type: application/json" \
   -X POST \
   -d '{"auth_token": "XXXXXXXXXX", "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"}' \
   http://<hostname>/api/payload/

где:

  • auth_token - авторизационный токен, вычисляемый как HMAC-SHA256(sha256(<device_token>), <uuid>)
  • uuid - идентификатор запроса на уведомление

Пример расчёта auth_token (Android)

PCInform HMAC calculation

Например, для идентификатора транзакции: 

c03a6d7f-5b5c-49af-be5c-6ea380080cb7

и идентификатора для уведомлений: 

fu37vBAcNxY:APA91bGMpZIh7zcksU2cjNVE8ZRhFyo6Xxac-K8Gp3ZOgVkZdanH5xHHpGkaFN1o2khW86pkU2nrC4EUmSaxRKpAYCA9v5h3YtMm-KaWbMUNHn3IWdzn3lFQRFWOtzD9GTl2qlQMezYS

должно вычисляться следующее значение HMAC: 

4f84bc0f9fffc793aa6a2e6b010737c3a5294fd2853111bcef4728af486f8263

Например, корректное значение можно сформировать на сайте https://www.freeformatter.com/hmac-generator.html

Пример расчёта auth_token (iOS)

PCInform HMAC calculation iOS

Например, для идентификатора транзакции: 

f811fd85-eddc-40fd-ac8d-1bd8f1186a78

и идентификатора для уведомлений: 

3b14bfec592ddc722b1c9f005dcaedfebf03fcc8b92358eb7a0d8b4069f7129c

для которого HEX-значение SHA-256 будет равным: 

65dfe2ca14542abad02b859b997858a2da8e85d25b7bb3c12dd93eb6c3a6a5d5

должно вычисляться следующее значение HMAC: 

c3756d24960ce4e33b1a134e5be5a235a55671c4fb0f8a9b5cfb94b7d8726d50

Например, корректное значение можно сформировать на сайте https://cryptii.com/pipes/hmac

Ответ

  • Если токен некорректный, то сервис возвращает 401
  • Если токен корректный, но полезной нагрузки нет, то сервис возвращает 204
  • Если токен корректный и полезная нагрузка есть, то сервис возвращает его с кодом 200. Пример:
    {"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "payload": "dGVzdA0KdGVzdCBQYXlDb250cm9sIEluZm9ybQ0KUGF5Q29udHJvbCBJbmZvcm0gdGVzdA0KdGVzdA=="}

Callback

PC Inform с использованием callback-адреса, указанного при создании задачи, выполняет HTTP POST вызов в Прикладную систему для уведомления о статусе получения уведомления.

Обратный вызов прикладной системы выполняется при условии, что при создании транзакции указан адрес, на который будет отправляться callback.

Отправка callback'а происходит после запроса на получение полезной нагрузки.

Пример отправляемых в callback данных: 

{"task_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx", "status": 3}

где:

Переключение PayControl на использование PCInform

Для переключения PayControl на использование PCInform нужно:

  • Установить PCInform вместо PCIS Internal с помощью SQL-запроса к БД PCS:
    update pc_system set pc_is_internal_url='[pc-inform]http://<PCINFORM_HOSTNAME/IP>/api/notification/';
  • Установить шаблоны пушей для всего сервера PayControl (таблица pc_sys_property). Пример SQL-запросов для PostgreSQL:
    insert into pc_sys_property values (nextval('pc_setting_seq'), 'ANDROID_PUSH_PAYLOAD_TEMPLATE', '{"messages":[{"notification":{"tag":"%USER_ID%","title":"PayControl","body":"%PUSH_TEXT%","icon":"paycontrol_push","sound":"default"},"data":{"type":"PayControl_v2"}},{"data": {"type": "PayControl_v2", "userid": "%USER_ID%"}}]}');
insert into pc_sys_property values (nextval('pc_setting_seq'), 'IOS_PUSH_PAYLOAD_TEMPLATE', '{"messages":[{"aps":{"alert":"%PUSH_TEXT%","sound":"%PUSH_SOUND%","badge":%PUSH_IOS_BADGE%},"type":"%PUSH_TYPE%","userid":"%USER_ID%"}]}');
  • Перезапустить PayControl.

Журналирование

Запись событий функционирования PCInform осуществляется в файл /var/log/messages.

Источник — «https://repo.paycontrol.org/wiki/index.php?title=PayControl_Inform&oldid=462»