Cordova SDK: Grundlegende Integrationsanleitung

Dieser Abschnitt enthält Informationen zur Integration des Pushwoosh Cordova SDK in Ihre Anwendung.

Voraussetzungen

Um das Pushwoosh Cordova SDK in Ihre App zu integrieren, benötigen Sie Folgendes:

Anforderungen

• Ein Pushwoosh-Konto.
• Ein in Ihrem Konto eingerichtetes Pushwoosh-Projekt.
• Für die iOS-Integration:
  • Eine iOS-Plattform, die für den Versand von Push-Benachrichtigungen konfiguriert ist. Wir empfehlen die Verwendung der tokenbasierten Authentifizierungskonfiguration als einfachsten Ansatz.
  • Setzen Sie das Gateway auf Sandbox, um Pushes an einen Simulator zu senden.
• Für die Android-Integration:
  • Eine konfigurierte Android-Plattform
  • Die Projektnummer (auch bekannt als Sender-ID), die Datei google-services.json und der Paketname aus Ihrem Firebase-Projekt.
  • Ein Firebase-Projekt, das mit Ihrer Android-Anwendung verbunden ist. Folgen Sie bei Bedarf der Firebase-Einrichtungsanleitung.
• Ihr Pushwoosh-Anwendungscode und Ihr Pushwoosh Device API Token aus dem Pushwoosh Control Panel für Ihre Anwendung.

Integrationsschritte

1. Pushwoosh Cordova SDK-Abhängigkeit hinzufügen

Fügen Sie die Abhängigkeit des Pushwoosh Cordova SDK zu Ihrem Projekt hinzu:

cordova plugin add pushwoosh-cordova-plugin

2. Initialisierung des Cordova SDK

Fügen Sie in der Root-Komponente Ihrer index.js-Datei den folgenden Code innerhalb des deviceready-Event-Handlers hinzu. Befolgen Sie die Schritte in exakter Reihenfolge:

index.js

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

    // 1. Registrieren Sie Benachrichtigungs-Callbacks vor der Initialisierung
    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. Initialisieren Sie Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

    // 3. Registrieren Sie das Gerät, um Push-Benachrichtigungen zu erhalten
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // Erfolgreiche Registrierung handhaben
        },
        function(status) {
            // Registrierungsfehler handhaben
        }
    );
}, false);

Wobei:

• __YOUR_APP_ID__ der Anwendungscode aus dem Pushwoosh Control Panel ist.
• __YOUR_FCM_SENDER_ID__ die Firebase-Projektnummer aus der Firebase Console ist.

Die Reihenfolge der Initialisierung ist wichtig

Die Initialisierungssequenz muss der oben gezeigten exakten Reihenfolge folgen:

1. Zuerst Event-Listener registrieren (push-receive, push-notification)
2. Dann onDeviceReady() aufrufen
3. Dann registerDevice() aufrufen

Eine Änderung dieser Reihenfolge kann folgende Probleme verursachen:

• Event-Listener werden nach onDeviceReady() registriert: Wenn die App durch Tippen auf eine Push-Benachrichtigung gestartet wurde (Kaltstart), liefert onDeviceReady() sofort die Payload der Startbenachrichtigung an JavaScript. Wenn Ihre Listener zu diesem Zeitpunkt noch nicht registriert sind, geht die Startbenachrichtigung verloren und kann nicht wiederhergestellt werden.
• registerDevice() wird vor onDeviceReady() aufgerufen: Das native SDK ist möglicherweise noch nicht korrekt mit Ihrer App-ID und Sender-ID konfiguriert, was dazu führen kann, dass die Geräteregistrierung stillschweigend fehlschlägt oder einen Fehler zurückgibt.
• Event-Listener werden nach registerDevice() registriert: Jede Push-Benachrichtigung, die ankommt und verarbeitet wird, bevor Ihre Listener vorhanden sind, wird als DOM-Event ausgelöst und stillschweigend verworfen, da es im Plugin keinen Wiederholungsmechanismus gibt.

Das Plugin stellt verpasste Events auf der JavaScript-Seite nicht in eine Warteschlange oder puffert sie. DOM-Events, die von document.dispatchEvent() ausgelöst werden, werden nur an Listener zugestellt, die zum Zeitpunkt des Versands bereits registriert sind.

3. Natives iOS-Setup

3.1 Capabilities

Um Push-Benachrichtigungen in Ihrem Projekt zu aktivieren, müssen Sie bestimmte Capabilities hinzufügen.

Fügen Sie im Abschnitt „Signing & Capabilities“ die folgenden Capabilities hinzu:

• Push Notifications
• Background Modes. Nachdem Sie diese Capability hinzugefügt haben, aktivieren Sie das Kontrollkästchen für Remote notifications.

