Push notifications (AirNotifier)

Owned by Chris Snyder
Last updated: May 04, 2021 by Liam TannerVersion comment

The Totara Mobile app uses Google's Firebase Cloud Messaging (FCM) service to deliver push notifications to registered devices. FCM works with both Android and Apple devices. 

Because the developer's FCM credentials are set in the app at compile time, there is no way to dynamically set FCM credentials. In other words, once the app is compiled and uploaded to the App Store, only the original developer can send push notifications to instances of it. Therefore, individual Totara instances cannot send push notifications directly, but must rely on a forwarding service operated by the app developer, with the app developer's credentials.

In the case of the Totara Mobile app, we are providing a forwarding service using the open-source AirNotifier server, hosted at push.totaralearning.com. We have designed and built a companion message output plugin called Totara AirNotifier that will work with our service by default, or with any other out-of-the-box installation of AirNotifier. This will allow anyone building a custom mobile app to use their own FCM credentials with their own hosted forwarding service.

It would also be possible to build a message output plugin that communicates directly with FCM, and remove AirNotifier from the architecture.

There are two workflows: configuration of the Totara AirNotifier message output plugin, and sending push notifications via AirNotifier and FCM.

Configuration

The configuration path only applies to Totara instances which are using the default push.totaralearning.com server for the standard Totara Mobile app. If you are hosting your own AirNotifier server to send push notifications to a custom app, you will need to make your own arrangements for configuring Totara instances to use it, including getting your own AirNotifier App Code. Please note that if you are customising/publishing your own mobile app, you will need to set up your own AirNotifier service, with your own configuration.

The Totara AirNotifier message output plugin stores an App Name, which corresponds to an AirNotifier project, and an App Code, which corresponds to an AirNotifier access key. It also stores a Server URL, which is the base URL of the AirNotifier server.

Configuring the Totara AirNotifier settings.

The push.totaralearning.com AirNotifier server has a project called 'totara' which holds the Totara Mobile app FCM credentials. 

Within that project, there is an access key called 'Subscription Portal', which only has the ability to create new access keys.

When an admin clicks the Request an app code token from push.totaralearning.com link, the following happens:

  1. Totara instance confirms that it is registered, and that the Server URL and App Name are defaults, and that the App Code is blank, otherwise an error is returned.
  2. Totara instance makes a request to the subscription portal at https://subscriptions.totara.community/local/airnotifier/appcode.php.
  3. The Subscription Portal checks to see that it is correctly configured, otherwise an error is returned.
  4. The Subscription Portal uses its own access key to request the creation of a new access key in the 'totara' project, with permission to create device tokens, send push notifications, and delete device tokens.
  5. If AirNotifier approves the access key request and returns a new access key, the Subscription Portal returns that to the Totara Instance; otherwise an error is returned.
  6. If the Totara Instance receives an access key from the Subscription Portal, it is set as the AirNotifier App Code and a success message is shown to the admin.

Sending notifications

Whenever a new mobile device is registered via the Totara Mobile plugin, the app sends a totara_mobile_set_fcmtoken GraphQL mutation. If the Totara AirNotifier message output plugin is configured, it sends a request to AirNotifier server to register the device token. If the device is deregistered, and the message output plugin is configured, a request will be sent to AirNotifier to delete the device token.

Whenever a notification is routed to the Totara AirNotifier message output plugin, the following things happen:

  1. The message output plugin asks the Totara Mobile plugin for a list of device tokens registered to the recipient of the message.
  2. If any are found, the message output plugin sends a series of push notification requests to AirNotifier server, one for each device token.
  3. AirNotifier queues the push requests, then sends forwards them to FCM using the 'totara' project's credentials.
  4. For Android notifications, FCM delivers them directly.
  5. For iPhone notifications, FCM forwards them to Apple for delivery.
  6. When a user taps the notification, the Totara Mobile app is opened to the messages screen.

Changes we've made to AirNotifier

The Totara AirNotifier message output plugin is set up to work by default with the official AirNotifier 2.x or 3.x source code.

We have forked the code and made a few changes to make it easier to host AirNotifier as a Docker container, and to allow our Subscription Portal to create new access keys. 

The current source code for push.totaralearning.com can be found at https://github.com/totara/airnotifier/tree/3.0.1.