1. Tigase Push Component

Tigase Push component is a Push notifications component implementing XEP-0357: Push Notifications. It is a gateway between Push Notification services and XMPP servers. It is configured by default to run under name of push.

Push notifications enable messages and pertinent information for clients, even if they are offline as long as they are registered with the push service. Tigase Messenger for iOS and Tigase Messenger for Android both have support for this feature.

1.1. Workflow

The workflow for enabling and using push notifications works as follows:

1.1.1. Enabling notifications

In order to receieve notifications, clients will require registration with a push service. Although this process is mainly invisible to the user, the steps in registration are listed here:

  • The client registers and bootstraps too it’s assicoated push service. This is done automatically.

  • The client registers itself with the push service server which then will dedicate a node for the device.

  • Node information is passed back to the client and is shared with necessary components.

1.1.2. Receiving notifications

Notifications sent from the server are recieved the following (simplified) way:

  • A message is published on the XMPP node which is then sent to the push service on the same server.

  • The push service will then inform the user agent (an application on the device running in the background) that a push notification has been sent.

  • The user agent will then publish the notification to the client for a user to see, waking up or turning on the client if is not running or suspended. = Configuration :author: Andrzej W√≥jcik :version: v2.0 October 2017. Reformatted for v8.0.0.

1.2. Enabling component

Push notifications may be sent by Tigase XMPP Server with or without use of Push component. Push Component is only required if you have your own application for mobile devices for which you want to send push notifications.

This component is not loaded and enabled by default as it requires implementations of Push notifications providers and additional configuration (including credentials required to authorize to push services). Following entries will activate component:

push () {
}
Note
You need to enable and configure push providers implementations before it will be possible to send push notifications. For more details about this process, please check documentations of push service provider projects.

1.3. Enabling push notifications for offline messages

Push notifications may be sent by Tigase XMPP Server with or without use of Push component. Push Component is only required if you have your own application for mobile devices for which you want to send push notifications.

If you are using existing application, then its maker have to provide you with push server (push component) which will send notification in format understandable by its application.

However, on Tigase XMPP Server side you need to enable processor which will generate notifications about offline messages sent to accounts on this server. To do so, you need to add following lines withing sess-man configuration block to enable urn:xmpp:push:0 processor:

'sess-man' () {
    'urn:xmpp:push:0' () {}
}

1.4. Enabling push notifications for messages received when all resources are AWAY/XA/DND

Push notifications may also be sent by Tigase XMPP Server when new message is received and all resources of recipient are in AWAY/XA/DND state. To enable this notifications you need to enable urn:xmpp:push:0:ext processor instead of default Push processor.

'sess-man' () {
    'urn:xmpp:push:0:ext' () {}
}
Warning
This is an extended version of default processor, so be sure not to enable both of them as you may received duplicated push notifications.

As this behaviour may not be expected by users and users need a compatible XMPP client to properly handle this notifications (XMPP client needs to retrieve message history to get actual message), even with this processor enable XMPP clients need to enable push notifications and in enable element need to have away attribute with value of true as in following example"

Enabling Push notifications for away/xa/dnd account
<iq type='set' id='x43'>
  <enable xmlns='urn:xmpp:push:0' away='true' jid='push-5.client.example' node='yxs32uqsflafdk3iuqo'>
    <x xmlns='jabber:x:data' type='submit'>
        ....
    </x>
  </enable>
</iq>

If later on, user decides to disable notification for account in away/xa/dnd state, it may disable push notifications or once again send stanza to enable push notification but without away attribute being set:

<iq type='set' id='x43'>
  <enable xmlns='urn:xmpp:push:0' away='true' jid='push-5.client.example' node='yxs32uqsflafdk3iuqo'>
    <x xmlns='jabber:x:data' type='submit'>
        ....
    </x>
  </enable>
</iq>

2. Usage

2.1. 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 will result in push notifications being delivered to the registered device.

2.2. 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.

2.3. 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.