Cordova SDK 基础集成指南

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

先决条件

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

要求

• 一个 Pushwoosh 账户。
• 在您的账户中设置好的一个 Pushwoosh 项目。
• 对于 iOS 集成：
  • 一个配置为发送推送通知的 iOS 平台。我们建议使用基于令牌的身份验证配置作为最简单的方法。
  • 将网关设置为 Sandbox 以向模拟器发送推送。
• 对于 Android 集成：
  • 一个已配置的 Android 平台
  • 来自您的 Firebase 项目的 project number（也称为 Sender ID）、google-services.json 文件和 package name。
  • 一个连接到您的 Android 应用程序的 Firebase 项目。如果需要，请遵循 Firebase 设置指南。
• 您的 Pushwoosh Application Code 和来自您应用程序的 Pushwoosh 控制面板的 Pushwoosh Device API Token。

集成步骤

1. 添加 Pushwoosh Cordova SDK 依赖

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

cordova plugin add pushwoosh-cordova-plugin

2. Cordova SDK 初始化

在您的 index.js 文件的根组件中，将以下代码添加到 deviceready 事件处理程序内。请严格按照顺序执行以下步骤：

index.js

document.addEventListener('deviceready', function() {
    var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

    // 1. 在初始化之前注册通知回调
    document.addEventListener('push-receive', function(event) {
        var notification = event.notification;
        console.log("Push received: " + JSON.stringify(notification));
    });

    document.addEventListener('push-notification', function(event) {
        var notification = event.notification;
        console.log("Push opened: " + JSON.stringify(notification));
    });

    // 2. 初始化 Pushwoosh
    pushwoosh.onDeviceReady({
        appid: "__YOUR_APP_ID__",
        projectid: "__YOUR_FCM_SENDER_ID__"
    });

    // 3. 注册设备以接收推送通知
    pushwoosh.registerDevice(
        function(status) {
            var pushToken = status.pushToken;
            // 处理成功注册
        },
        function(status) {
            // 处理注册错误
        }
    );
}, false);

其中：

• __YOUR_APP_ID__ 是来自 Pushwoosh 控制面板的应用程序代码。
• __YOUR_FCM_SENDER_ID__ 是来自 Firebase 控制台的 Firebase 项目编号。

初始化顺序至关重要

初始化序列必须严格遵循上面显示的顺序：

1. 首先注册事件监听器 (push-receive, push-notification)
2. 然后调用 onDeviceReady()
3. 然后调用 registerDevice()

更改此顺序可能会导致以下问题：

• 在 onDeviceReady() 之后注册事件监听器： 如果应用程序是通过点击推送通知启动的（冷启动），onDeviceReady() 会立即将启动通知的有效负载传递给 JavaScript。如果此时您的监听器尚未注册，启动通知将会丢失，并且无法恢复。
• 在 onDeviceReady() 之前调用 registerDevice()： 原生 SDK 可能尚未正确配置您的 App ID 和 Sender ID，这可能导致设备注册静默失败或返回错误。
• 在 registerDevice() 之后注册事件监听器： 在您的监听器就位之前到达并处理的任何推送通知都将作为 DOM 事件被分派，并由于插件中没有重播机制而被静默丢弃。

该插件不会在 JavaScript 端排队或缓冲错过的事件。由 document.dispatchEvent() 触发的 DOM 事件仅传递给在分派时已经注册的监听器。

3. iOS 原生设置

3.1 功能 (Capabilities)

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

在 “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：

info.plist

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

3.3 消息送达跟踪

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

请遵循原生指南中的步骤来添加扩展目标并在其中添加必要的 Pushwoosh 代码。

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 SDK 中有两个事件监听器，专为处理推送通知而设计：

• 当应用程序处于前台时收到推送通知，会触发 push-receive 事件
• 当用户打开通知时，会触发 push-notification 事件

这些事件监听器必须在调用 onDeviceReady() 之前注册，如上面的初始化步骤所示。您可以根据需要自定义处理逻辑：

index.js

// 在 onDeviceReady() 之前注册
document.addEventListener('push-receive', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push received: " + message);
    // 在此处添加您的自定义逻辑
});

document.addEventListener('push-notification', function(event) {
    var message = event.notification.message;
    var payload = event.notification.userdata;
    console.log("Push accepted: " + message);
    // 在此处添加您的自定义逻辑（例如，导航到特定屏幕）
});

用户配置

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

class Registration {
  afterUserLogin(user) {

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

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

标签 (Tags)

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

class UpdateUser {
  afterUserUpdateProfile(user) {

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

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

事件 (Events)

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

class Registration {

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

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

故障排除

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