Capacitor SDK: Leitfaden zur Basis-Integration

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

Voraussetzungen

Um das Pushwoosh Capacitor 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 Konfiguration mit tokenbasierter Authentifizierung als einfachsten Ansatz.
  • Stellen Sie das Gateway auf Sandbox ein, um Pushes an einen Simulator zu senden.
  • Um das Plugin mit Swift Package Manager hinzuzufügen: Capacitor 7 oder 8. Um ein CocoaPods-Projekt zu Swift Package Manager zu migrieren: @capacitor/cli 7.4.0 oder höher.
• Für die Android-Integration:
  • Eine konfigurierte Android-Plattform
  • Die Datei google-services.json und den package name aus Ihrem Firebase-Projekt.
  • Ein Firebase-Projekt, das mit Ihrer Android-Anwendung verbunden ist. Folgen Sie bei Bedarf der Firebase-Einrichtungsanleitung.
• Ihr Pushwoosh Application Code und Ihr Pushwoosh Device API Token aus dem Pushwoosh Control Panel für Ihre Anwendung.

Integrationsschritte

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

Fügen Sie die Pushwoosh Capacitor SDK-Abhängigkeit zu Ihrem Projekt hinzu:

npm install pushwoosh-capacitor-plugin

Synchronisieren Sie die Capacitor-Konfiguration:

npx cap sync

1.1 iOS-Paketmanager auswählen

npx cap sync installiert den iOS-Teil des Plugins mit dem Paketmanager, den Ihr Capacitor-Projekt verwendet: Swift Package Manager oder CocoaPods. Beide liefern dieselbe Version des nativen Pushwoosh SDK und der Inbox UI. Swift Package Manager wird mit Capacitor 7 und Capacitor 8 unterstützt.

Ein bestehendes Projekt behält seinen Paketmanager: Wenn ios/App/CapApp-SPM existiert, verwendet die Capacitor CLI Swift Package Manager, andernfalls CocoaPods. Für eine neue iOS-Plattform:

Capacitor 8

Capacitor 8 erstellt standardmäßig ein Swift-Package-Manager-Projekt:

npx cap add ios

Um stattdessen CocoaPods zu verwenden, führen Sie npx cap add ios --packagemanager CocoaPods aus.

Capacitor 7

Capacitor 7 erstellt standardmäßig ein CocoaPods-Projekt. Um Swift Package Manager zu verwenden, führen Sie Folgendes aus:

npx cap add ios --packagemanager SPM

Der Befehl erstellt das Projekt und bricht dann beim Versuch, pod install auszuführen, mit dem Fehler ENOENT ... Podfile ab. Das Projekt wird dennoch korrekt erstellt. Schließen Sie die Einrichtung ab mit:

npx cap sync ios

Mit Swift Package Manager fügt die Capacitor CLI das Plugin zu ios/App/CapApp-SPM hinzu, und das Plugin bringt das Pushwoosh iOS SDK und die Inbox UI mit. Fügen Sie das Pushwoosh SDK nicht ein zweites Mal zur App hinzu, weder als Pod noch als Paket mit einer anderen Version.

Einstellung von CocoaPods

CocoaPods trunk wird am 2. Dezember 2026 schreibgeschützt, und Pushwoosh stellt das iOS SDK auf Swift Package Manager um. Plugin-Versionen nach diesem Datum verwenden nur noch das Swift-Paket. Bis dahin zeigen pod install und der Xcode-Build eines CocoaPods-Projekts eine entsprechende Warnung an. Die Warnung beeinträchtigt den Build nicht.

Um ein bestehendes CocoaPods-Projekt zu migrieren, führen Sie npx cap spm-migration-assistant aus und folgen Sie dann dem verlinkten manuellen Xcode-Schritt. Der Befehl erfordert @capacitor/cli 7.4.0 oder höher.

2. Initialisierung des Capacitor SDK