Wenn Sie zeitkritische Benachrichtigungen (iOS 15+) verwenden möchten, fügen Sie auch die Capability Time Sensitive Notifications hinzu.

3.2 Info.plist

Setzen Sie in Ihrer Runner/Info.plist den Schlüssel __PUSHWOOSH_DEVICE_API_TOKEN__ auf den Pushwoosh Device API Token:

info.plist

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

3.3 Verfolgung der Nachrichtenzustellung

Sie müssen Ihrem Projekt ein Notification Service Extension Target hinzufügen. Dies ist für eine genaue Zustellungsverfolgung und Funktionen wie Rich Media unter iOS unerlässlich.

Folgen Sie den Schritten der nativen Anleitung, um das Extension Target und den erforderlichen Pushwoosh-Code darin hinzuzufügen.

4. Natives Android-Setup

4.1 Abhängigkeiten installieren

Stellen Sie sicher, dass die erforderlichen Abhängigkeiten und Plugins zu Ihren Gradle-Skripten hinzugefügt werden:

Fügen Sie das Google Services Gradle-Plugin zu den Abhängigkeiten Ihrer build.gradle auf Projektebene hinzu:

android/build.gradle

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

Wenden Sie das Plugin in Ihrer build.gradle-Datei auf App-Ebene an:

app/build.gradle

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

4.2 Firebase-Konfigurationsdatei hinzufügen

Platzieren Sie die Datei google-services.json in den Ordner android/app in Ihrem Projektverzeichnis.

4.3 Pushwoosh-Metadaten hinzufügen

Fügen Sie in Ihrer main/AndroidManifest.xml den Pushwoosh Device API Token innerhalb des <application>-Tags hinzu:

AndroidManifest.xml

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

Wichtig: Stellen Sie sicher, dass Sie dem Token im Pushwoosh Control Panel Zugriff auf die richtige App gewähren. Erfahren Sie mehr

5. Projekt ausführen

1. Erstellen und führen Sie das Projekt aus.
2. Gehen Sie zum Pushwoosh Control Panel und senden Sie eine Push-Benachrichtigung.
3. Sie sollten die Benachrichtigung in der App sehen.

Erweiterte Integration

In diesem Stadium haben Sie das SDK bereits integriert und können Push-Benachrichtigungen senden und empfangen. Lassen Sie uns nun die Kernfunktionalität erkunden.

Event-Listener für Push-Benachrichtigungen

Im Pushwoosh SDK gibt es zwei Event-Listener, die für die Handhabung von Push-Benachrichtigungen konzipiert sind:

• Das push-receive-Event wird ausgelöst, wenn eine Push-Benachrichtigung empfangen wird, während die App im Vordergrund ist.
• Das push-notification-Event wird ausgelöst, wenn ein Benutzer eine Benachrichtigung öffnet.

Diese Event-Listener müssen registriert werden, bevor onDeviceReady() aufgerufen wird, wie im Initialisierungsschritt oben gezeigt. Sie können die Handler-Logik an Ihre Bedürfnisse anpassen:

index.js

// Vor onDeviceReady() registrieren
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // Fügen Sie hier Ihre benutzerdefinierte Logik hinzu
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // Fügen Sie hier Ihre benutzerdefinierte Logik hinzu (z.B. Navigation zu einem bestimmten Bildschirm)
});

Benutzerkonfiguration

Indem Sie sich auf das individuelle Nutzerverhalten und die Vorlieben konzentrieren, können Sie personalisierte Inhalte liefern, was zu einer höheren Nutzerzufriedenheit und -loyalität führt.

class Registration {
  afterUserLogin(user) {

    // Benutzer-ID setzen
    pushwoosh.setUserId(user.getId());

    // Zusätzliche Benutzerinformationen als Tags für Pushwoosh setzen
    pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

Tags

Tags sind Schlüssel-Wert-Paare, die Benutzern oder Geräten zugewiesen werden und eine Segmentierung basierend auf Attributen wie Vorlieben oder Verhalten ermöglichen, was gezieltes Messaging ermöglicht.

class UpdateUser {
  afterUserUpdateProfile(user) {

    // Liste der Lieblingskategorien setzen
    pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // Zahlungsinformationen setzen
    pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

Events

Events sind spezifische Benutzeraktionen oder Ereignisse innerhalb der App, die verfolgt werden können, um das Verhalten zu analysieren und entsprechende Nachrichten oder Aktionen auszulösen.

class Registration {

  // Login-Event verfolgen
  afterUserLogin(user) {
    pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // Kauf-Event verfolgen
  afterUserPurchase(product) {
    pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}

Fehlerbehebung

Wenn während des Integrationsprozesses Probleme auftreten, lesen Sie bitte den Abschnitt Support und Community.