Push notifications (Mobile)

The Totara Mobile app uses Firebase Cloud Messaging (formerly known as Google Cloud Messaging) to deliver push notifications to registered devices. 

Firebase Cloud Messaging (FCM)

The diagram below shows how FCM works for push notifications. There are four steps.

1. Message building and targeting, in either the notification console GUI or a trusted environment such as Admin SDK.

2. The topic or instance is then sent to the FCM backend.

3. Next is platform-level message transport, where the notification goes through an Android transport layer, iOS/APNs or web push.

4. This is then pushed to SDK on the device. 

Open

Diagram of how Firebase Cloud Messaging works

Configuring Google Service for iOS

The Firebase Cloud Messaging APNs interface uses the Apple Push Notification service (APNs) to send messages up to 4KB in size to your iOS app, including when it is in the background.

To enable sending Push Notifications through APNs, you need:

• An Apple Push Notification Authentication Key for your Apple Developer account. Firebase Cloud Messaging uses this token to send Push Notifications to the application identified by the App ID.

• A provisioning profile for that App ID.

You create both in the Apple Developer Member Center.

More details can be found in the FCM docs for iOS: https://firebase.google.com/docs/cloud-messaging/ios/certs

Adding an iOS project (if it does not exist)

1. Go to the Firebase console.

2. In the centre of the project overview page, click the iOS icon to launch the setup workflow.

   Open

   

   Screenshot of project overview page.

3. If you've already added an app to your Firebase project, click Add app to display the platform options.

4. Enter your app's bundle ID in the iOS bundle ID field - make sure to enter the bundle ID that your app is actually using. The bundle ID value is case-sensitive, and it cannot be changed for this Firebase iOS app after it's registered with your Firebase project.

5. Optionally you can enter other app information; App nickname and App Store ID.

6. Click Register app.

Downloading and installing the google services plist file

1. Click Download GoogleService-Info.plist to obtain the Firebase iOS config file (GoogleService-Info.plist).

2. Replace the sample GoogleService-Info.plist in the iOS folder.

iOS Google service plist location

Configuring Google Service for Android

1. Go to the Firebase console.

2. In the centre of the project overview page, click the Android icon or Add app to launch the setup workflow.

3. Enter your app's package name in the Android package name field - make sure to enter the package name that your app is actually using. The package name value is case-sensitive, and it cannot be changed for this Firebase Android app after it's registered with your Firebase project.
   
   

4. Optionally you can enter other app information; App nickname and Debug signing certificate SHA-1.

5. Click Register app.

Downloading and installing the google services json file

1. Click Download google-services.json to obtain your Firebase Android config file (google-services.json).

2. Move your config file into the module (app-level) directory of your app.

Android Google service json location

Verifying configuration

Once you have done the configuration part, install and run the app on a device and you will see, in the debug logs, a massage that contains a statement "FCM TOKEN RECEIVED" (if authenticated successfully).

This means FCM recognises your app.

Testing a push notification 

If you have access to the FCM token, you can perform a simple test to make sure the communication between FCM and the device is correct.

1. Install and run the app on the target device.

2. Make sure the app is in the background on the device.

3. Open the FCM Notifications composer and select New notification.

4. Enter the message text.

5. Select Send test message.

6. In the field labelled Add an FCM registration token, enter the registration token you obtained in a previous section of this guide.

7. Click Test

If you receive your test notification, this means FCM is able to send to the device a push notification.

Alternatively, the same test can be done via Postman. You can use this example, just import it into the Postman tool. 

• Replace the value of the property "to" with the testing device token

• In the result panel, you will see if FMC was able to deliver the message to the device ("success": 1) or not

If you are trying to send a push notification via a Totara instance, make sure the steps configuring Totara AirNotifier is done and working as expected.

Troubleshooting

• In most cases, a missing configuration step is the root cause for not receiving a push notification message.

• Use a physical device to perform push notification tests. There is no guarantee for delivering messages on simulators/emulators.

• Avoid sending unnecessary push notifications. If you send too many, the Apple Push Notification service (APNs) will throttle your requests. 

• The user must be logged into the app to get a valid token.

• If you log out on the app, your token will be invalidated.

In the Totara instance:

• Make sure you are using the correct AirNotifier server configuration, it's probably push.totaralearning.com if you are not extending/customising the Totara Mobile App.  

On the device:

• Verify if notifications permission is allowed on the device:

  1. Go to Settings and find the Totara app.
     
     

     
     
     
     

  2. Verify if notifications are allowed.
     
     

     
     
     
     

  3. Make sure you have allowed the Totara app to send you notifications when you first installed it.
     
     

If you are extending/customising the Totara Mobile app

Verify if the Google service files are the correct ones and if they are at the correct place.

iOS
The configuration (plist) must be at ios/GoogleService-Info.plist. Application IDs defined in the info.plist (xcode project identity settings) and GoogleService-Info.plist must match.

Android

The configuration (json) must be at android/app/google-services.json. Application IDs defined in the app/build.gradle and google-services.json must match. 



Also, make sure you are using the correct flavour when generating a release build. Mismatching application IDs will lead to the push notification message not being delivered.

• If the configuration is done properly, you will be able to see the FCM token registering messages in the debug logs:
  
  

  • FCM TOKEN RECEIVED: This means the communication between FCM and the device is working properly, and FCM can find your device

  • REGISTERING FCM TOKEN: The token is being sent to the Totara instance backend to be linked to the current app user

  • TOKEN REGISTERED: The token has been linked to the current app user
    
    
    

• If you are still not able to see the FCM token in the console, you can try a few things:

  • Uninstall the app manually

  • Close the react console

  • Execute the running command to launch a new instance of the app

Known issues

Depending on the device the app is being tested on, you might face issues receiving push notification messages when the app is closed (killed, not in the background). Some manufacturers might kill the app service to save battery.

Devices that are known have issues receiving push notifications after the app is closed (killed):

• Lenovo Tab M8 with Android 10 (reported by a partner)

Testing push notification from Totara

Enable Totara Mobile on your site.

Set up AirNotifier as per the instructions here Push notifications (AirNotifier).

1. As site admin, go to Manage badges and create a new site-level badge.

2. Set the criteria to ‘Manual issue by role’

3. ‘Enable access’ to the new badge

4. Create a new user

5. As the user, open a fresh install of the Totara app and log into the site

6. You should see a request for permission to send push notifications on your device – if you don’t see that, is this a fresh install of the app? Is AirNotifier enabled on the site?

7. Once logged in, close the app by going to the home screen and locking your device

8. As admin, go to ‘Recipients’ tab on the badge, and award the badge to your mobile user

9. The push notification should arrive within a minute or two