Flutter SDK 基础集成指南

本节包含有关如何将 Pushwoosh Flutter SDK 集成到您的应用程序中的信息。

先决条件

要将 Pushwoosh Flutter SDK 集成到您的应用中，您需要具备以下条件：

集成步骤

1. 添加 Pushwoosh Flutter SDK 依赖项

将 pushwoosh_flutter 包添加到您的 pubspec.yaml 文件中：

dependencies:
  flutter:
    sdk: flutter
  # 使用 https://pub.dev/packages/pushwoosh_flutter 上的最新版本
  pushwoosh_flutter: ^[LATEST_VERSION]

在 pub.dev 上查看最新版本。

然后，在您项目的根目录中运行以下命令来安装依赖项：

flutter pub get

仔细检查该包是否已正确安装：

flutter pub deps | grep pushwoosh_flutter

# 示例输出：
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11

2. Flutter SDK 初始化

在您的 main.dart 文件的根组件中：

导入 pushwoosh_flutter 包。
初始化 Pushwoosh SDK。
在您的初始化逻辑中调用 registerForPushNotifications() 以注册推送通知。

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

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

其中：

__YOUR_APP_ID__ 是来自 Pushwoosh 控制面板的应用程序代码。

3. iOS 原生设置

3.1 功能

要在您的项目中启用推送通知，您需要添加某些功能。

在“Signing & Capabilities”部分，添加以下功能：

Push Notifications
Background Modes。添加此功能后，选中 Remote notifications 复选框。

如果您打算使用 Time Sensitive Notifications (iOS 15+)，也请添加 Time Sensitive Notifications 功能。

3.2 Info.plist

在您的 Runner/Info.plist 中，将 __PUSHWOOSH_DEVICE_API_TOKEN__ 键设置为 Pushwoosh Device API Token：

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

3.3 消息送达跟踪

您必须向您的项目添加一个 Notification Service Extension 目标。这对于准确的送达跟踪和 iOS 上的富媒体等功能至关重要。

按照原生指南的步骤添加扩展目标并在其中添加必要的 Pushwoosh 代码。

为确保 Notification Service Extension 正确集成到您的 Flutter 项目中，您需要使用以下 Podfile 配置：

target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end

3.4 为 iOS Flutter 项目安装依赖项

要为 iOS Flutter 项目安装依赖项，请运行以下命令：

flutter run

或在终端中导航到 ios 文件夹并运行：

pod install --repo-update

4. Android 原生设置

4.1 安装依赖项

确保所需的依赖项和插件已添加到您的 Gradle 脚本中：

将 Google Services Gradle 插件添加到您的项目级 build.gradle 依赖项中：

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

在您的应用级 build.gradle 文件中应用该插件：

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

4.2 添加 Firebase 配置文件

将 google-services.json 文件放入您项目目录的 android/app 文件夹中。

4.3 添加 Pushwoosh 元数据

在您的 main/AndroidManifest.xml 中，在 <application> 标签内添加 Pushwoosh Device API Token：

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

重要提示： 请确保在您的 Pushwoosh 控制面板中为令牌授予对正确应用的访问权限。了解更多

5. 运行项目

构建并运行项目。
转到 Pushwoosh 控制面板并发送推送通知。
您应该会在应用中看到该通知。

扩展集成

到此阶段，您已经集成了 SDK，可以发送和接收推送通知。现在，让我们来探索核心功能。

推送通知事件监听器

在 Pushwoosh SDK 中，有两个事件监听器，专为处理推送通知而设计：

当收到推送通知时，会触发 onPushReceived 事件
当用户打开通知时，会触发 onPushAccepted 事件

您应该在应用程序启动时初始化 SDK 后立即设置这些事件监听器：

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}");
    });

  }
}

用户配置

通过关注个人用户的行为和偏好，您可以提供个性化内容，从而提高用户满意度和忠诚度。

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {
  void afterUserLogin(User user) {

    // 设置用户 ID
    Pushwoosh().setUserId(user.getId());

    // 设置用户邮箱
    Pushwoosh().setEmail(user.getEmail());

    // 注册短信号码
    // 短信和 WhatsApp 号码必须为 E.164 格式（例如，“+1234567890”）并且有效
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // 注册 WhatsApp 号码
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());

    // 将其他用户信息设置为 Pushwoosh 的标签
    Pushwoosh().setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class UpdateUser {
  void afterUserUpdateProfile(User user) {

    // 设置喜爱的类别列表
    Pushwoosh().setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // 设置支付信息
    Pushwoosh().setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}

事件

事件是应用内可以跟踪的特定用户操作或事件，用于分析行为并触发相应的消息或操作。

import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

class Registration {

  // 跟踪登录事件
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

  // 跟踪购买事件
  Pushwoosh().postEvent("purchase", {
    "product_id": product.getId(),
    "product_name": product.getName(),
    "price": product.getPrice(),
    "quantity": product.getQuantity()
  });
 }
}

使用 ProGuard

因此，您可能会收到此异常：

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

在这种情况下有两种解决方案：

使用 flutter build apk --no-shrink 命令编译您的代码而不进行混淆。
或者您可以手动启用 ProGuard 并添加必要的规则。

要为您的项目启用 ProGuard，请将以下字符串添加到您的 build.gradle 文件中：

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

            signingConfig signingConfigs.debug
        }
    }

然后，将以下规则添加到 android/app/proguard-rules.pro 中

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

故障排除

如果您在集成过程中遇到任何问题，请参阅支持和社区部分。