NativeScript 推送插件

此插件已弃用。 可以自由使用 Firebase 插件 在 NativeScript 应用中实现推送通知。如果您已经有一个使用推送插件的 app，请阅读 迁移到 Firebase 文档 以获取初始指导。

NativeScript 推送插件的代码。

• 安装
• 配置
  • Android
  • iOS
• 用法
  • 在 Android 中使用插件
  • 在 iOS 中使用插件
• API 参考
  • 方法
  • 仅限 Android
  • 仅限 iOS
• 故障排除
  • Android 中的故障排除问题
  • iOS 中的故障排除问题
• 使用 Firebase Cloud Messaging 的 Android 配置
  • 在 Android 上接收和处理 FCM 消息
• 贡献
• 获取帮助

安装

在命令提示符 / 终端中导航到您的应用程序根目录并运行

tns plugin add nativescript-push-notifications

配置

Android

有关如何将 Firebase 添加到项目的信息，请参阅 使用 Firebase Cloud Messaging 的 Android 配置。

• 通过将包标识符更改为与 Firebase 的项目包名称匹配来编辑应用程序根目录中的 package.json 文件。例如

  "id": "org.nativescript.PushNotificationApp"

• 通过将应用程序 ID 更改为与 package.json 中的包标识符匹配来编辑应用程序根目录中的 app/App_Resources/Android/app.gradle 文件。例如

  android {
  // ...
      defaultConfig {
          applicationId = "org.nativescript.PushNotificationApp"
      }
  // ...
  }

• 转到应用程序文件夹并将 Android 平台添加到应用程序

  tns platform add android

• 将带有 FCM 配置的 google-settings.json 文件添加到应用程序的 app/App_Resources/Android 文件夹中。如果没有添加此文件，则构建 Android 应用程序将失败。

插件将默认使用 firebase-messaging SDK 的 12.0.1 版本。如果需要更改版本，可以在项目中添加一个项目扩展属性 firebaseMessagingVersion

    // in the root level of /app/App_Resources/Android/app.gradle:
    project.ext {
        firebaseMessagingVersion = "+" // OR the version you wish
    }

iOS

• 请确保您已在 Apple 开发者账户中设置了一个应用程序，并且已启用并配置了推送通知。有关更多信息，请参阅 Apple 的 添加功能文档 > 配置推送通知 部分。

• 通过将包标识符更改为与 App ID 匹配来编辑应用程序根目录中的 package.json 文件。例如

  "id": "org.nativescript.PushNotificationApp"

• 转到应用程序文件夹并将 iOS 平台添加到应用程序

  tns build ios

• 转到（应用程序文件夹）/platforms/ios并打开 XCode 项目。在项目功能选项中启用推送通知。如果没有 XCode，请转到（应用程序文件夹）/platforms/ios/（应用程序文件夹名称），找到 *.entitlements 文件，并添加 aps-environment 键及其值，如下所示

  <plist version="1.0">
  <dict>
      <key>aps-environment</key>
      <string>development</string>
  </dict>
  </plist>

用法

在 Android 中使用插件

在您的视图模型或组件中添加代码以订阅和接收消息（不要忘记在注册方法的选项中输入您的 Firebase Cloud Messaging 发送者 ID）

TypeScript

import * as pushPlugin from "nativescript-push-notifications";
private pushSettings = {
    senderID: "<ENTER_YOUR_PROJECT_NUMBER>", // Required: setting with the sender/project number
    notificationCallbackAndroid: (stringifiedData: String, fcmNotification: any) => {
        const notificationBody = fcmNotification && fcmNotification.getBody();
        this.updateMessage("Message received!\n" + notificationBody + "\n" + stringifiedData);
    }
};
pushPlugin.register(pushSettings, (token: String) => {
    alert("Device registered. Access token: " + token);;
}, function() { });

JavaScript

var pushPlugin = require("nativescript-push-notifications");
var pushSettings = {
        senderID: "<ENTER_YOUR_PROJECT_NUMBER>", // Required: setting with the sender/project number
        notificationCallbackAndroid: function (stringifiedData, fcmNotification) {
            var notificationBody = fcmNotification && fcmNotification.getBody();
            _this.updateMessage("Message received!\n" + notificationBody + "\n" + stringifiedData);
        }
    };
