Flutter SDK: Grundlegende Integrationsanleitung

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

Voraussetzungen

Um das Pushwoosh Flutter 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 für den Versand von Push-Benachrichtigungen konfigurierte iOS-Plattform. Wir empfehlen die Verwendung der Token-basierten Authentifizierungskonfiguration als einfachsten Ansatz.
  • Stellen Sie das Gateway auf Sandbox ein, um Pushes an einen Simulator zu senden.
• Für die Android-Integration:
  • Eine konfigurierte Android-Plattform
  • Die Projektnummer (auch als Sender-ID bekannt), die Datei google-services.json und den Paketnamen aus Ihrem Firebase-Projekt.
  • Ein mit Ihrer Android-Anwendung verbundenes Firebase-Projekt. 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 Flutter SDK-Abhängigkeit hinzufügen

Fügen Sie das pushwoosh_flutter-Paket zu Ihrer pubspec.yaml-Datei hinzu:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  # Use the latest version from https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]

Überprüfen Sie die neueste Version auf pub.dev.

Führen Sie dann den folgenden Befehl im Stammverzeichnis Ihres Projekts aus, um die Abhängigkeit zu installieren:

flutter pub get

Überprüfen Sie, ob das Paket korrekt installiert ist:

flutter pub deps | grep pushwoosh_flutter

# Example output:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11

2. Flutter SDK-Initialisierung

In der Stammkomponente Ihrer main.dart-Datei:

• Importieren Sie das pushwoosh_flutter-Paket.
• Initialisieren Sie das Pushwoosh SDK.
• Rufen Sie registerForPushNotifications() in Ihrer Initialisierungslogik auf, um sich für Push-Benachrichtigungen zu registrieren.

main.dart

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__",
    "sender_id": "__YOUR_FCM_SENDER_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}

Wobei:

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

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 Time Sensitive Notifications-Capability hinzu.

3.2 Info.plist

Setzen Sie in Ihrer Runner/Info.plist-Datei 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 Target hinzufügen. Dies ist für eine genaue Zustellungsverfolgung und Funktionen wie Rich Media unter iOS unerlässlich.

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

Um sicherzustellen, dass die Notification Service Extension ordnungsgemäß in Ihr Flutter-Projekt integriert ist, müssen Sie die folgende Podfile-Konfiguration verwenden:

Podfile

target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end

3.4 Installation von Abhängigkeiten für das iOS Flutter-Projekt

Um Abhängigkeiten für das iOS Flutter-Projekt zu installieren, führen Sie den folgenden Befehl aus:

flutter run

oder navigieren Sie im Terminal zum Ordner ios und führen Sie aus:

pod install --repo-update

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

5. 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 SDK gibt es zwei Event-Listener, die für die Verarbeitung von Push-Benachrichtigungen konzipiert sind:

• Das onPushReceived-Event wird ausgelöst, wenn eine Push-Benachrichtigung empfangen wird.
• Das onPushAccepted-Event wird ausgelöst, wenn ein Benutzer eine Benachrichtigung öffnet.

Sie sollten diese Event-Listener direkt nach der Initialisierung des SDK beim Start der Anwendung einrichten:

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });

  }
}

Benutzerkonfiguration

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

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {

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

    // Set user email
    Pushwoosh().setEmail(user.getEmail());

    // Register SMS number
    // The SMS and WhatsApp numbers must be in E.164 format (e.g., "+1234567890") and be valid
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // Register WhatsApp number
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

    // Setting additional user information as tags for Pushwoosh
    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 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User 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()
    });
  }
}

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 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

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

  void afterUserPurchase(Product product) {

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

Verwendung von ProGuard

Hinweis

Beachten Sie, dass der Befehl flutter build apk Ihren Code standardmäßig verschleiert.

Daher erhalten Sie möglicherweise diese Ausnahme:

java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension

In diesem Fall gibt es zwei Lösungen:

1. Verwenden Sie den Befehl flutter build apk --no-shrink, um Ihren Code ohne Verschleierung zu kompilieren.
2. Oder Sie können ProGuard manuell aktivieren und die notwendigen Regeln hinzufügen.

Um ProGuard für Ihr Projekt zu aktivieren, fügen Sie die folgenden Zeichenfolgen zu Ihrer build.gradle-Datei hinzu:

build.gradle

buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }

Fügen Sie dann die folgenden Regeln zu android/app/proguard-rules.pro hinzu

proguard-rules.pro

#Pushwoosh Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }

Fehlerbehebung

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