Skip to main content

Understanding Push Notifications

HiTo Kenneth,

best

Workingunderstand through thehow push process,notifications seeare setup in Matrix, a good place to start is with the diagram below from the Push Gateway API.

                                   +--------------------+  +-------------------+
                  Matrix HTTP      |                    |  |                   |
             Notification Protocol |   App Developer    |  |   Device Vendor   |
                                   |                    |  |                   |
           +-------------------+   | +----------------+ |  | +---------------+ |
           |                   |   | |                | |  | |               | |
           | Matrix homeserver +----->  Push Gateway  +------> Push Provider | |
           |                   |   | |                | |  | |               | |
           +-^-----------------+   | +----------------+ |  | +----+----------+ |
             |                     |                    |  |      |            |
    Matrix   |                     |                    |  |      |            |
 Client/Server API  +              |                    |  |      |            |
             |      |              +--------------------+  +-------------------+
             |   +--+-+                                           |
             |   |    <-------------------------------------------+
             +---+    |
                 |    |          Provider Push Protocol
                 +----+

         Mobile Device or Client

FromThe process starts when a high level, the user installs thea Matrix client, for example on an iOS device or Android device.device, and signs in. The client is configured with the push gateway location (URL) and also acquires a push key to identify itself from its push provider, Apple Push Notification (APN) service or Firebase Cloud Messaging (FCM). The client then registers a pusher on the users' homeserver providing the URL, push key etc.

So, onOn the Matrix Homeserver (for instance, Synapse), a pusher is registered for a user. The pusher information details:details1:

  • app_display_name: A string that will allow the user to identify what application owns this pusher.
  • app_id: This is a reverse-DNS style identifier for the application. Max length, 64 chars.
  • url: The URL to use to send notifications to the push gateway.
  • device_display_name: A string that will allow the user to identify what device owns this pusher.
  • pushkey: This is a unique identifier for this pusher. (Acquired from APN / FCM)

Relevant1 links:

more

See an example of a set pusher from the Client-Server APIs Push Notifications section:information

{
  "pushers": [
    {
      "app_display_name": "Appy McAppface",
      "app_id": "face.mcapp.appy.prod",
      "data": {
        "url": "https://example.com/_matrix/push/v1/notify"
      },
      "device_display_name": "Alice's Phone",
      "kind": "http",
      "lang": "en-US",
      "profile_tag": "xyz",
      "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A="
    }
  ]
}

When a notification is received the homeserver sends this information to the registered Push Gateway, i.e. Sygnal from the users' pushers. The push gateway is where you configure your App Types (apns / gcm). The push gateway, Sygnal in this instance, recieves the request and forwards it to the required notification service (APN or FCM) using the pushkey. If successful, the push gateway confirms the success to the homeserver.

You can find a very good overview of the entire process on ourSygnals' Sygnal, our push gateway's, Notes for Application Developers.

Hopefully the above clarifies, so regarding your specific questions, the answers would be:

  • What information the payload holds regarding the specific device?

    • Per the above payload example, a pusher contains a display name for the App (client), that app's reverse-DNS style identifier, a device name and finally the push key. The pushkey is the unique identifier of the pusher.

  • See an example of a set pusher from the Client-Server APIs Push Notifications section:

    {
  "pushers": [
    {
      "app_display_name": "Appy McAppface",
      "app_id": "face.mcapp.appy.prod",
      "data": {
        "url": "https://example.com/_matrix/push/v1/notify"
      },
      "device_display_name": "Alice's Phone",
      "kind": "http",
      "lang": "en-US",
      "profile_tag": "xyz",
      "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A="
    }
  ]
}

    How does e.g Apple APNS know that my device is suppose to get the push notice?

    • When the application on a user's device registers for push notifications, it acquires a pushkey from the push provider. So for iOS, the client will acquire this key from APN and use it when registering the pusher with synapse.

  • Does the payload hold any information about my device? E.g. IMEI etc?

      Per

    • Seethe abovesample payload provided above, only a device_display_name and answerpushkey toare theincluded, firstas questionsuch for breakdown. The payloadit does not contain a devices' IMEI
    etc.

Back to top