pushPlugin.register(pushSettings, function (token) {
    alert("Device registered. Access token: " + token);
}, function() { });

• 在手机或模拟器上运行应用程序

  tns run android

• 在插件成功订阅接收通知后，访问令牌将写入控制台并在设备上显示。当收到通知时，如果应用已关闭，则消息将在通知区域显示；如果应用已打开，则会在notificationCallbackAndroid回调中直接处理。

在 iOS 中使用插件

在您的视图模型或组件中添加代码以订阅和接收消息

TypeScript

import * as pushPlugin from "nativescript-push-notifications";
const iosSettings = {
    badge: true,
    sound: true,
    alert: true,
    interactiveSettings: {
        actions: [{
            identifier: 'READ_IDENTIFIER',
            title: 'Read',
            activationMode: "foreground",
            destructive: false,
            authenticationRequired: true
        }, {
            identifier: 'CANCEL_IDENTIFIER',
            title: 'Cancel',
            activationMode: "foreground",
            destructive: true,
            authenticationRequired: true
        }],
        categories: [{
            identifier: 'READ_CATEGORY',
            actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'],
            actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER']
        }]
    },
    notificationCallbackIOS: (message: any) => {
        alert("Message received!\n" + JSON.stringify(message));
    }
};

pushPlugin.register(iosSettings, (token: String) => {
    alert("Device registered. Access token: " + token);

    // Register the interactive settings
    if(iosSettings.interactiveSettings) {
        pushPlugin.registerUserNotificationSettings(() => {
            alert('Successfully registered for interactive push.');
        }, (err) => {
            alert('Error registering for interactive push: ' + JSON.stringify(err));
        });
    }
}, (errorMessage: any) => {
    alert("Device NOT registered! " + JSON.stringify(errorMessage));
});

JavaScript

var pushPlugin = require("nativescript-push-notifications");
var iosSettings = {
    badge: true,
    sound: true,
    alert: true,
    interactiveSettings: {
        actions: [{
            identifier: 'READ_IDENTIFIER',
            title: 'Read',
            activationMode: "foreground",
            destructive: false,
            authenticationRequired: true
        }, {
            identifier: 'CANCEL_IDENTIFIER',
            title: 'Cancel',
            activationMode: "foreground",
            destructive: true,
            authenticationRequired: true
        }],
        categories: [{
            identifier: 'READ_CATEGORY',
            actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'],
            actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER']
        }]
    },
    notificationCallbackIOS: function (data) {
        alert("message", "" + JSON.stringify(data));
    }
};

pushPlugin.register(iosSettings, function (data) {
    alert("Device registered. Access token" + data);

    // Register the interactive settings
        if(iosSettings.interactiveSettings) {
            pushPlugin.registerUserNotificationSettings(function() {
                alert('Successfully registered for interactive push.');
            }, function(err) {
                alert('Error registering for interactive push: ' + JSON.stringify(err));
            });
        }
}, function() { });

• 在手机或模拟器上运行应用

  tns run ios

• [提示] 安装pusher应用，向正在调试的设备发送通知。在“设备推送令牌”字段中粘贴在应用启动后由 {N} CLI / XCode 调试控制台生成的设备访问令牌。

API 参考

方法

register(options, successCallback, errorCallback) - 使用Apple/Google推送通知服务订阅设备，以便应用可以接收通知

iOS的interactiveSettings对象可以包含以下内容

iOS交互设置中的actions数组包含以下内容

iOS交互设置中的categories数组包含以下内容

有关iOS交互式通知的更多信息，请访问Apple开发者网站

var settings = {
    badge: true,
    sound: true,
    alert: true,
    interactiveSettings: {
        actions: [{
            identifier: 'READ_IDENTIFIER',
            title: 'Read',
            activationMode: "foreground",
            destructive: false,
            authenticationRequired: true
        }, {
        identifier: 'CANCEL_IDENTIFIER',
            title: 'Cancel',
            activationMode: "foreground",
            destructive: true,
            authenticationRequired: true
        }],
        categories: [{
            identifier: 'READ_CATEGORY',
            actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'],
            actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER']
        }]
    },
    notificationCallbackIOS: function(message) {
        alert(JSON.stringify(message));
    }
};


