Skip to main content

Push Notifications

Hi Kenneth,

Working through the push process, see the diagram below from the Push Gateway API.

From a high-level, the user installs the client, for example on an iOS device or Android device. The client is configured with the push gateway location (URL) and also acquires a push key to identify itself from it's 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, on the Matrix Homeserver (Synapse), a pusher is registered for a user. The pusher information details:

  • 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)

Relevant links:

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="
    }
  ]
}

When a notification is recieved 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 our 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.

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

    • When the application on a users 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?

    • See above and answer to first question for breakdown. The payload does not contain IMEI
Back to top