5. 提供者
提供者的可用性取决于部署的二进制文件,默认情况下 Tigase 包括以下提供程序:
5.1. Tigase 推送组件 - FCM 提供者
5.1.1. 概述
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. 配置
5.1.2.1. HTTP v1
5.1.2.1.1. 启用提供者
要启用此提供者,您需要在推送组件配置范围内启用 fcm-xmpp-api bean。
例子。
push () {
'fcm-http-v1' () {
# FCM configuration here
}
}
备注
If you configure this provider with a different identifier than fcm-http-v1, you need to specify class of the provider to be used as tigase.push.fcm.FcmHttpV1Provider, ie. 'fcm-provider' (class: tigase.push.fcm.FcmHttpV1Provider)
备注
您需要传递 FCM 配置参数才能使其工作,见下文。
5.1.2.1.2. 设置 FCM 凭据
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.
The file can be generated/obtained in the Firebase console and it should set all required permissions correctly. In order to do that open Firebase console (https://console.firebase.google.com/), select your project and navigate to Project settings (cog icon️) and then select Service account section. On the tab click "Generate new private key" and download resulting JSON file.
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.
例子。
push () {
'fcm-http-v1' () {
'serviceAccountPath' = '/home/tigase/tigase-server/etc/serviceaccount.json'
}
}
Alternatively it can be updated via Admin WebUI. In order to do that open Admin WebUI, expand Other section and in it select Set FCM service account item. In the form select desired FCM provider, paste contents of the JSON file and submit the form. If everything was correct you should see FCM service account updated message.
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.
push () {
'fcm-xmpp-api' () {
'sender-id' = 'your-sender-id'
'server-key' = 'your-server-key'
}
}
push () {
'fcm-xmpp-api' (class: tigase.push.fcm.FcmHttpV1Provider) {
'serviceAccountPath' = '/home/tigase/tigase-server/etc/serviceaccount.json'
}
}
重要
Keep fcm-xmpp-api in place and add class property!
5.2. Tigase 推送组件 - APNs 提供者
5.2.1. 概述
Tigase 推送组件 - APNs 提供者是 Tigase 推送组件的 APNs 提供者的实现。它允许 Tigase 推送组件连接到 Apple 推送通知服务并使用该服务发送通知。
5.2.2. 配置
5.2.2.1. 启用提供者
要启用此提供程序,您需要在推送组件配置范围内启用 apns-binary-api bean。
例子。
push () {
'apns-binary-api' () {
# APNs configuration here
}
}
备注
If you configure this provider with a different identifier than apns-binary-api, you need to specify class of the provider to be used as tigase.push.apns.APNsBinaryApiProvider, ie. 'apns-provider' (class: tigase.push.apns.APNsBinaryApiProvider)
备注
您需要传递 APNs 配置参数才能使其工作,见下文。
5.2.2.2. 设置 APNs 凭据
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.
5.2.2.2.1. 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.
备注
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.
5.2.2.2.2. 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.
当您拥有此证书时,您需要将证书文件的路径作为 cert-file 属性传递,将密码作为 cert-password 并将 APNS 主题(捆绑 ID)作为 apns-topic。
/etc/apns-cert.p12、Pa$$word 和 com.bundle.id 的示例。
push () {
'apns-binary-api' () {
'cert-file' = '/etc/apns-cert.p12'
'cert-password' = 'Pa$$w0rd'
'apns-topic' = 'com.bundle.id'
}
}
或者,证书可以存储在数据库中,在这种情况下,TDSL 配置文件应该只包含 'apns-topic'
条目,证书和密码应该通过 ad-hoc 命令更新(服务发现→推送组件→ 设置 APNS 证书)。在 ad-hoc 中,您应该从列表中选择 APNS 提供程序并包括从 Apple 获得的 base64 编码证书(.p12
文件),例如:
base64 -w 0 PushCertificate.p12
5.2.2.3. Whitelisting APNS server certificates
Hashes of root SSL certificates used by APNS servers are embedded in APNS provider of Tigase Push Component to ensure that it is possible to secure connect with APNS servers even if local server certificate trust store do not consider those certificates as secure.
It is possible to replace the list of hashes with an empty set (to relay on the system trust store) or to add exceptions for new certificates used by APNS service if required.
Example for clearing APNS SSL certificate exceptions.
push () {
'apns-binary-api' () {
'whitelisted-certificate-hashes' = []
}
}
Example for setting custom SHA-256 hashes (hex encoded) for APNS SSL certificate exceptions.
push () {
'apns-binary-api' () {
'whitelisted-certificate-hashes' = [
'HASH-abcd01234',
'HASH-abcd017A3',
]
}
}
5.2.2.4. Advanced options
Below are listed advanced options allowing for customization of push notifications payload.
5.2.2.4.1. with-account
This option when set to false
will disable sending account JID as part of push notification.
5.2.2.4.2. static-notification
This option when set to true
will replace notification content received with static data configured in TDLS configuration file.
5.2.2.4.3. static-notification-title
This option when static-notification
is set to true
will replace notification title received with value set with this option.
5.2.2.4.4. static-notification-subtitle
This option when static-notification
is set to true
will replace notification subtitle received with value set with this option.
5.2.2.4.5. static-notification-body
This option when static-notification
is set to true
will replace notification body received with value set with this option.
5.2.2.4.6. static-notification-badge
This option when static-notification
is set to true
will replace notification badge received with value set with this option.