Importieren und initialisieren Sie das Pushwoosh SDK in Ihrer Haupt-JavaScript-Datei:

index.js

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

// Initialisieren Sie das SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Für Push-Benachrichtigungen registrieren
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Erfolgreiche Registrierung behandeln
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Registrierungsfehler behandeln
    });

Wobei:

• __YOUR_APP_CODE__ ist der Anwendungscode aus dem Pushwoosh Control Panel.

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 Time Sensitive Notifications (iOS 15+) verwenden möchten, fügen Sie auch die Capability Time Sensitive Notifications hinzu.

3.2 Info.plist

Setzen Sie in Ihrer ios/App/App/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 Nachverfolgung der Nachrichtenzustellung

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

Befolgen Sie die Schritte der nativen Anleitung, um das Erweiterungsziel und den erforderlichen Pushwoosh-Code darin hinzuzufügen. Fügen Sie das Pushwoosh SDK je nach Paketmanager zum Extension-Target hinzu:

• CocoaPods: Folgen Sie dem Schritt Abhängigkeiten für die Notification Service Extension (nur CocoaPods) der nativen Anleitung. Fügen Sie in ios/App/Podfile dem Extension-Target pod 'PushwooshXCFramework' ohne Version hinzu, damit es auf die vom Plugin verwendete Version aufgelöst wird, und führen Sie dann npx cap sync ios aus.

• Swift Package Manager: Überspringen Sie den Schritt mit den CocoaPods-Abhängigkeiten aus der nativen Anleitung. Fügen Sie das SDK in Xcode selbst zum Extension-Target hinzu, da das Target die Abhängigkeiten des Plugins nicht erbt:

  1. Öffnen Sie das Extension-Target > General > Frameworks and Libraries.
  2. Fügen Sie das Produkt PushwooshFramework aus dem Paket Pushwoosh-XCFramework hinzu. Verwenden Sie die Version, die bereits in Package.resolved steht.

  Wenn Sie von CocoaPods migriert haben, stellen Sie sicher, dass die Extension PushwooshXCFramework nicht mehr als Pod erhält, damit die App das SDK nicht doppelt enthält.

Fügen Sie dann import PushwooshFramework in den Code der Extension ein. Das App-Target benötigt nichts weiter, da es das Pushwoosh SDK über das Plugin erhält.

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-Datei 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 im 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 der Token im Pushwoosh Control Panel Zugriff auf die richtige App hat. Erfahren Sie mehr

5. Das Projekt ausführen

1. Erstellen Sie das Projekt und führen Sie es 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 Capacitor SDK gibt es zwei Callback-Methoden zur Behandlung von Push-Benachrichtigungen:

• pushReceivedCallback wird ausgelöst, wenn eine Push-Benachrichtigung empfangen wird
• pushOpenedCallback wird ausgelöst, wenn ein Benutzer eine Benachrichtigung öffnet

Sie sollten diese Callbacks direkt nach der Initialisierung des SDK einrichten:

index.js

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

// Callback für empfangene Pushes einrichten
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Die empfangene Benachrichtigung behandeln
    }
});

// Callback für geöffnete Pushes einrichten
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Die geöffnete Benachrichtigung behandeln
    }
});

Benutzerkonfiguration

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

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

class Registration {
  async afterUserLogin(user) {

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

    // Zusätzliche Benutzerinformationen als Tags für Pushwoosh setzen
    await 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 nach Attributen wie Vorlieben oder Verhalten ermöglichen, was gezielte Nachrichtenübermittlung ermöglicht.

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

class UpdateUser {
 async afterUserUpdateProfile(user) {

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

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

Events

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

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

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 eine Push-Benachrichtigung nicht zugestellt wird, suchen Sie den Fehlercode für Ihre Plattform unter Sendefehler, um zu erfahren, was er bedeutet und wie Sie ihn beheben.

Wenn Sie während des Integrationsprozesses auf Probleme stoßen, lesen Sie bitte den Abschnitt Support und Community.