Mendix module basic integration guide

This guide walks through adding the Pushwoosh module to an existing Mendix native mobile app, from installing it out of the Marketplace to receiving a notification on a device.

Prerequisites

To integrate the Pushwoosh module into your app, you will need the following:

आवश्यकताएँ

• एक Pushwoosh खाता।
• आपके खाते में सेट अप किया गया एक Pushwoosh प्रोजेक्ट।
• iOS एकीकरण के लिए:
  • पुश नोटिफिकेशन भेजने के लिए कॉन्फ़िगर किया गया एक iOS प्लेटफ़ॉर्म। हम सबसे सरल तरीके के रूप में टोकन-आधारित प्रमाणीकरण कॉन्फ़िगरेशन का उपयोग करने की सलाह देते हैं।
  • सेटअप के दौरान, एक सिम्युलेटर पर पुश भेजने के लिए Gateway को Sandbox पर सेट करें।
• Android एकीकरण के लिए:
  • एक कॉन्फ़िगर किया गया Android प्लेटफ़ॉर्म
  • आपके Firebase प्रोजेक्ट से google-services.json फ़ाइल और package name।
  • आपके Android एप्लिकेशन से जुड़ा एक Firebase प्रोजेक्ट। यदि आवश्यक हो तो Firebase सेटअप गाइड का पालन करें।
• आपके एप्लिकेशन के लिए Pushwoosh कंट्रोल पैनल से आपका Pushwoosh Application Code और Pushwoosh Device API Token।

The Device API Token in the list above is not needed for this module. The widget takes the Application Code and nothing else.

You will also need the following:

• Mendix Studio Pro 11.12.3 or newer. The module package is built with that version, and Studio Pro cannot open a package produced by a newer version than itself.
• A native mobile navigation profile in your app.
• Xcode or Android Studio to produce the native build. The Make It Native app cannot run this module, because it does not contain third-party native code.

1. Install the module from the Marketplace

In Studio Pro, click the Marketplace icon in the top right corner, search for Pushwoosh, and click Download. Studio Pro adds a module named Pushwoosh to your app.

There is nothing else to install. The native libraries come from npm during the native build, pinned to the exact version the module was tested with.

2. Add the Pushwoosh events widget to your home page

The Pushwoosh events widget starts the SDK and turns push notifications into nanoflow events. It renders nothing, so place it once, on the page that loads first in the native mobile navigation profile.

1. Open the home page of your native mobile navigation profile.
2. Drag the Pushwoosh events widget onto the page. It is in the Pushwoosh category of the toolbox.
3. Set the Application Code property to the Application Code of your app from the Pushwoosh Control Panel. It looks like XXXXX-XXXXX.

Leave Register on load enabled to register the device as soon as the app opens. Turn it off if you would rather ask for notification permission later, at a point in the app where the request makes more sense to the user. See Register the device below.

3. Configure the native build

Pushwoosh replaces the built-in push notifications of a Mendix app rather than working next to them. In the Native Mobile Builder, set the capabilities as follows:

• Push notifications: off.
• Firebase Android: on, so that google-services.json is still picked up.

Two notification services registered for the com.google.firebase.MESSAGING_EVENT event shadow each other, and notifications stop arriving. On Android, the FCM Sender ID comes from google-services.json; it is not passed to the module.

On iOS, add the Push Notifications capability to the generated Xcode project in Signing & Capabilities, and upload your APNs key to the Pushwoosh Control Panel as described in the iOS platform configuration guide.

Building on macOS

Studio Pro for Mac has no Native Mobile Builder. Configure the native template with the @mendix/native-mobile-toolkit command line tool instead, then build the generated iOS and Android projects locally with Xcode and Gradle.

4. Register the device

A device receives notifications only after it is registered with Pushwoosh. There are two ways to register, and you need one of them.

Register on load. Leave the Register on load property of the widget enabled. The device registers as soon as the widget loads, and on iOS the system permission prompt appears at that moment.

Register from a nanoflow. Turn Register on load off and call the RegisterForPushNotifications action from a nanoflow of your own, for example after the user signs in or accepts a consent screen. The action returns the push token as a string.

To stop delivery to a device, call UnregisterForPushNotifications.

5. Handle a notification that arrives while the app is open

When a notification arrives while the app is in the foreground, the widget writes the notification into the attributes you point it at, and then triggers the nanoflow in On push received.

1. Set Message to a string attribute that receives the notification text.
2. Set Payload to a string attribute that receives the full payload as JSON.
3. Set On push received to a nanoflow that reacts to it, for example one that shows a message or refreshes a list.

The attributes are filled before the nanoflow runs, so the nanoflow can read them straight away.

6. Handle an opened notification and a deep link

When the user taps a notification, the widget triggers the nanoflow in On push opened, with the same Message and Payload attributes filled.

If the notification carries a deep link, the widget also writes the link into the attribute set in Deep link and triggers the nanoflow in On deep link. That nanoflow runs in addition to On push opened, so use it to route the user to the page the link points at.

7. Identify the user and set tags

Tags are what turn a broadcast into a targeted message. Call SetTags from any nanoflow with a JSON object as its parameter:

'{"Language":"en","Plan":"pro","Level":7}'

Quotes in Mendix expressions

A string in a Mendix expression is written in single quotes, so the JSON inside it keeps its double quotes unescaped. Writing "" or \" inside the expression produces a string the action cannot parse.

Call SetUserId with your own user identifier to associate the device with a person rather than with a device. All devices registered under the same user ID can then be reached with one message.

8. Post events

Events drive triggered campaigns and in-app messages. Call PostEvent with the event name and, optionally, a JSON object of attributes:

'{"product":"Coffee grinder","price":129}'

The event name must match the event configured in the Pushwoosh Control Panel.

9. Send a test notification

Register the device as a test device and send a message to it from the Pushwoosh Control Panel. See Test your integration for the steps.

A notification that arrives while the app is open is shown by the system as an alert, and the On push received nanoflow runs as well. To suppress the system alert and handle the notification only in the nanoflow, call SetShowForegroundAlert with false. That action works on iOS only.

10. Check the integration when nothing arrives

Work through these in order when the device receives no notifications:

1. Confirm the app is a custom developer app or a real native build. The Make It Native app does not contain the module, so every Pushwoosh action fails silently in it.
2. Confirm the capabilities of the native build: Push notifications off, Firebase Android on.
3. Confirm the device is registered. Call GetPushToken and check that it returns a token rather than an empty string.
4. Confirm the platform is configured in the Pushwoosh Control Panel, with the APNs key uploaded for iOS and the Firebase server key for Android.

If the device is still not reachable, call GetHwid and open a support ticket with that identifier.

Next steps

• Module actions reference - the widget properties and the JavaScript actions, with parameters and return values
• Mendix FAQ - the questions that come up during the first integration