Push-уведомления¶

Предположим, у Вас есть приложение, созданное с помощью Clickable и размещенное в OpenStore. Но теперь Вы хотите отправлять Push-уведомления своим пользователям. Прежде всего, нужно понять, как это работает:

Каждое приложение, которое использует push-уведомления, имеет уникальный токен. Этот токен идентифицирует пользователя, устройство и само приложение. Маркер генерируется службой UBports Push.
Для отправки push-уведомления потребуется токен. Таким образом, приложение отправляет свой токен на сервер разработчика приложения.
С помощью токена можно отправить HTTP-запрос на UBports Push Server, а он перенаправит уведомление на устройство пользователя.

Давайте попробуем повторить этот алгоритм шаг за шагом.

Примечание

В следующем примере мы не будем заниматься настройками сервера. Связь между приложением и сервером зависит от вас. Пожалуйста, сообщите пользователю о соединении с сервером и попросите у него согласие с политикой конфиденциальности!

Подготовьте приложение к работе с push-уведомлениями¶

Реализиция PushClient¶

Сначала нам нужно добавить группу политик «push-messages-client». Ваш файл для apparmor может выглядеть так:

    {
        "policy_groups": [
            "networking",
            "push-notification-client"
        ],
        "policy_version": 16.04
    }

Далее нам нужно внести изменения в Qml. Добавляем компонент pushclient:

//...

import Ubuntu.PushNotifications 0.1

//...

PushClient {
        id: pushClient
        appId: "myapp.yourname_hookname"
        onTokenChanged: console.log("👍", pushClient.token)
}

Необходимо указать правильный appId! Если имя приложения в файле манифеста - myapp.yourname, а имя основного обработчика (которое обрабатывает файл .desktop) - это имя_хука, тогда appId будет такой: myapp.yourname_hookname. Когда мы запустим приложение, оно получит токен и запишет его в лог-файл. Из лог-файлов для clickable можно скопировать этот токен в терминале. Но приложение еще не готово для получения push-уведомления. Для этого нам понадобится pushhelper!

Реализация pushhelper¶

Pushhelper - это часть приложения, которая будет получать все push-уведомления и обрабатывать их перед отправкой в центр системных уведомлений. Pushhelper получит json-файл и должен вывести другой json-файл в правильном формате. Pushhelper отделен от приложения. Итак, нам нужен новый hook в файле manifest. Это может выглядеть так:

    {
        //...

        "title": "myapp",
        "hooks": {
            "myapp": {
                "apparmor": "myapp.apparmor",
                "desktop":  "myapp.desktop"
            },
            "push": {
                "apparmor": "push-apparmor.json",
                "push-helper": "push.json"
            }
        },

        //...
    }

It should be clear that we now need a different apparmor file and a different executable file. The push-apparmor.json file must only contain the policy group push-notification-client and should look like this:

{
    "template": "ubuntu-push-helper",
    "policy_groups": [
        "push-notification-client"
    ],
    "policy_version": 16.04
}

The push.json is for redirecting to the executable file:

{
    "exec": "pushexec"
}

In our tutorial we will use python to create a executable named pushexec which will forward the notification without changing anything:

#!/usr/bin/python3

import sys

f1, f2 = sys.argv[1:3]

open(f2, "w").write(open(f1).read())

We also need to add this new files to the CMakeLists.txt and make the pushexec executable:

[…]

install(FILES pushexec PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ DESTINATION ${DATA_DIR})
install(FILES push.json DESTINATION ${DATA_DIR})
install(FILES push-apparmor.json DESTINATION ${DATA_DIR})

[…]

Теперь приложение готово для получения и обработки push-уведомлений!

Использование API сервиса Push¶

Теперь у нас есть токен, и приложение готово для получения и обработки push-уведомлений. Чтобы отправить уведомление, нужно отправить HTTP-запрос по этому адресу: https://push.ubports.com/notify. Тип содержимого должен быть application/json в соответствующем формате. Пример в javascript может выглядеть так:

