Introduction
This guide will walk you through the steps needed to implement push notifications in your application.
This how-to will teach you how to do the following:
- Import the
PushNotifications
module - Add the Push Notification widget and administrator pages
- Update several project files with the necessary dependencies
- Obtain FCM/APNs access/credentials and configuring them with your application
- Build the hybrid mobile package
2 Prerequisites
None.
3 Steps
3.1 Step 1 – Import the PushNotifications
Module from the Marketplace
The PushNotifications
module is published in the Mendix Marketplace. To import it into your project, click the Marketplace icon in the top right of Modeler. This will open the Marketplace in a new tab. Search for Push Notifications Connector and click the title of the result.
On the resulting page, click the green Download
button. Make sure that ‘Add as a new module’ is selected, and click OK.
3.2 Step 2 – Install Module Dependencies
The PushNotifications
module has two dependencies; the Encryption
module and the Community Commons Function Library
module. Include both dependencies by downloading them from the Marketplace, similar to how you installed the PushNotifications
module. While importing you may again get a dialog about overwriting project files, which you can confirm by clicking the OK
button.
If your project is using an older version of the Encryption module, it might trigger an error for referencing a non-existent layout. Fix it by assigning the master layout of the Encryption.ResponsiveLayout_Certificate
layout to another layout (in this specific use case it is not really important which layout is used). This does not apply to version 1.3.1 and higher.
After importing the module and the dependencies, your error dock will inform you that entity access is out of date; double-click the error, and then click Update security
at the top of the domain model pane to fix this error.
3.3 Step 3 – Include the Push Notifications Snippet in the Application’s Layouts
To properly register your device with a third party remote push service (FCM or APNs) and display in-app notifications, the widget should be put on the pages of your app. One way to accomplish this is by drag-and-dropping the snippet called PushNotification_Snippet (located in _USE ME folder in the PushNotifications module) into the layouts used by your app. Note that push notifications are currently not working on the desktop.
If your app is offline-compatible, please ensure that a sync button is available to the user, so that device registration requests will be synchronized with the server. Also, make sure your app has an offline device profile.
Please do not remove the buttons with the caption “GCM Settings reference” and “Device Registration reference” from the PushNotification_Snippet; they are necessary to make the widget offline-compatible. Note that both buttons are invisible to the user.
3.4 Step 4 – Start Connectors from Your “After Startup” Microflow
The PushNotifications module contains a microflow named AfterStartup_PushNotifications
which will start the connectors for FCM and APNs for you. Call this microflow from your AfterStartup microflow.
If your project already has a microflow set to execute after startup, we suggest to change your startup microflow to a new microflow, from where you call both after startup microflows. Reference the microflow below:
3.5 Step 5 – Set up the Administration Pages
Add the PushNotifications_Administration
page to the project navigation, so it can be reached after you deploy your app. This page contains three tabs: Pending Messages
, Devices
, and Configuration. The Pending Messages tab shows all the messages that are queued either because they were sent using the QueueMessage
action or because previous attempts to send them failed. The Devices tab contains a list of all devices registered with the application and is useful for testing purposes. The Configuration tab is used to configure your application to be able to reach the respective services (APNs and FCM) later on.
Do not add the administration pages to the navigation layout of offline devices; the administration pages are not offline compatible.
3.6 Step 6 – Set Up the Project Security for Your Module
Set the Project security
-> User roles
to include the PushNotifications.Administrator
role as part of the main Administrator
role and the PushNotifications.User
role as part of the main User
role. If your application allows anonymous users, then include the PushNotifications.Anonymous
role role as part of the main Anonymous
role.
3.7 Step 7 – Deploy Your App
At this point all implementation steps are done and you can deploy your application to the Mendix cloud. If you are using a Free App, simply click the Run
button.
You should make sure that the Encryption.EncryptionKey
constant has a value before you start the application. If the value is not set, you will get a NullPointerException when you try to send a notification to APNs.
If you are using a Free App, you should set a default value for the constant in the model. Otherwise, you can configure the constant value in the Mendix Cloud Portal.
3.8 Step 8 – Set Up Access to APNs and FCM
Set up access to APNs and FCM and configure them in your application. Note that starting with FCM is recommended because it is significantly less complicated than setting up APNs. You can return to this step later on to set up APNs.
See Setting up Apple Push Notification Server and Setting up Firebase Cloud Messaging Server for the details.
3.9 Step 9 – Build the Hybrid Mobile Application
You will need to build the hybrid mobile application. Refer to the Publishing a Mendix Hybrid Mobile App how-to to get the explanation on how to do this.
For more information about PhoneGap Build, you can refer to their documentation.
Note that a free PhoneGap Build account is limited to a single application, whereas paid plans support multiple applications. As a consequence, you may need to delete an existing app from your PhoneGap build environment in order to create a new one.