Capacitor SDK 基础集成指南

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

前提条件

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

要求

• 一个 Pushwoosh 账户。
• 在您的账户中设置一个 Pushwoosh 项目。
• 对于 iOS 集成：
  • 一个配置为发送推送通知的 iOS 平台。我们建议使用 基于令牌的身份验证配置 作为最简单的方法。
  • 将网关设置为 Sandbox 以向模拟器发送推送。
  • 通过 Swift Package Manager 添加插件：需要 Capacitor 7 或 8。将 CocoaPods 项目迁移到 Swift Package Manager：需要 @capacitor/cli 7.4.0 或更高版本。
• 对于 Android 集成：
  • 一个 已配置的 Android 平台
  • 来自您的 Firebase 项目的 google-services.json 文件和 package name。
  • 一个连接到您的 Android 应用程序的 Firebase 项目。如果需要，请遵循 Firebase 设置指南。
• 您的 Pushwoosh Application Code 和来自您应用程序的 Pushwoosh 控制面板的 Pushwoosh Device API Token。

集成步骤

1. 添加 Pushwoosh Capacitor SDK 依赖

将 Pushwoosh Capacitor SDK 依赖项添加到您的项目中：

npm install pushwoosh-capacitor-plugin

同步 Capacitor 配置：

npx cap sync

1.1 选择 iOS 包管理器

npx cap sync 会使用您的 Capacitor 项目所用的包管理器（Swift Package Manager 或 CocoaPods）安装插件的 iOS 部分。两者提供相同版本的原生 Pushwoosh SDK 和 Inbox UI。Capacitor 7 和 Capacitor 8 均支持 Swift Package Manager。

现有项目会保留其包管理器：如果存在 ios/App/CapApp-SPM，Capacitor CLI 使用 Swift Package Manager，否则使用 CocoaPods。对于新的 iOS 平台：

Capacitor 8

Capacitor 8 默认创建 Swift Package Manager 项目：

npx cap add ios

如需改用 CocoaPods，请运行 npx cap add ios --packagemanager CocoaPods。

Capacitor 7

Capacitor 7 默认创建 CocoaPods 项目。如需使用 Swift Package Manager，请运行：

npx cap add ios --packagemanager SPM

该命令会创建项目，然后在尝试运行 pod install 时因 ENOENT ... Podfile 错误而停止。项目已正确创建。使用以下命令完成设置：

npx cap sync ios

使用 Swift Package Manager 时，Capacitor CLI 会将插件添加到 ios/App/CapApp-SPM，插件会引入 Pushwoosh iOS SDK 和 Inbox UI。请勿再次将 Pushwoosh SDK 添加到应用中，无论是作为 pod 还是作为不同版本的包。

CocoaPods 弃用

CocoaPods trunk 将于 2026 年 12 月 2 日变为只读，Pushwoosh 正在将 iOS SDK 迁移到 Swift Package Manager。此日期之后发布的插件版本将仅使用 Swift 包。在此之前，CocoaPods 项目的 pod install 和 Xcode 构建会显示相关警告。该警告不影响构建。

要迁移现有的 CocoaPods 项目，请运行 npx cap spm-migration-assistant，然后按照其链接的手动 Xcode 步骤操作。该命令需要 @capacitor/cli 7.4.0 或更高版本。

2. Capacitor SDK 初始化

在您的主 JavaScript 文件中，导入并初始化 Pushwoosh SDK：

index.js

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

// Initialize the SDK
Pushwoosh.onDeviceReady({
    appid: "__YOUR_APP_CODE__"
});

// Register for push notifications
Pushwoosh.registerDevice()
    .then(result => {
        console.log("Push token:", result.pushToken);
        // Handle successful registration
    })
    .catch(error => {
        console.error("Failed to register device:", error);
        // Handle registration error
    });

其中：

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

3. iOS 原生设置

3.1 功能

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

在“签名与功能”部分，添加以下功能：

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

如果您打算使用时效性通知 (iOS 15+)，还需添加 Time Sensitive Notifications 功能。

3.2 Info.plist

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

info.plist

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

3.3 消息送达跟踪

您必须向您的项目添加一个通知服务扩展目标。这对于在 iOS 上实现准确的送达跟踪和富媒体等功能至关重要。

请遵循 原生指南的步骤 来添加扩展目标并在其中添加必要的 Pushwoosh 代码。根据您的包管理器，将 Pushwoosh SDK 添加到扩展目标：

• CocoaPods： 按照原生指南中的 Notification Service Extension 的依赖项 (仅限 CocoaPods) 步骤操作。在 ios/App/Podfile 中，为扩展目标添加不带版本号的 pod 'PushwooshXCFramework'，使其解析为插件所用的版本，然后运行 npx cap sync ios。

• Swift Package Manager： 跳过原生指南中的 CocoaPods 依赖项步骤。请在 Xcode 中自行将 SDK 添加到扩展目标，因为该目标不会继承插件的依赖项：

  1. 打开扩展目标 > General > Frameworks and Libraries。
  2. 添加 Pushwoosh-XCFramework 包中的 PushwooshFramework 产品。使用 Package.resolved 中已有的版本。

  如果您是从 CocoaPods 迁移过来的，请确保扩展不再以 pod 形式获取 PushwooshXCFramework，以免应用中包含两份 SDK。

然后在扩展代码中 import PushwooshFramework。App 目标无需额外操作，因为它通过插件获取 Pushwoosh SDK。

4. Android 原生设置

4.1 安装依赖

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

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

android/build.gradle

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

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

app/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：

AndroidManifest.xml

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

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

5. 运行项目

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

扩展集成

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

推送通知事件监听器

在 Pushwoosh Capacitor SDK 中，有两个用于处理推送通知的回调方法：

• pushReceivedCallback 在收到推送通知时触发
• pushOpenedCallback 在用户打开通知时触发

您应该在 SDK 初始化后立即设置这些回调：

index.js

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

// Set up push received callback
await Pushwoosh.pushReceivedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process received notification:", err);
    } else {
        console.log("Push received:", JSON.stringify(notification));
        // Handle the received notification
    }
});

// Set up push opened callback
await Pushwoosh.pushOpenedCallback((notification, err) => {
    if (err) {
        console.error("Failed to process opened notification:", err);
    } else {
        console.log("Push opened:", JSON.stringify(notification));
        // Handle the opened notification
    }
});

用户配置

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

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

class Registration {
  async afterUserLogin(user) {

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

    // Setting additional user information as tags for Pushwoosh
    await Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}

标签 (Tags)

标签 (Tags) 是分配给用户或设备的键值对，允许根据偏好或行为等属性进行分段，从而实现有针对性的消息传递。

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

class UpdateUser {
 async afterUserUpdateProfile(user) {

    // Set list of favorite categories
    await Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

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

事件 (Events)

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

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

class Registration {

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

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

故障排除

如果推送未送达，请在发送错误中查找您所用平台的错误代码，了解其含义及修复方法。

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