Usage
=======

Sending notifications
----------------------

When you will register a device for a Push Notifications, you will receive name of the PubSub node where you should publish items. Publishing items to this node, as specified in `XEP-0357: Push Notifications <https://xmpp.org/extensions/xep-0357.html>`__ will result in push notifications being delivered to the registered device.

Registering device
-------------------

To register a device you need to execute the adhoc command ``register-device`` available at Push Notification component. This command will return a form which needs to be filled.

Form consists of following fields:

**provider**
   ID of a provider for which you want to register a device. It contains a list of available providers and you need to select a proper one.

**device-token**
   Unique token which your application retrieved from a device or client library and which should be used to identify device you want to register for push notifications.

When you submit this form, it will be processed and will respond with a ``result`` type form. Within this form you will find a ``node`` field which will contain a PubSub node name created by the Push Notifications component, to which you should publish notification items. This returned node with jid of the Push Notifications Component should be passed to your XMPP server as the address of the XMPP Push Service.

Unregistering device
---------------------

To unregister a device, you need to execute the adhoc command ``unregister-device`` available within the Push Notification component. This command will return a form which needs to be filled out.

This form consists of the following fields:

**provider**
   ID of a provider for which your devices was registered.

**device-token**
   Unique token which your application retrieved from a device or client library and was registered at this push notifications component.

When you submit this form, it will be processed and will respond with a ``result`` form to notify you that device was successfully unregistered from the push notifications component.

Unregistering device via HTTPS
----------------------------------

There is REST API handler (in form of ``UnregisterDeviceHandler.groovy`` script) which placed in ``/scripts/rest/push/`` directory in Tigase XMPP Server installation directory will enable endpoint (documented in Development Guide) allowing client to disable their push notifications even without authentication to their XMPP server.

.. note::

   It is recommended to not expose this endpoint using HTTP but only with HTTPS.