pushPlugin.register(settings,
    // Success callback
    function(token){
        // Register the interactive settings
        if(settings.interactiveSettings) {
            pushPlugin.registerUserNotificationSettings(function() {
                alert('Successfully registered for interactive push.');
            }, function(err) {
                alert('Error registering for interactive push: ' + JSON.stringify(err));
            });
        }
    },
    // Error Callback
    function(error){
        alert(error.message);
    }
);

unregister(successCallback, errorCallback, options) - 取消订阅设备，以便应用停止接收推送通知。选项对象与register方法中相同

pushPlugin.unregister(
    // Success callback
    function(result) {
        alert('Device unregistered successfully');
    },
    // Error Callback
    function(errorMessage) {
        alert(errorMessage);
    },
    // The settings from the registration phase
    settings
);

areNotificationsEnabled(successCallback) - 检查是否启用了推送通知（iOS仅限，Android上始终返回true）

pushPlugin.areNotificationsEnabled(function(areEnabled) {
        alert('Are Notifications enabled: ' + areEnabled);
    });

仅限 Android

onMessageReceived(callback) 已弃用 - 注册一个回调函数，在收到通知时执行。您应该从notificationCallbackAndroid注册选项中设置此选项

fcmNotification 对象包含以下方法

onTokenRefresh(callback) - 当旧令牌被撤销并获取新令牌时，注册一个回调函数执行。注意，令牌不会作为参数传递给回调。如果您需要新的令牌值，您需要再次调用 register 或添加一些本地代码从 FCM 获取令牌。

pushPlugin.onTokenRefresh(function() {
        alert("new token obtained");
});

仅限 iOS

registerUserNotificationSettings(successCallback, errorCallback) - 用于在 iOS 上注册交互式推送

故障排除

如果应用无法正常工作。以下是一些您可以验证的事项

Android 中的故障排除问题

• 当使用 tns run android 启动应用时（即在调试模式下带有 live sync），某些后台通知可能无法正确接收。这是因为应用未以正常方式启动进行调试，并且从后台恢复的方式不同。要正确接收所有通知，请停止应用（从最近应用列表中滑动将其移除），然后通过在设备上轻触应用图标重新启动它。

• 自动添加了 google-services 插件。如果失败，您可以尝试手动添加

• • 导航到项目文件夹 platforms/android/
• • 将 google-services 插件添加到您的应用 build.gradle 文件中的其他依赖项列表中

    dependencies {
    	// ...
    	classpath "com.google.gms:google-services:3.0.0"
    	// ...
    }

• • 在您的 build.gradle 文件底部添加以下行以启用 Gradle 插件

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

• 确保位于 platforms/android/build/... 的 AndroidManifest.xml 文件（不要将其添加到 "App_Resources/Android/AndroidManifest.xml" 文件中）包含以下注册 GCM 监听器的片段

  <activity android:name="com.telerik.pushplugin.PushHandlerActivity"/>
  <receiver
      android:name="com.google.android.gms.gcm.GcmReceiver"
      android:exported="true"
      android:permission="com.google.android.c2dm.permission.SEND" >
      <intent-filter>
          <action android:name="com.google.android.c2dm.intent.RECEIVE" />
          <category android:name="com.pushApp.gcm" />
      </intent-filter>
  </receiver>
  <service
      android:name="com.telerik.pushplugin.PushPlugin"
      android:exported="false" >
      <intent-filter>
          <action android:name="com.google.android.c2dm.intent.RECEIVE" />
      </intent-filter>
  </service>

• 确保位于 platforms/android/build/... 的 AndroidManifest.xml 文件包含以下推送通知权限

  <uses-permission android:name="android.permission.WAKE_LOCK" />
  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

iOS 中的故障排除问题

• 错误 "Error registering: no valid 'aps-environment' entitlement string found for application" - 这意味着在 xcodeproject 中证书设置不正确。打开 xcodeproject，修复它们，甚至可以从 xcode 运行应用程序以验证其设置是否正确。xcode 中的包标识符应与项目根目录中 package.json 文件中的 "id" 相同。此外，请确保在项目设置中的 "Capabilities" 页上已开启 "Push Notifications"。

