Guide d'intégration de base du SDK Cordova

Cette section contient des informations sur la manière d’intégrer le SDK Cordova de Pushwoosh dans votre application.

Prérequis

Pour intégrer le SDK Cordova de 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 recommandons d’utiliser la configuration d’authentification basée sur un token comme approche la plus simple.
  • Réglez la passerelle (Gateway) sur Sandbox pour envoyer des pushes à un simulateur.
• Pour l’intégration Android :
  • Une plateforme Android configurée
  • Le numéro de projet (également connu sous le nom de Sender ID), le fichier google-services.json et le nom du package de votre projet Firebase.
  • Un projet Firebase connecté à votre application Android. Suivez le guide de configuration de Firebase si nécessaire.
• Votre code d'application Pushwoosh et votre token d’API de l’appareil Pushwoosh (Pushwoosh Device API Token) depuis le panneau de contrôle Pushwoosh pour votre application.

Étapes d’intégration

1. Ajouter la dépendance du SDK Cordova de Pushwoosh

Ajoutez la dépendance du SDK Cordova de Pushwoosh à votre projet :

cordova plugin add pushwoosh-cordova-plugin

2. Initialisation du SDK Cordova

Dans le composant racine de votre fichier index.js, ajoutez le code suivant à l’intérieur du gestionnaire d’événements deviceready. Suivez les étapes dans l’ordre exact :

index.js

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. Register notification callbacks before initialization
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. Initialize Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

    // 3. Register the device to receive push notifications
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // Handle successful registration
        },
        function(status) {
            // Handle registration error
        }
    );
}, false);

Où :

• __YOUR_APP_ID__ est le code d’application du panneau de contrôle Pushwoosh.
• __YOUR_FCM_SENDER_ID__ est le numéro de projet Firebase de la console Firebase.

L'ordre d'initialisation est important

La séquence d’initialisation doit suivre l’ordre exact indiqué ci-dessus :

1. Enregistrez d’abord les écouteurs d’événements (push-receive, push-notification)
2. Ensuite, appelez onDeviceReady()
3. Puis, appelez registerDevice()

Changer cet ordre peut causer les problèmes suivants :

• Écouteurs d’événements enregistrés après onDeviceReady() : si l’application a été lancée en appuyant sur une notification push (démarrage à froid), onDeviceReady() livre immédiatement la charge utile (payload) de la notification de lancement à JavaScript. Si vos écouteurs ne sont pas encore enregistrés à ce moment-là, la notification de lancement est perdue sans aucun moyen de la récupérer.
• registerDevice() appelé avant onDeviceReady() : le SDK natif peut ne pas être correctement configuré avec votre ID d’application et votre Sender ID, ce qui peut entraîner l’échec silencieux de l’enregistrement de l’appareil ou le retour d’une erreur.
• Écouteurs d’événements enregistrés après registerDevice() : toute notification push qui arrive et est traitée avant que vos écouteurs ne soient en place sera envoyée comme un événement DOM et silencieusement ignorée car il n’y a pas de mécanisme de relecture dans le plugin.

Le plugin ne met pas en file d’attente ni ne met en mémoire tampon les événements manqués du côté JavaScript. Les événements DOM déclenchés par document.dispatchEvent() ne sont livrés qu’aux écouteurs qui sont déjà enregistrés au moment de l’envoi.

3. Configuration native iOS

3.1 Capacités

Pour activer les notifications push dans votre projet, vous devez ajouter certaines capacités.

Dans la section Signing & Capabilities, ajoutez les capacités suivantes :

• Push Notifications
• Background Modes. Après avoir ajouté cette capacité, cochez la case Remote notifications.

Si vous avez l’intention d’utiliser les notifications urgentes (Time Sensitive Notifications) (iOS 15+), ajoutez également la capacité Time Sensitive Notifications.

3.2 Info.plist

Dans votre Runner/Info.plist, définissez la clé __PUSHWOOSH_DEVICE_API_TOKEN__ sur le token d’API de l’appareil Pushwoosh (Pushwoosh Device API Token) :

info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

3.3 Suivi de la livraison des messages

Vous devez ajouter une cible d’extension de service de notification (Notification Service Extension) à votre projet. Ceci est essentiel pour un suivi précis de la livraison et pour des fonctionnalités comme le Rich Media sur iOS.

Suivez les étapes du guide natif pour ajouter la cible d’extension et le code Pushwoosh nécessaire à l’intérieur.

4. Configuration native Android

4.1 Installer les dépendances

Assurez-vous que les dépendances et plugins requis sont ajoutés à vos scripts Gradle :

Ajoutez le plugin Gradle des services Google aux dépendances de votre build.gradle au niveau du projet :

android/build.gradle

buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

Appliquez le plugin dans votre fichier build.gradle au niveau de l’application :

app/build.gradle

apply plugin: 'com.google.gms.google-services'

4.2 Ajouter le fichier de configuration Firebase

Placez le fichier google-services.json dans le dossier android/app de votre répertoire de projet.

4.3 Ajouter les métadonnées Pushwoosh

Dans votre main/AndroidManifest.xml, ajoutez le token d’API de l’appareil Pushwoosh (Pushwoosh Device API Token) à l’intérieur de la balise <application> :

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

Important : Assurez-vous de donner au token l’accès à la bonne application dans votre panneau de contrôle Pushwoosh. En savoir plus

5. Exécuter le projet

1. Compilez et exécutez le projet.
2. Allez dans le panneau de contrôle Pushwoosh et envoyez une notification push.
3. Vous devriez voir la notification dans l’application.

Intégration étendue

À ce stade, vous avez déjà intégré le SDK et pouvez envoyer et recevoir des notifications push. Explorons maintenant les fonctionnalités de base.

Écouteurs d’événements de notification push

Dans le SDK Pushwoosh, il y a deux écouteurs d’événements, conçus pour gérer les notifications push :

• L’événement push-receive est déclenché lorsqu’une notification push est reçue alors que l’application est au premier plan.
• L’événement push-notification est déclenché lorsqu’un utilisateur ouvre une notification.

Ces écouteurs d’événements doivent être enregistrés avant d’appeler onDeviceReady(), comme indiqué dans l’étape d’initialisation ci-dessus. Vous pouvez personnaliser la logique du gestionnaire pour répondre à vos besoins :

index.js

// Register before onDeviceReady()
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // Add your custom logic here
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // Add your custom logic here (e.g., navigate to a specific screen)
});

Configuration de l’utilisateur

En vous concentrant sur le comportement et les préférences de chaque utilisateur, vous pouvez fournir un contenu personnalisé, ce qui entraîne une satisfaction et une fidélité accrues des utilisateurs.

class Registration {
  afterUserLogin(user) {

    // Set user ID
    pushwoosh.setUserId(user.getId());

    // Setting additional user information as tags for Pushwoosh
    pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

Les tags sont des paires clé-valeur attribuées aux utilisateurs ou aux appareils, permettant une segmentation basée sur des attributs tels que les préférences ou le comportement, ce qui permet une messagerie ciblée.

class UpdateUser {
  afterUserUpdateProfile(user) {

    // Set list of favorite categories
    pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Set payment information
    pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Événements

Les événements sont des actions ou des occurrences spécifiques de l’utilisateur au sein de l’application qui peuvent être suivies pour analyser le comportement et déclencher des messages ou des actions correspondants.

class Registration {

  // Track login event
  afterUserLogin(user) {
    pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Track purchase event
  afterUserPurchase(product) {
    pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

Dépannage

Si vous rencontrez des problèmes lors du processus d’intégration, veuillez vous référer à la section support et communauté.