Push-сповіщення¶

Уявімо, що Ви створили програму з Clickable та опублікували її в OpenStore. Але тепер Вам потрібно надсилати користувачам Push-сповіщення. Перш за все потрібно зрозуміти як це працює:

Кожна програма, яка використовує пуш-сповіщення має унікальний токен. Він ідентифікує користувача, пристрій та саму програму. Цей токен створюється Push-сервісом UBports.
Для надсилання пуш-повідомлень потрібен токен, який надсилатиметься програмою на сервер її розробника.
З токеном можна надсилати до пуш-сервера UBports запит HTTP, який буде перенаправлений до користувацьких пристроїв як сповіщення.

Пройдемо це покроково.

Примітка

У наступному прикладі ми не зачіпатимемо сервер. Комунікація між Вашою програмою та Вашим сервером — також Ваша справа. Повідомте, будь ласка, користувача про обмін даними з Вашим сервером з наданням інформації про політику безпеки!

Підготуйте програму для отримання пуш-сповіщень¶

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

Перш за все потрібно додати групову політику «push-notification-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) — hookname, Ваш appId — це myapp.yourname_hookname. Тепер, коли програма запуститься, вона отримає токен та запише його у журналі. З журналами clickable ми зможемо скопіювати цей токен до термінала. Але програма все ще не готова отримувати пуш-повідомлення. Для цього потрібен так званий pushhelper!

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

Pushhelper є частиною програми, яка отримує усі пуш-сповіщення та обробляє їх перед надсиланням до системного центру сповіщень. Отримуватися буде json-файл, який передаватиметься далі у правильному json-форматі. Pushhelper відділений від програми. Отже, потрібен новий хук у маніфесті. Це може виглядати так:

    {
        //...

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

        //...
    }

Зрозуміло, що тепер потрібен інший файл apparmor та інший виконуваний файл. Файл push-apparmor.json повинен містити лише групову політику push-notification-client та виглядати приблизно так:

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

Файл push.json перенаправляє до виконуваного файлу:

{
    "exec": "pushexec"
}

У нашій настанові для створення виконуваного файлу pushexec, який перенаправлятиме сповіщення без будь-яких змін, ми використовуємо python:

#!/usr/bin/python3

import sys

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

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

Також потрібно додати цей новий файл до CMakeLists.txt та зробити pushexec виконуваним:

[…]

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})

[…]

Тепер програма готова приймати та обробляти пуш-сповіщення!

Використання API пуш-сервиса¶

Тепер у Вас є токен і програма вже готова отримувати та обробляти пуш-сповіщення. Для того щоби надіслати сповіщення потрібно створити запит 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.
token	Рядок	Обов’язково. Токен для ідентифікації пари користувач-пристрій, для якої повідомлення буде направлене згідно з описом у клієнтській документації.
clear_pending	Булевий (логічний)	Відкидає усі попередні повідомлення з черги. Зазвичай у відповідь на отриману помилку «too-many-pending». Типове значення false.
replace_tag	Рядок	Якщо в черзі присутні сповіщення з таким самим тегом, видалити їх перед додаванням до черги нового.
data	Дані	Об’єкт JSON. Вміст полів даних — довільний. Можна використовувати для передачі програмі будь-яких даних.

Дані¶

Параметр	Тип	Опис
notification	Сповіщення	Об’єкт JSON з визначенням представлення сповіщення.
message	Об’єкт	Об’єкт JSON, який передається у незмінному вигляді до програми через PopAll.

Сповіщення¶

Параметр	Тип	Опис
tag	Рядок	Тег пуш-сповіщення.
sound	Булевий чи рядок	Це або логічний тип (відтворювати визначений наперед звук) або це шлях до звукового файлу. Користувач може це вимкнути, тож не сподівайтеся тут на ексклюзивну дію. Типово значення порожнє (без звуку). Цей шлях відносний і може бути доступним у (a) каталозі програми `.local/share/<pkgname>` та у (b) стандартних каталогах xdg.
vibrate	Булевий чи Вібрація	Сповіщення може містити поле з вібрацією для тактильного ефекту, яке може бути або логічним (якщо true, буде вібрація з заданими параметрами) або об’єктом Вібрації.
emblem-counter	Емблема-лічильник	Об’єкт JSON, який визначає як буде показана емблема-лічильник.
card	Картка	Об’єкт JSON з інформацією щодо картки сповіщення.

Картка¶

Параметр	Тип	Опис
summary	Рядок	Обов’язково. Назва. Картка не буде представлена, якщо це поле порожнє.
body	Рядок	Довший текст, типово порожнє.
actions	Масив	Якщо порожньо (типово), бульбашкове сповіщення не інтерактивне. Якщо додати URL, то сповіщення буде активним і клацання по ньому відкриє посилання. Один з варіантів використання — це посилання вигляду `appid://com.ubuntu.developer.ralsina.hello`, яке перенаправить на іншу програму та запустить її.
icon	Рядок	Значок стосується події, що і сповіщення. Типово порожнє (без значка); додаткова піктограма — для програми і з’являтиметься так само, незалежно від цього поля.
timestamp	ціле (integer)	Секунди епохи unix. Використовується наразі тільки збереження. Якщо нуль чи порожнє, використовується поточна відмітка часу.
persist	Булевий (логічний)	Чи треба показувати у центрі сповіщень; типово false.
popup	Булевий (логічний)	Чи треба показувати бульбашку. Користувачі можуть відключити це, і можуть легко пропустити її, тому не покладайтеся на це. Типово встановлено у false.

Вибрація¶

Параметр	Тип	Опис
pattern	Масив	Список цілих чисел, які описують вібраційну схему (тривалості з чергуванням вібрації/спокою, у мілісекундах).
repeat	ціле (integer)	Кількість повторів шаблону вібрації (типово 1, 0 - це те саме, що і 1).

Емблема-лічильник¶

Параметр	Тип	Опис
count	ціле (integer)	Число, що відображається над значком програми на панелі запуску.
visible	Булевий (логічний)	Якщо true — показувати лічильник, false — для приховування.

Джерела¶

Перегляньте документацію Lomiri Push Service.