5. Providers

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

5.1. Tigase Push Component - FCM provider

5.1.1. Overview

Tigase Push Component - FCM providers are implementations of FCM providers for Tigase Push Component. Any of them allows Tigase Push Component to connect to Firebase Cloud Messaging and send notifications using this service.

There are 2 providers for FCM:

fcm-http-v1 (new)
fcm-xmpp-api (deprecated)

fcm-http-v1 provider uses FCM HTTP v1 API for sending push notifications over FCM, while fcm-xmpp-api uses XMPP protocol for sending push notifications. Currently, support for XMPP protocol for sending push notifications over FCM was deprecated (by FCM) and will be removed.

5.1.2. Configuration

5.1.2.1. HTTP v1

5.1.2.1.1. Enabling provider

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

Example.

push () {
    'fcm-http-v1' () {
        # FCM configuration here
    }
}

Note

You need to pass FCM configuration parameters to make it work, see below.

5.1.2.1.2. Setting FCM credentials

FCM HTTP v1 provider will not work properly without service account JSON file. This file needs to be generated by Firebase console and issued for user/service account that has permissions to connect to FCM and send notifications. Currently that means it would be required to have Firebase messaging campaigns Admin or Cloud Messaging Admin role.

This service file contains all necessary keys and information required for authorization by FCM.

When you have this file, you need to save it in a folder accessible by Tigase XMPP Server and pass an absolute path to this file as serviceAccountPath property.

Example.

push () {
    'fcm-http-v1' () {
        'serviceAccountPath' = '/home/tigase/tigase-server/etc/serviceaccount.json'
    }
}

5.1.2.2. XMPP (deprecated)

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

5.1.2.2.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'
    }
}

5.1.2.2.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
    }
}

5.1.3. Migration

As XMPP protocol for sending push notifications with Firebase Cloud Messaging was deprecated it will be required to migrate to HTTP v1 API. To achieve that, you need to migrate from fcm-xmpp-api provider to fcm-http-v1 provider.

The easiest way to do that, should be by updating Tigase XMPP Server to version having support for fcm-http-v1 provider and then adjusting its configuration.

To do that, you would need to specify (or replace) a class for exising provider named fcm-xmpp-api with class of fcm-http-v1 provider (tigase.push.fcm.FcmHttpV1Provider) and replace its confguration with configuration required by fcm-http-v1 provider.

Before migration

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

After migration

 push () {
    'fcm-xmpp-api' (class: tigase.push.fcm.FcmHttpV1Provider) {
        'serviceAccountPath' = '/home/tigase/tigase-server/etc/serviceaccount.json'
    }
}

Important

Keep fcm-xmpp-api in place and add class property!

5.2. Tigase Push Component - APNs provider

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

5.2.2. Configuration

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.

APNs binary API provider will not work properly without credentials allowing it to connect and authenticate to APNs.

This can be done either by providing certificate files (including certificate files for accessing PushKit, if VoIP notifications need to be available) or by providing P8 encryption key.

Usage of P8 private encryption key is preferred way of authentication as a single key allows you to send push notifications (including PushKit notifications) and this private key doesn’t expire, so you do not need to renew it.

6. P8 encryption key

The P8 private encryption key required for authorization by APNs you need to obtain using Apple Developer Account. You also need to know your team ID and downloaded key ID.

Note

Apple provides you with only a single private key. This key can be downloaded only once and needs to be shared between installations sending push notifications. (Actually, you can have 2 encryption keys, but according to the documention, second key should be created only for updating all instances to use new key without stopping not updated instances from sending push notifications due to expired/cancelled key).

When you have that, you need to pass encryption key file as key-file, encryption key ID as key-id, team ID as team-id and APNS topic (bundle id) as apns-topic.

Example for /etc/apns-private-key.p8, XMXXXXU5XC, XXXXW6EXXX and com.bundle.id.

push () {
    'apns-binary-api' () {
        'key-file' = '/etc/apns-private-key.p8'
        'key-id' = 'XMXXXXU5XC'
        'team-id' = 'XXXXW6EXXX'
        'apns-topic' = 'com.bundle.id'
    }
}

Alternatively, P8 private key can be stored in the database and in that case the TDSL configuration file should only contain 'apns-topic' entry and the private key, the key id and team id should be updated via ad-hoc command (Service discovery → Push component → Set APNS encryption key). In the ad-hoc you should select the APNS provider from the list and include private key (P8 form/content of P8 file) obtained from Apple.

7. Certificate files

The certificate file required for authorization by APNs and password to decrypt this certificate file you need to obating using Apple Developer Account.

When you have this certificate, you need to pass path to certificate file as cert-file property, password as cert-password and APNS topic (bundle id) as apns-topic.

Example for /etc/apns-cert.p12, Pa$$word and com.bundle.id.

push () {
    'apns-binary-api' () {
        'cert-file' = '/etc/apns-cert.p12'
        'cert-password' = 'Pa$$w0rd'
        'apns-topic' = 'com.bundle.id'
    }
}

Alternatively, certificate can be stored in the database and in that case the TDSL configuration file should only contain 'apns-topic' entry and the certificate and the password should be updated via ad-hoc command (Service discovery → Push component → Set APNS certificate). In the ad-hoc you should select the APNS provider from the list and include base64 encoded certificate obtained from Apple (.p12 file), for example:

base64 -w 0 PushCertificate.p12