Guide d'intégration de base du module Mendix

Ce guide explique comment ajouter le module Pushwoosh à une application mobile native Mendix existante, de son installation depuis le Marketplace à la réception d’une notification sur un appareil.

Prérequis

Pour intégrer le module Pushwoosh dans votre application, vous aurez besoin des éléments suivants :

Prérequis

• Un compte Pushwoosh.
• Un projet Pushwoosh configuré dans votre compte.
• Pour l’intégration iOS :
  • Une plateforme iOS configurée pour envoyer des notifications Push. Nous vous recommandons d’utiliser la configuration d’authentification basée sur un token (Token-Based Authentication) comme approche la plus simple.
  • Lors de la configuration, réglez la Gateway sur Sandbox pour envoyer des notifications Push à un simulateur.
• Pour l’intégration Android :
  • Une plateforme Android configurée
  • Le fichier google-services.json et le package name de votre projet Firebase.
  • Un projet Firebase connecté à votre application Android. Suivez le guide de configuration de Firebase si nécessaire.
• Votre Pushwoosh Application Code et votre token d’API de l’appareil (Pushwoosh Device API Token) depuis le Control Panel de Pushwoosh pour votre application.

Le jeton d’API de l’appareil (Device API Token) dans la liste ci-dessus n’est pas nécessaire pour ce module. Le widget ne prend que le code de l’application (Application Code) et rien d’autre.

Vous aurez également besoin des éléments suivants :

• Mendix Studio Pro 11.12.3 ou une version plus récente. Le package du module est construit avec cette version, et Studio Pro ne peut pas ouvrir un package produit par une version plus récente que la sienne.
• Un profil de navigation mobile natif dans votre application.
• Xcode ou Android Studio pour produire la version native. L’application Make It Native ne peut pas exécuter ce module, car elle ne contient pas de code natif tiers.

1. Installer le module depuis le Marketplace

Dans Studio Pro, cliquez sur l’icône du Marketplace en haut à droite, recherchez Pushwoosh, puis cliquez sur Télécharger. Studio Pro ajoute un module nommé Pushwoosh à votre application.

Il n’y a rien d’autre à installer. Les bibliothèques natives proviennent de npm lors de la compilation native, fixées à la version exacte avec laquelle le module a été testé.

2. Ajouter le widget Pushwoosh events à votre page d’accueil

Le widget Pushwoosh events démarre le SDK et transforme les notifications push en événements de nanoflow. Il n’affiche rien, donc placez-le une seule fois, sur la page qui se charge en premier dans le profil de navigation mobile natif.

1. Ouvrez la page d’accueil de votre profil de navigation mobile natif.
2. Faites glisser le widget Pushwoosh events sur la page. Il se trouve dans la catégorie Pushwoosh de la boîte à outils.
3. Définissez la propriété Application Code sur le code d’application de votre application depuis le panneau de contrôle de Pushwoosh. Il ressemble à XXXXX-XXXXX.

Laissez Register on load activé pour enregistrer l’appareil dès l’ouverture de l’application. Désactivez-le si vous préférez demander l’autorisation de notification plus tard, à un moment de l’application où la demande a plus de sens pour l’utilisateur. Voir Enregistrer l’appareil ci-dessous.

3. Configurer la compilation native

Pushwoosh remplace les notifications push intégrées d’une application Mendix plutôt que de fonctionner à côté d’elles. Dans le Native Mobile Builder, définissez les capacités comme suit :

• Push notifications : désactivé.
• Firebase Android : activé, afin que google-services.json soit toujours pris en compte.

Deux services de notification enregistrés pour l’événement com.google.firebase.MESSAGING_EVENT se masquent mutuellement, et les notifications cessent d’arriver. Sur Android, l’ID d’expéditeur FCM provient de google-services.json ; il n’est pas transmis au module.

Sur iOS, ajoutez la capacité Push Notifications au projet Xcode généré dans Signing & Capabilities, et téléchargez votre clé APNs dans le panneau de contrôle de Pushwoosh comme décrit dans le guide de configuration de la plateforme iOS.

Compilation sur macOS

Studio Pro pour Mac n’a pas de Native Mobile Builder. Configurez le modèle natif avec l’outil en ligne de commande @mendix/native-mobile-toolkit, puis compilez les projets iOS et Android générés localement avec Xcode et Gradle.

4. Enregistrer l’appareil

Un appareil ne reçoit des notifications qu’après avoir été enregistré auprès de Pushwoosh. Il y a deux façons de s’enregistrer, et vous en avez besoin d’une.

