We've prepared a detailed tutorial for a proper push notifications setup on both client and server side.
Please make sure that clients provide all form fields required by the specified
Some publish errors may result in disabling push notifications for the specific device until it
attempts to enable them again.
This module is very easy to enable, just paste the following to your MongooseIM configuration file:
[modules.mod_event_pusher] backend.push.wpool.workers = 100
And that's basically it. You have just enabled the push notification support with 100 asynchronous workers that will handle all push notification related work.
- Syntax: string, one of
backend = "rdbms"
Backend to use for storing the registrations.
- Syntax: Array of TOML tables. See description.
wpool = [workers = 200]
List of options that will be passed to the
worker_pool library that handles all the requests.
Please refer to the Project Site for more details.
- Syntax: non-empty string
plugin_module = "mod_event_pusher_push_plugin_defaults"
The module implementing
mod_event_pusher_push_plugin behaviour, used for dynamic configuration of push notifications.
See the relevant section for more details.
- Syntax: array of strings
virtual_pubsub_hosts = ["host1", "host2"]
The list of "simulated" Publish-Subscribe domains. You may use the
@HOSTS@ pattern in the domain name.
It will automatically be replaced by a respective XMPP domain (e.g.
See the relevant section for more details.
Virtual PubSub hosts
If a notification is published to one of the configured domains, the internal push notification hook
is executed in MongooseIM instead of the XEP-0357 typical behaviour. If an existing PubSub domain
is added to this list, it will be shadowed in the push notifications context. To ensure complete
shadowing of all the PubSub subdomains we must use the
@HOSTS@ pattern, otherwise only the
subdomain of the user is shadowed. It enables easy migration from PubSub-full deployments to
Migration from XEP-0357 to virtual hosts
This is an example of how you can migrate the existing setup to the new model. PubSub service still
exists, just for the case of a user attempting to create a node. However, its domain is overridden
for the purpose of sending push notifications. Please note the value of
"pubsub.@HOSTS@" is the default domain for
[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 backend.push.virtual_pubsub_hosts = ["pubsub.@HOSTS@"]
- Versatility: PubSub-less and PubSub-full mechanisms can be configured with different domains and therefore give fine-grained control over the push notification handling
- Takes advantage of the PubSub-less efficiency when told to do so
- Fully compliant with XEP-0357: Push Notifications and therefore with most 3rd party client libraries
- Ideal for migrations to PubSub-less deployments.
- More complex configuration on the server side
- Pays the PubSub performance penalty when the PubSub path is taken
You can also control the format of the "sender" of the push notification (which ultimately becomes
the title of push notification) and filter which messages will trigger the notification.
In order to achieve that, you need to create a plugin module that implements the
mod_event_pusher_push_plugin behaviour and enable this plugin in the
plugin_module section as
A plugin module handles the dynamic configuration of push notifications. It contains the filtering and custom logic for notifying about messages.
Two plugin implementations are provided. They offer different behaviour considering unacknowledged messages when using XEP-0198: Stream Management:
mod_event_pusher_push_plugin_defaults, which implements an older behaviour. It does not notify the user of unacknowledged messages immediately after detecting a lost connection to the user.
mod_event_pusher_push_plugin_enhanced, which pushes notifications as soon as the server detects that the client has disconnected and waits for stream resumption (by an
unack_msg_eventevent generated by the
unacknowledged_messagehook). This immediate notification prevents the unneeded suspension of the client's application, if there are no unacknowledged messages yet. This allows to create more power efficient mobile applications.
In order for the enhanced plugin to work, each device (an entity that may receive push notifications) should be uniquely identified. The only correct way to identify a device from the XMPP standpoint is to use the data provided with the enable stanza. Because of that, each device should (re)enable the push notifications at the beginning of each and every connection.
A custom module implementing the optional callbacks of
may be used as a plugin to change the default behaviour. In the case of not implemented callbacks
the defaults are used instead.