# Flutter SDK 基础集成指南 本节包含有关如何将 Pushwoosh Flutter SDK 集成到您的应用程序中的信息。 ## 先决条件 要将 Pushwoosh Flutter SDK 集成到您的应用中，您需要具备以下条件： ## 集成步骤 ### 1. 添加 Pushwoosh Flutter SDK 依赖项 将 `pushwoosh_flutter` 包添加到您的 `pubspec.yaml` 文件中： ```yaml title="pubspec.yaml" dependencies: flutter: sdk: flutter # 使用 https://pub.dev/packages/pushwoosh_flutter 上的最新版本 pushwoosh_flutter: ^[LATEST_VERSION] ``` 在 pub.dev 上查看[最新版本](https://pub.dev/packages/pushwoosh_flutter)。 然后，在您项目的根目录中运行以下命令来安装依赖项： ```bash flutter pub get ``` 仔细检查包是否已正确安装： ```bash 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()` 来注册推送通知。 ```dart title="main.dart" 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 功能 要在您的项目中启用推送通知，您需要添加某些功能。 在“签名与功能”部分，添加以下功能： - `Push Notifications` - `Background Modes`。添加此功能后，勾选 `Remote notifications` 复选框。 如果您打算使用时间敏感通知 (iOS 15+)，也请添加 `Time Sensitive Notifications` 功能。 #### 3.2 Info.plist 在您的 `Runner/Info.plist` 中，将 `__PUSHWOOSH_DEVICE_API_TOKEN__` 键设置为 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)： ```swift title="info.plist" Pushwoosh_API_TOKEN __PUSHWOOSH_DEVICE_API_TOKEN__ ``` #### 3.3 消息送达跟踪 您必须向您的项目添加一个通知服务扩展目标。这对于准确的送达跟踪和 iOS 上的富媒体等功能至关重要。 请遵循[原生指南的步骤](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#4-message-delivery-tracking)来添加扩展目标及其中的必要 Pushwoosh 代码。 为确保通知服务扩展正确集成到您的 Flutter 项目中，您需要使用以下 Podfile 配置： ```ruby title="Podfile" target 'NotificationServiceExtension' do use_frameworks! use_modular_headers! pod 'PushwooshXCFramework' inherit! :search_paths end ``` #### 3.4 为 iOS Flutter 项目安装依赖项 要为 iOS Flutter 项目安装依赖项，请运行以下命令： ```bash flutter run ``` 或在终端中导航到 `ios` 文件夹并运行： ```bash pod install --repo-update ``` ### 4. Android 原生设置 #### 4.1 安装依赖项 确保所需的依赖项和插件已添加到您的 Gradle 脚本中： 将 Google Services Gradle 插件添加到您的项目级 `build.gradle` 依赖项中： ```groovy title="android/build.gradle" buildscript { dependencies { classpath 'com.google.gms:google-services:4.3.15' } } ``` 在您的应用级 `build.gradle` 文件中应用该插件： ```groovy title="app/build.gradle" apply plugin: 'com.google.gms.google-services' ``` #### 4.2 添加 Firebase 配置文件 将 `google-services.json` 文件放入您项目目录的 `android/app` 文件夹中。 #### 4.3 添加 Pushwoosh 元数据 在您的 `main/AndroidManifest.xml` 中，在 `` 标签内添加 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)： ```xml title="AndroidManifest.xml" ``` > **重要提示：** 请确保在您的 Pushwoosh 控制面板中为令牌授予对正确应用的访问权限。[了解更多](/zh/developer/api-reference/api-access-token/#edit-token) ### 5. 运行项目 1. 构建并运行项目。 2. 转到 Pushwoosh 控制面板并[发送一条推送通知](/zh/product/messaging-channels/push-notifications/send-push-notifications/one-time-push)。 3. 您应该会在应用中看到该通知。 ## 扩展集成 至此，您已经集成了 SDK，可以发送和接收推送通知了。现在，让我们来探索核心功能 ### 推送通知事件监听器 在 Pushwoosh SDK 中，有两个事件监听器，专为处理推送通知而设计： - `onPushReceived` 事件在收到推送通知时触发 - `onPushAccepted` 事件在用户打开通知时触发 您应该在应用程序启动时，在 SDK 初始化之后立即设置这些事件监听器： ```dart 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}"); }); } } ``` ### 用户配置 通过关注个人用户的行为和偏好，您可以提供个性化内容，从而提高用户满意度和忠诚度 ```dart import 'package:pushwoosh_flutter/pushwoosh_flutter.dart'; class Registration { void afterUserLogin(User user) { // 设置用户 ID Pushwoosh().setUserId(user.getId()); // 设置用户邮箱 Pushwoosh().setEmail(user.getEmail()); // 注册 SMS 号码 // SMS 和 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() }); } } ``` ### 标签 标签是分配给用户或设备的键值对，允许根据偏好或行为等属性进行分段，从而实现定向消息传递。 ```dart 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() }); } } ``` ### 事件 事件是应用内特定的用户操作或发生的事情，可以被跟踪以分析行为并触发相应的消息或操作 ```dart 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 java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension ``` 在这种情况下，有两种解决方案： 1. 使用 `flutter build apk --no-shrink` 命令编译您的代码，而不进行混淆。 2. 或者您可以手动启用 ProGuard 并添加必要的规则。 要为您的项目启用 ProGuard，请将以下字符串添加到您的 `build.gradle` 文件中： ```java title="build.gradle" buildTypes { release { minifyEnabled true useProguard true proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' signingConfig signingConfigs.debug } } ``` 然后，将以下规则添加到 `android/app/proguard-rules.pro` ```java title="proguard-rules.pro" #Pushwoosh Flutter -keep class com.pushwoosh.plugin.PushwooshPlugin { *; } -keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; } ``` ## 故障排除 如果您在集成过程中遇到任何问题，请参阅[支持和社区](/zh/developer/pushwoosh-sdk/support-and-community)部分。