Enregistrement au chargement. Laissez la propriété Register on load du widget activée. L’appareil s’enregistre dès que le widget se charge, et sur iOS, la demande d’autorisation système apparaît à ce moment-là.

Enregistrement depuis un nanoflow. Désactivez Register on load et appelez l’action RegisterForPushNotifications depuis un de vos propres nanoflows, par exemple après que l’utilisateur se connecte ou accepte un écran de consentement. L’action renvoie le jeton push sous forme de chaîne de caractères.

Pour arrêter la livraison à un appareil, appelez UnregisterForPushNotifications.

5. Gérer une notification qui arrive lorsque l’application est ouverte

Lorsqu’une notification arrive alors que l’application est au premier plan, le widget écrit la notification dans les attributs que vous lui indiquez, puis déclenche le nanoflow dans On push received.

1. Définissez Message sur un attribut de type chaîne de caractères qui reçoit le texte de la notification.
2. Définissez Payload sur un attribut de type chaîne de caractères qui reçoit la charge utile complète au format JSON.
3. Définissez On push received sur un nanoflow qui y réagit, par exemple un qui affiche un message ou rafraîchit une liste.

Les attributs sont remplis avant l’exécution du nanoflow, de sorte que le nanoflow peut les lire immédiatement.

6. Gérer une notification ouverte et un lien profond

Lorsque l’utilisateur appuie sur une notification, le widget déclenche le nanoflow dans On push opened, avec les mêmes attributs Message et Payload remplis.

Si la notification contient un lien profond (deep link), le widget écrit également le lien dans l’attribut défini dans Deep link et déclenche le nanoflow dans On deep link. Ce nanoflow s’exécute en plus de On push opened, utilisez-le donc pour acheminer l’utilisateur vers la page vers laquelle le lien pointe.

7. Identifier l’utilisateur et définir des tags

Les tags sont ce qui transforme une diffusion de masse en un message ciblé. Appelez SetTags depuis n’importe quel nanoflow avec un objet JSON comme paramètre :

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

Guillemets dans les expressions Mendix

Une chaîne de caractères dans une expression Mendix est écrite entre apostrophes, de sorte que le JSON à l’intérieur conserve ses guillemets doubles non échappés. Écrire "" ou \" à l’intérieur de l’expression produit une chaîne que l’action ne peut pas analyser.

Appelez SetUserId avec votre propre identifiant utilisateur pour associer l’appareil à une personne plutôt qu’à un appareil. Tous les appareils enregistrés sous le même ID utilisateur peuvent alors être atteints avec un seul message.

8. Publier des événements

Les événements déclenchent des campagnes et des messages in-app. Appelez PostEvent avec le nom de l’événement et, éventuellement, un objet JSON d’attributs :

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

Le nom de l’événement doit correspondre à l’événement configuré dans le panneau de contrôle de Pushwoosh.

9. Envoyer une notification de test

Enregistrez l’appareil comme appareil de test et envoyez-lui un message depuis le panneau de contrôle de Pushwoosh. Consultez Tester votre intégration pour les étapes.

Une notification qui arrive lorsque l’application est ouverte est affichée par le système comme une alerte, et le nanoflow On push received s’exécute également. Pour supprimer l’alerte système et gérer la notification uniquement dans le nanoflow, appelez SetShowForegroundAlert avec false. Cette action ne fonctionne que sur iOS.

10. Vérifier l’intégration lorsque rien n’arrive

Passez en revue ces points dans l’ordre lorsque l’appareil ne reçoit aucune notification :

1. Confirmez que l’application est une application de développeur personnalisée ou une véritable compilation native. L’application Make It Native ne contient pas le module, donc chaque action Pushwoosh échoue silencieusement.
2. Confirmez les capacités de la compilation native : Push notifications désactivé, Firebase Android activé.
3. Confirmez que l’appareil est enregistré. Appelez GetPushToken et vérifiez qu’il renvoie un jeton plutôt qu’une chaîne vide.
4. Confirmez que la plateforme est configurée dans le panneau de contrôle de Pushwoosh, avec la clé APNs téléchargée pour iOS et la clé de serveur Firebase pour Android.

Si l’appareil n’est toujours pas joignable, appelez GetHwid et ouvrez un ticket de support avec cet identifiant.

Prochaines étapes

• Référence des actions du module - les propriétés du widget et les actions JavaScript, avec les paramètres et les valeurs de retour
• FAQ Mendix - les questions qui se posent lors de la première intégration