使用 Firebase Cloud Messaging 的 Android 配置

Android 的 nativescript-push-notifications 模块依赖于 Firebase 云消息 (FCM) SDK。在下面的步骤中，您将指导完成几个额外的步骤，以准备您的 Android 应用以接收来自 FCM 的推送通知。

1. 添加 google-services.json 文件

   要使用 FCM，您需要此文件。它包含您 Firebase 项目的配置和凭据。要获取此文件，请按照官方 文档 中的说明将 Firebase 添加到您的项目中。向下滚动到 手动添加 Firebase 部分。

   将文件放置在您的应用的 App_Resources/Android 文件夹中

2. 获取 FCM 服务器密钥（可选）

   此密钥是能够以编程方式向您的应用发送推送通知所必需的。您可以从您的 Firebase 项目中获取此密钥。

在 Android 上接收和处理 FCM 消息

插件允许处理包含 数据、通知 以及包含 两者 负载键的消息，在本文章中这些消息被称为 混合。有关这些消息的更多详细信息，请参阅 这里。

插件扩展了 FirebaseMessagingService 并重写了其 onMessageReceived 回调。在您的应用中，您需要在调用插件的 register 方法时使用 notificationCallbackAndroid 设置。

模块中回调的行为遵循 FCM 服务的操作。

处理 数据 消息

插件中的notificationCallbackAndroid方法会在接收到每次data通知时被调用。

如果应用程序被停止或挂起，则不会构建和放置任何通知在托盘上。点击应用程序图标将启动应用程序并调用notificationCallbackAndroid回调，您将在此接收通知数据。

如果应用程序处于活动状态且在前台，则立即调用notificationCallbackAndroid回调，并使用通知数据（fcmNotification）。

处理Notification消息

如果应用程序处于活动状态且在前台，则它会使用两个参数（stringifiedData，fcmNotification）调用notificationCallbackAndroid回调。

如果应用程序处于后台，则将通知放入托盘。当点击时，它会启动应用程序，但不会调用notificationCallbackAndroid回调。

处理Mixed消息

混合消息是指其负载中同时包含data和notification键的消息。当接收到此类消息时

• 应用程序处于前台，则使用参数（stringifiedData，fcmNotification）调用notificationCallbackAndroid回调
• 应用程序处于后台，则不会调用notificationCallbackAndroid回调。将通知放入系统托盘。如果点击托盘中的通知，则混合消息中的data部分可在活动的intent的extra中找到，并在NativeScript的相应应用程序事件中可用。

在应用程序resume事件中处理data部分的示例（例如，应用程序从通知被带到前台）

application.on(application.resumeEvent, function(args) {
    if (args.android) {
        var act = args.android;
        var intent = act.getIntent();
        var extras = intent.getExtras();
        if (extras) {
            // for (var key in extras) {
            //     console.log(key + ' -> ' + extras[key]);
            // }
            var msg = extras.get('someKey');
        }
    }
});

notificationCallbackAndroid回调的参数

根据通知事件和有效负载，使用两个参数调用notificationCallbackAndroid回调。

• stringifiedData - 字符串。通知有效负载中data值的JSON表示的字符串化形式。
• fcmNotification - RemoteMessage.Notification。可以按其公共方法访问的RemoteMessage.Notification类的表示。如果回调是从有效负载中包含notification键的消息中调用的，则此参数可用。

设置通知图标和颜色

插件自动处理data对象中的某些键，如message、title、color、smallIcon、largeIcon，并使用它们在托盘上构建通知条目。

在AndroidManifest.xml中的application指令内可以设置自定义默认颜色和图标，用于notification消息

<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />

有关更多信息，请参阅编辑应用程序清单文章。

贡献

我们喜欢PRs！查看贡献指南。如果您想贡献，但不确定从哪里开始 - 查找标记为help wanted的问题。

获取帮助

请，仅使用github issues严格用于报告错误或请求新功能。对于一般问题和支持，请查看Stack Overflow或在我们的NativeScript社区Slack频道中向我们的专家提问。