Welcome to Tigase Push component guide

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.

Note
 Tigase Push component requires at the minimum version 8.0.0 of Tigase XMPP Server.

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.

2. Configuration

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

2.2. 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' () {}
}

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

3. Usage

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

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

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

4. Providers

Providers availability depends on the deployed binaries, by default Tigase includes following providers:

4.1. Tigase Push Component - FCM provider

4.2. Overview

Tigase Push Component - FCM provider is an implementation of FCM provider for Tigase Push Component. It allows Tigase Push Component to connect to Firebase Cloud Messaging and send notifications using this service.

4.3. Configuration

4.3.1. Enabling provider

To enable this provider, you need to enable fcm-xmpp-api bean within push component configuration scope.

Example
push () {
    'fcm-xmpp-api' () {
        # FCM configuration here
    }
}
Note
 You need to pass FCM configuration parameters to make it work, see below.

4.3.2. Setting FCM credentials

FCM XMPP API provider will not work properly without API key and project id as this values are required for authorization by FCM. You need to get information from FCM account.

When you have this data, you need to pass sender id as sender-id property and server key as server-key property.

Example
push () {
    'fcm-xmpp-api' () {
        'sender-id' = 'your-sender-id'
        'server-key' = 'your-server-key'
    }
}

4.3.3. Connection pool

By default this provider uses single client to server connection to FCM for sending notifications. If in your use case it is to small (as you need better performance), you should adjust value of pool-size configuration property. Setting it to 5 will open five connections to FCM for better performance.

Example
push () {
    'fcm-xmpp-api' () {
        'pool-size' = 5
    }
}

4.4. Tigase Push Component - APNs provider

4.5. Overview

Tigase Push Component - APNs provider is an implementation of APNs provider for Tigase Push Component. It allows Tigase Push Component to connect to Apple Push Notification service and send notifications using this service.

4.6. Configuration

4.6.1. Enabling provider

To enable this provider, you need to enable apns-binary-api bean within push component configuration scope.

Example
push () {
    'apns-binary-api' () {
        # APNs configuration here
    }
}
Note
 You need to pass APNs configuration parameters to make it work, see below.

4.6.2. Setting APNs credentials

APNs binary API provider will not work properly without certificate file required for authorization by APNs and password to decrypt this certificate file. You need to get certificate using Apple Developer Account.

When you have this certificate, you need to pass path to certificate file as cert-file property and password as cert-password

Example for /etc/apns-cert.p12 and Pa$$word
push () {
    'apns-binary-api' () {
        'cert-file' = '/etc/apns-cert.p12'
        'cert-password' = 'Pa$$w0rd'
    }
}

4.6.3. Connection pool

By default this provider uses many connection to APNs for sending notifications which equals to number of available CPU cores. If in your use case it is to small or too big number, you can adjust it by setting value of pool-size configuration property. Setting it to 5 will make sure to use only five connections to APNs.

Example
push () {
    'apns-binary-api' () {
        'pool-size' = 5
    }
}