Guide d'intégration de base du SDK Capacitor

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

Prérequis

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

Exigences

• 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 par token comme approche la plus simple.
  • Réglez la passerelle sur Sandbox pour envoyer des notifications push à un simulateur.
  • Pour ajouter le plugin avec Swift Package Manager : Capacitor 7 ou 8. Pour migrer un projet CocoaPods vers Swift Package Manager : @capacitor/cli 7.4.0 ou ultérieur.
• 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 Pushwoosh Device API Token depuis le Control Panel de Pushwoosh pour votre application.

Étapes d’intégration

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

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

npm install pushwoosh-capacitor-plugin

Synchronisez la configuration de Capacitor :

npx cap sync

1.1 Choisir le gestionnaire de paquets iOS

npx cap sync installe la partie iOS du plugin avec le gestionnaire de paquets utilisé par votre projet Capacitor : Swift Package Manager ou CocoaPods. Les deux fournissent la même version du SDK natif Pushwoosh et d’Inbox UI. Swift Package Manager est pris en charge avec Capacitor 7 et Capacitor 8.

Un projet existant conserve son gestionnaire de paquets : si ios/App/CapApp-SPM existe, la CLI Capacitor utilise Swift Package Manager, sinon CocoaPods. Pour une nouvelle plateforme iOS :

Capacitor 8

Capacitor 8 crée par défaut un projet Swift Package Manager :

npx cap add ios

Pour utiliser CocoaPods à la place, exécutez npx cap add ios --packagemanager CocoaPods.

Capacitor 7

Capacitor 7 crée par défaut un projet CocoaPods. Pour utiliser Swift Package Manager, exécutez :

npx cap add ios --packagemanager SPM

La commande crée le projet, puis s’arrête avec une erreur ENOENT ... Podfile en essayant d’exécuter pod install. Le projet est créé correctement. Terminez la configuration avec :

npx cap sync ios

Avec Swift Package Manager, la CLI Capacitor ajoute le plugin à ios/App/CapApp-SPM, et le plugin apporte le SDK iOS Pushwoosh et Inbox UI. N’ajoutez pas le SDK Pushwoosh une seconde fois à l’application, ni en tant que pod ni en tant que paquet d’une autre version.

Abandon de CocoaPods

CocoaPods trunk passe en lecture seule le 2 décembre 2026, et Pushwoosh migre le SDK iOS vers Swift Package Manager. Les versions du plugin publiées après cette date utiliseront uniquement le paquet Swift. D’ici là, pod install et le build Xcode d’un projet CocoaPods affichent un avertissement à ce sujet. L’avertissement n’affecte pas le build.

Pour migrer un projet CocoaPods existant, exécutez npx cap spm-migration-assistant, puis suivez l’étape manuelle dans Xcode vers laquelle il renvoie. La commande nécessite @capacitor/cli 7.4.0 ou ultérieur.

2. Initialisation du SDK Capacitor

Dans votre fichier JavaScript principal, importez et initialisez le SDK Pushwoosh :

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Initialize the SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Register for push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Handle successful registration
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Handle registration error
    });

Où :

• __YOUR_APP_CODE__ est le code d’application du Control Panel de Pushwoosh.

3. Configuration native pour 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 ios/App/App/Info.plist, définissez la clé __PUSHWOOSH_DEVICE_API_TOKEN__ sur le 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 Notification Service Extension à votre projet. C’est essentiel pour un suivi précis de la livraison et pour des fonctionnalités comme les 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. Ajoutez le SDK Pushwoosh à la cible de l’extension selon votre gestionnaire de paquets :

• CocoaPods : suivez l’étape Dépendances pour l’extension de service de notification (CocoaPods uniquement) du guide natif. Dans ios/App/Podfile, ajoutez pod 'PushwooshXCFramework' sans version à la cible de l’extension, afin qu’il se résolve vers la version utilisée par le plugin, puis exécutez npx cap sync ios.

• Swift Package Manager : ignorez l’étape des dépendances CocoaPods du guide natif. Ajoutez vous-même le SDK à la cible de l’extension dans Xcode, car la cible n’hérite pas des dépendances du plugin :

  1. Ouvrez la cible de l’extension > General > Frameworks and Libraries.
  2. Ajoutez le produit PushwooshFramework du paquet Pushwoosh-XCFramework. Utilisez la version déjà présente dans Package.resolved.

  Si vous avez migré depuis CocoaPods, assurez-vous que l’extension ne reçoit plus PushwooshXCFramework en tant que pod, afin que l’application n’inclue pas le SDK deux fois.

Ensuite, ajoutez import PushwooshFramework dans le code de l’extension. La cible App n’a besoin de rien de plus, car elle obtient le SDK Pushwoosh via le plugin.

4. Configuration native pour Android

4.1 Installer les dépendances

Assurez-vous que les dépendances et les 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 projet.

4.3 Ajouter les métadonnées Pushwoosh

Dans votre main/AndroidManifest.xml, ajoutez le 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 Control Panel Pushwoosh. En savoir plus

5. Exécuter le projet

1. Compilez et exécutez le projet.
2. Allez dans le Control Panel de 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 Capacitor de Pushwoosh, il existe deux méthodes de rappel pour gérer les notifications push :

• pushReceivedCallback est déclenché lorsqu’une notification push est reçue
• pushOpenedCallback est déclenché lorsqu’un utilisateur ouvre une notification

Vous devez configurer ces rappels juste après l’initialisation du SDK :

index.js

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

// Set up push received callback
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Handle the received notification
    }
});

// Set up push opened callback
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Handle the opened notification
    }
});

Configuration de l’utilisateur

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

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class Registration {
  async afterUserLogin(user) {

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

    // Setting additional user information as tags for Pushwoosh
    await 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 un envoi de messages ciblé.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

class UpdateUser {
 async afterUserUpdateProfile(user) {

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

    // Set payment information
    await 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 dans l’application qui peuvent être suivies pour analyser le comportement et déclencher des messages ou des actions correspondants.

import { Pushwoosh } from 'pushwoosh-capacitor-plugin';

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 une notification push n’est pas délivrée, recherchez le code d’erreur de votre plateforme dans Erreurs d’envoi pour savoir ce qu’il signifie et comment le corriger.

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