How to set up Push Notifications
Push notifications are the bread and butter of the modern mobile experience, and MongooseIM has support for them. When used together with MongoosePush, you get out-of-the-box push notifications for FCM (Firebase Cloud Messaging) and APNS (Apple Push Notification Service) providers. And it's easy to extend it to any other protocols of your choice.
You might also want to read about the push notification's client side configuration.
XEP-0357: Push Notifications
Server side push notification support is fully compliant with XEP-0357: Push Notifications, which defines several components that need to work together in order to provide clients with working push notifications. However, there's just one non-optimal detail required by the aforementioned XEP: that push notifications being a PubSub service — we can do better than that.
As it is always said, one picture is worth a thousand words:
Who does what is highly configurable. You may use MongooseIM as the XMPP server clients connect to, and send the push XMPP stanzas to a different server that will take care of the push business; or you might use MongooseIM as the remote XMPP-PubSub server that does such business. Note that the XEP doesn't enforce the push IQ stanza format, so whichever setup is used, you need to take care of the producing and processing of these stanzas.
You might also use MongooseIM as both, or you might even do both things within a single MongooseIM node (the most common setup!). Or, for the best performance, you might just skip that PubSub node altogether. While the whole setup can be incredibly extensible, we see the following straightforward uses of it.
XEP-0357 compliant with local PubSub
This is, historically, the most common setup. It allows your clients to enable push notifications via a local PubSub, and the IQ stanza is routed internally.
[modules.mod_pubsub] plugins = ["push"] # mandatory minimal config [modules.mod_event_pusher] backend.push.backend = "mnesia" # optional backend.push.wpool.workers = 200 # optional backend.push.plugin_module = "mod_event_pusher_push_plugin_defaults" # optional
- Completely XEP-0357 compliant, and therefore compatible with any compliant 3rd party client library
- No need to have two different servers
- Less efficient (PubSub has a considerable impact on heavily loaded systems)
- More load within a single node
- Harder to customise
MongooseIM as a PubSub-less XMPP server
PubSub is completely bypassed and clients don't need to create a push node — if they attempt to do so, and PubSub is not configured, the server would respond with an error stanza. They only have to provide the virtual PubSub address in the enable stanza, and node name can be anything unique. In order to ensure uniqueness the APNS/FCM token can be used. Note that the token must be provided as a publish option anyway.
[modules.mod_event_pusher] backend.push.backend = "mnesia" # optional backend.push.wpool.workers = 200 # optional backend.push.plugin_module = "mod_event_pusher_push_plugin_defaults" # optional backend.push.virtual_pubsub_hosts = ["pubsub.@HOSTS@"]
- No need to use PubSub at all
- More efficient (PubSub has a considerable impact on heavily loaded systems)
- Simpler client-side usage — Read about the client side configuration here
- If the client application is built to create the push PubSub node, this might require a migration for such client — as he attempts to create the node, the server will answer with an IQ error stanza. If migrating the client side is a problem, there's a solution for that in the module section
Virtual PubSub hosts
These domains will shadow any identical domain configured for PubSub, stealing any notification published to it. It enables easy migration from PubSub-full deployments to PubSub-less variants. Read more in the relevant section.
Overview of all the involved MongooseIM components
The components that make push notifications possible in MongooseIM comprise the following architecture:
|PubSub-full setup||PubSub-less setup|
The first component that we need to configure in MongooseIM is the mod_event_pusher_push module.
According to the XEP-0357: Push Notifications, all notifications generated via the module we have just enabled (i.e. mod_event_pusher_push) have to be send to a push enabled publish-subscribe node. In order to allow clients to allocate such a node, we need to enable it in our mod_pubsub on the MongooseIM server that will communicate with the XMPP Push Service.