You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/specification/modules/push_overview.rst

81 lines
4.0 KiB
ReStructuredText

Push Notifications
==================
.. _module:push:
Overview
--------
::
+--------------------+ +-------------------+
Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor |
| | | |
+-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | |
| Matrix Home Server+-----> Push Gateway | +---> Push Provider | |
| | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | |
Matrix | | | | | |
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
Matrix supports push notifications as a first class citizen. Home Servers send
notifications of user events to user-configured HTTP endpoints. User may also
configure a number of rules that determine what events generate notifications.
These are all stored and managed by the users home server such that settings can
be reused between client apps as appropriate.
The above diagram shows the flow of push notifications being sent to a handset
where push notifications are submitted via the handset vendor, such as Apple's
APNS or Google's GCM. This happens as follows:
1. The client app signs in to a Matrix Home Server
2. The client app registers with its vendor's Push Notification provider and
obtains a routing token of some kind.
3. The mobile app, uses the Matrix client/server API to add a 'pusher',
providing the URL of a specific Push Gateway which is configured for that
application. It also provides the routing token it has acquired from the
Push Notification Provider.
4. The Home Server starts sending notification HTTP requests to the Push
Gateway using the supplied URL. The Push Gateway relays this notification to
the Push Notification Provider, passing the routing token along with any
necessary private credentials the provider requires to send push
notifications.
5. The Push Notification provider sends the notification to the device.
Nomenclature
------------
Pusher
A 'pusher' is an activity in the Home Server that manages the sending
of HTTP notifications for a single device of a single user.
Push Rules
A push rule is a single rule, configured by a matrix user, that gives
instructions to the Home Server about whether an event should be notified
about and how given a set of conditions. Matrix clients allow the user to
configure these. They create and view them via the Client to Server REST API.
Push Gateway
A push gateway is a server that receives HTTP event notifications from Home
Servers and passes them on to a different protocol such as APNS for iOS
devices or GCM for Android devices. Matrix.org provides a reference push
gateway, 'sygnal'. A client app tells a Home Server what push gateway
to send notifications to when it sets up a pusher.
For information on the client-server API for setting pushers and push rules, see
the Client Server API section. For more information on the format of HTTP
notifications, see the HTTP Notification Protocol section.