~ps-jenkins/ubuntu-push/ubuntu-vivid-proposed

Ubuntu Push Client High Level Developer Guide

=============================================

:Version: 0.50+

.. contents::

Introduction

------------

This document describes how to use the Ubuntu Push Client service from the point of view of a developer writing

a QML-based application.

---------

.. include:: _description.txt

The PushClient Component

------------------------

Example::

    import Ubuntu.PushNotifications 0.1

    PushClient {

        id: pushClient

        Component.onCompleted: {

            notificationsChanged.connect(messageList.handle_notifications)

            error.connect(messageList.handle_error)

        }

        appId: "com.ubuntu.developer.push.hello_hello"

    }

Registration: the appId and token properties

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To register with the push system and start receiving notifications, set the ``appId`` property to your application's APP_ID,

with or without version number. For this to succeed the user **must** have an Ubuntu One account configured in the device.

The APP_ID is as described in the `ApplicationId documentation <https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId>`__

except that the version is treated as optional. Therefore both ``com.ubuntu.music_music`` and ``com.ubuntu.music_music_1.3.496``

are valid. Keep in mind that while both versioned and unversioned APP_IDs are valid, they are still different and will affect

which notifications are delivered to the application. Unversioned IDs mean the token will be the same after updates and the application

will receive old notifications, while versioned IDs mean the app needs to explicitly ask to get older messages delivered.

Setting the same appId more than once has no effect.

After you are registered, if no error occurs, the PushClient will have a value set in its ``token`` property

which uniquely identifies the user+device combination.

Receiving Notifications

~~~~~~~~~~~~~~~~~~~~~~~

When a notification is received by the Push Client, it will be delivered to your application's push helper, and then

placed in your application's mailbox. At that point, the PushClient will emit the ``notificationsChanged(QStringList)`` signal

containing your messages. You should probably connect to that signal and handle those messages.

Because of the application's lifecycle, there is no guarantee that it will be running when the signal is emitted. For that

reason, apps should check for pending notifications whenever they are activated or started. To do that, use the

``getNotifications()`` slot. Triggering that slot will fetch notifications and trigger the

``notificationsChanged(QStringList)`` signal.

Error Handling

~~~~~~~~~~~~~~

Whenever PushClient suffers an error, it will emit the ``error(QString)`` signal with the error message.

Persistent Notification Management

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some notifications are persistent, meaning that, after they are presented, they don't disappear automatically.

This API allows the app to manage that type of notifications.

On each notification there's an optional ``tag`` field, used for this purpose.

The ``persistent`` property of PushClient contains the list of the tags of notifications with the "persist" element set

to true that are visible to the user right now.

The ``void clearPersistent(QStringList tags)`` method clears persistent notifications for that app marked by ``tags``.

If no tag is given, match all.

The ``count`` property sets the counter in the application's icon to the given value.

.. include:: _common.txt