Общее описание

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

Основной класс, используемый для работы с push-уведомлениями — это Aurora::PushNotifications::Client.

В начале работы приложения необходимо установить applicationId с помощью метода Aurora::PushNotifications::Client::setApplicationId().

Значение applicationId необходимо получить в технической поддержке предприятия-разработчика. Данный идентификатор можно вынести в конфигурацию приложения или программно запрашивать у сервера Сервиса уведомлений до начала процесса регистрации.

Каждому applicationId может соответствовать только одно приложение.

На основе applicationID push-демон выполняет поиск соответствующего ему registrationId, после чего при вызове метода registrate() эта пара отправляется на сервер, где производится проверка её актуальности. Если пара не актуальна (или если registrationId пустой в случае первой регистрации), то генерируется новый registrationId, который возвращается приложению через push-демон. Если же пара уже была актуальна, то возвращается существующий registrationId, поэтому registrationId является постоянным для связки приложения и устройства.

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

Каждое push-уведомление содержит поля для заголовка, тело сообщения и объект с данными, который представляет собой набор пар ключ-значение. Структура с описанием push-уведомления:

struct Push
{
    QString data; // строка, содержащая сериализованный JSON-объект
    QString title; // заголовок сообщения
    QString message; // тело сообщения
    QString action; // зарезервировано для будущего использования
    QString image; // зарезервировано для будущего использования
    QString sound; // зарезервировано для будущего использования
    quint32 categoryId = 0; // зарезервировано для будущего использования
};

Следует обратить внимание, что все поля, кроме data, предназначены для системы, и нет гарантии, что они будут передаваться в МП всегда.

data является сериализованным в строку JSON-объектом. Формат JSON-объекта в data может быть произвольным. Атрибут data, в частности, можно использовать для указания типа push-уведомления — text, command и т. д., например "{"type": "command", "text": "value"}".

Список этих структур Aurora::PushNotifications::PushList возвращается с сигналом Aurora::PushNotifications::Client::notifications. Каждое push-уведомление, полученное таким образом, в дальнейшем может быть выведено как уведомление.

API клиента Aurora::PushNotifications::Client для работы с push-демоном состоит из методов и сигналов.

Основные методы:

• void setApplicationId(const QString &applicationId) устанавливает объекту класса Client applicationId приложения, должен быть вызван непосредственно перед вызовом startHandler. Пример:

bool Application::start(const QStringList &arguments)
{
    auto applicationId = getApplicationId();
    m_client->setApplicationId(applicationId); // m_client — это объект класса `Aurora::PushNotifications::Client`
    if (!m_client->startHandler()) {
        qWarning() << "Failed to start push client, can not start handler";
        return false;
    }
    if (arguments.indexOf(QStringLiteral("--gui")) != -1) {
        startGui();
    }
    return true;
}

• QString applicationId() возвращает установленный в объекте класса Client applicationId. Пример:

qDebug() << "Current client applicationId:" << m_client->applicationId(); // m_client — это объект класса Aurora::PushNotifications::Client

• void registrate() отправляет запрос на сервер Сервиса уведомлений на регистрацию приложения (следует вызывать при каждом запуске приложения).
• bool isPushSystemReady() возвращает статус готовности push-демона:
  • true, если push-демон может обрабатывать запросы приложения;
  • false в противоположном случае;
• int error() позволяет получить код последней ошибки регистрации;
• QString errorMessage() позволяет получить текстовое описание последней ошибки регистрации.

Основные сигналы:

• void pushSystemReadinessChanged(bool status) передаётся при изменении состояния push-демона. Status имеет значение true, если устройство способно получать push-уведомления, false – в противоположном случае. Пример:

connect(m_client, &Aurora::PushNotifications::Client::pushSystemReadinessChanged, this, [](bool status){
    qDebug() << "Daemon сan receive push notifications: " << status;
});

• void registrationId(const QString &registrationId) передаётся при получении объектом класса Client registrationId, содержащего идентификатор приложения. Данный идентификатор должен быть отправлен на сервер Сервиса уведомлений для реализации возможности отправки push-уведомлений. Пример:

connect(m_client, &Aurora::PushNotifications::Client::registrationId, this, [this](const QString &registrationId){
    qDebug() << QString("Registration is successful for %1. RegistrationId: %2").arg(applicationId()).arg(registrationId);
    setRegistrationId(registrationId);
});

• void registrationError() передаётся в случае неудачной регистрации. Пример:

connect(m_client, &Aurora::PushNotifications::Client::registrationError, this, [this]() {
    qWarning() << "Registration error for " << applicationId();
});

• void notifications(const Aurora::PushNotifications::PushList &pushList) передаётся при получении объектом класса Client push-уведомлений. PushList содержит список сообщений. Пример:

connect(m_client, &Aurora::PushNotifications::Client::notifications, this, [this](const Aurora::PushNotifications::PushList &pushList){
    for (const Aurora::PushNotifications::Push &push : pushList) {
        qInfo() << "Push title" << push.title;
        qInfo() << "Push message" << push.message;
    }
});

• void clientInactive() передаётся в случае, если приложение не взаимодействовало с push-уведомлениями длительное время. Если приложение запущено в фоновом режиме, его рекомендуется выключить. Пример:

connect(m_client, &Aurora::PushNotifications::Client::clientInactive, this, [this](){
    if (!m_guiStarted) {
        qInfo() << "Handling inactivity in background mode";
        QGuiApplication::instance()->quit();
        return;
    }
    qInfo() << "Ignoring inactivity signal";
});