var req = new XMLHttpRequest();
req.open("post", "https://push.ubports.com/notify", true);
req.setRequestHeader("Content-type", "application/json");
req.onreadystatechange = function() {
        if ( req.readyState === XMLHttpRequest.DONE ) {
                        console.log("✍ Answer:", req.responseText);
        }
}
var approxExpire = new Date ();
approxExpire.setUTCMinutes(approxExpire.getUTCMinutes()+10);
req.send(JSON.stringify({
        "appid" : "appname.yourname_hookname",
        "expire_on": approxExpire.toISOString(),
        "token": "aAnqwiFn§DF%2",
        "data": {
                "notification": {
                        "card": {
                                "icon": "notification",
                                "summary": "Push Notification",
                                "body": "Hello world",
                                "popup": true,
                                "persist": true
                        },
                "vibrate": true,
                "sound": true
                }
        }
}));

Объект Push Notification¶

Параметр	Тип	Описание
appid	строка	Обязательный параметр. ID приложения, которое получит уведомление, как это описано в документации для клиентской части.
expire_on	строка	Обязательный параметр. Срок (время и дата) истечения для этого сообщения, в формате ISO8601 Extendendformat.
token	строка	Обязательный параметр. Токен, идентифицирующий пользователя и устройство, которому предназначено сообщение как это описано в клиентской части документации.
clear_pending	bool	Отменяет все предыдущие ожидающие уведомления. Обычно в ответ на ошибку «too-many-pending». По умолчанию отключена.
replace_tag	строка	Если есть ожидающее уведомление с тем же тегом, удалите его в очереди появится это новое сообщение.
data	Данные	Объект JSON. Содержимое поля данных является произвольным. Мы можем использовать его для отправки любых данных в приложение.

Данные¶

Параметр	Тип	Описание
notification	Уведомление	Объект JSON, который определяет, как будет представлено это уведомление.
message	объект	Объект JSON, который передается приложению в состоянии «как есть» через PopAll.

Уведомление¶

Параметр	Тип	Описание
tag	строка	Тэг push-уведомления.
sound	логическая опция или путь к объекту	Эта опция или задается логически (воспроизведение предустановленной мелодии), или путь к звуковому файлу. Пользователь может выключить опцию, поэтому не доверяйте этой опции полностью. По умолчанию отключена (звука нет). Путь относительный, и будет задаваться (a) в разделе настроек приложения `.local/share/<pkgname>`, и (b) в стандартных директориях xdg.
vibrate	bool или Вибрация	В уведомлении может содержаться поле для вибрации, вызывающей тактильную обратную связь, опция может быть логической (если активирована, идет вибрация в заранее заданном режиме) или может быть выбран готовый объект.
еmblem-счетчика	Эмблема-счетчик	Объект JSON, который определяет, как отображать эмблему счетчика.
card	Карточка	Объект JSON с информацией о карточке уведомления.

Карточка¶

Параметр	Тип	Описание
summary	строка	Обязательно к заполнению. Карточка не будет видна, если это поле не заполнено.
body	строка	Более длинный текст, пустой по умолчанию.
actions	массив	Если пустое (по умолчанию), нажатие на bubble notification не даёт ничего. Если Вы добавите адрес URL, то bubble notifications становятся активными и позволяют открыть этот URL. Один из способов это использовать - a URL like `appid://com.ubuntu.developer.ralsina.hello` это позволит переключиться на приложение или запустит его.
icon	строка	Иконка относится к событию, к которому относится уведомление. По умолчанию, значение пустое (иконка отсутствует); дополнительная иконка относится к приложению будет также отображаться, независимо от настроек этого поля.
timestamp	integer - целое число	Секунды, прошедшие с начала эпохи Unix, пока используются только для сохранения. Если значение не задано или нулевое, то используется текущая временная отметка.
persist	bool	показывать ли в центре уведомлений; по умолчанию отключено.
popup	bool	Показывать ли в bubble notification. Пользователи могут отключить это, и могут легко отключить их, поэтому не нужно полагаться на эту опцию. Значения по умолчанию - опция отключена.

Вибрация¶

Параметр	Тип	Описание
pattern	массив	Список переменных, описывающих схемы вибрации (длительность периодов вибраций или её отсутствие - время в милисекундах).
repeat	integer - целое число	Сколько раз будет повторяться выбранняя модель (по умолчанию установлен 1 раз, 0 - тоже самое, что и 1).

Эмблема-счетчик¶

Параметр	Тип	Описание
count	integer - целое число	Число, отображаемое над значком приложения в панели запуска (launcher).
visible	bool	Установите значение true, чтобы показать счетчик, или false, чтобы скрыть его.

References¶

See the documentation of the Lomiri Push Service.