NativeScript 推送插件

NativeScript 推送插件的代码。

入门
API 参考
故障排除
与 Telerik 后端服务一起使用
使用 Firebase Cloud Messaging 的 Android 配置

入门

创建一个新的 NativeScript 应用程序
```
  tns create MyApp
```
或使用现有的一个。
添加推送插件（从 NPM）。这将把推送插件安装到项目根目录的 node_modules 文件夹中。当添加新平台（或使用现有平台）时，插件也会添加到那里。转到应用程序文件夹，添加推送插件
```
  tns plugin add nativescript-push-notifications
```

Android

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

转到应用程序文件夹，将 Android 平台添加到应用程序
```
  tns platform add android
```
在 app/main-view-model.js 中的 HelloWorldModel() 函数中添加示例代码，以订阅并接收消息（在注册方法的选项中输入您的 Firebase Cloud Messaging Sender ID）

	var pushPlugin = require("nativescript-push-notifications");
	var self = this;
	pushPlugin.register({ senderID: '<ENTER_YOUR_PROJECT_NUMBER>' }, function (data){
		self.set("message", "" + JSON.stringify(data));
	}, function() { });

	pushPlugin.onMessageReceived(function callback(data) {
		self.set("message", "" + JSON.stringify(data));
	});

将您的手机连接到电脑，确保 "adb devices" 命令列出了它，并在手机上运行应用程序
```
  tns run android
```
订阅后，访问令牌将写入控制台和消息区域（查找 ObtainTokenThread 日志记录）。发送通知时，TAP 按钮下面的消息应更改为接收到的消息。

默认情况下，插件将使用 firebase-messaging SDK 的 10.0.1 版本。如果您需要更改版本，可以添加一个项目扩展属性 firebaseMessagingVersion，如下所示

```
// in the root level of /app/App_Resources/Android/app.gradle:

project.ext {
    firebaseMessagingVersion = "+" // OR the version you wish
}
```

iOS

编辑应用程序根目录中的 package.json 文件，将捆绑标识符更改为与您的推送证书匹配的标识符。例如："id": "com.telerik.PushNotificationApp"
转到应用程序文件夹，将 iOS 平台添加到应用程序
```
  tns platform add ios
```
在 app/main-view-model.js 中的 HelloWorldModel() 函数中添加示例代码，以订阅并接收消息（在注册方法的选项中输入您的 google 项目 ID）

	var pushPlugin = require("nativescript-push-notifications");
        var self = this;
        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) {
                self.set("message", "" + JSON.stringify(data));
            }
        };

        pushPlugin.register(iosSettings, function (data) {
            self.set("message", "" + JSON.stringify(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
发送通知

API

	// Get reference to the push plugin module.
	var pushPlugin = require('nativescript-push-notifications');

register - 用于订阅设备以接收推送通知

register(settings, successCallback, errorCallback)


	var settings = {
		// Android settings
		senderID: '<ENTER_YOUR_PROJECT_NUMBER>', // Android: Required setting with the sender/project number
		notificationCallbackAndroid: function(message, pushNotificationObject) { // Android: Callback to invoke when a new push is received.
        	alert(JSON.stringify(message));
        },

		// iOS settings
        badge: true, // Enable setting badge through Push Notification
        sound: true, // Enable playing a sound
        alert: true, // Enable creating a alert

        // Callback to invoke, when a push is received on iOS
        notificationCallbackIOS: function(message) {
        	alert(JSON.stringify(message));
        }
	};


	pushPlugin.register(settings,
		// Success callback
		function(token) {
                        // if we're on android device we have the onMessageReceived function to subscribe
			// for push notifications
			if(pushPlugin.onMessageReceived) {
				pushPlugin.onMessageReceived(settings.notificationCallbackAndroid);
			}

			alert('Device registered successfully');
		},
		// Error Callback
		function(error){
			alert(error.message);
		}
	);

unregister - 用于取消订阅推送通知

unregister(successCallback, errorCallback, settings)


	pushPlugin.unregister(
		// Success callback
		function(){
			alert('Device unregistered successfully');
		},
		// Error Callback
		function(error){
			alert(error.message);
		},

		// The settings from the registration phase
		settings
	);

注册交互式推送通知（iOS >= 8.0） - 为了处理交互式通知，您需要在注册设备时传递额外的设置。在 notificationCallbackIOS 中的消息对象将包含一个具有标识符值的属性。

register(settings, successCallback, errorCallback)


	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){
			// if we're on android device we have the onMessageReceived function to subscribe
			// for push notifications
			if(pushPlugin.onMessageReceived) {
				pushPlugin.onMessageReceived(settings.notificationCallbackAndroid);
			}

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

areNotificationsEnabled - 检查设备的通知是否已启用。返回 true/false。仅适用于 iOS，对于 Android 总是返回 true。

areNotificationsEnabled(callback)


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

onTokenRefresh - Android 仅，订阅令牌刷新事件（用于在 Google 作废旧令牌的情况下获取新令牌）

onTokenRefresh(callback)


	pushPlugin.onTokenRefresh(function(token){
			alert(token);
		});

故障排除

如果应用程序未按预期工作。以下是一些您可以验证的事情

Android

确保 platforms\android 中的 AndroindManifest.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 的 AndroindManifest.xml 包含以下推送通知权限

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

iOS

错误信息“注册错误：未找到有效的 'aps-environment' 权益字符串” - 这表示在 xcodeproject 中证书设置不正确。打开 xcodeproject，修复它们，您甚至可以从 xcode 运行应用程序以验证其设置是否正确。xcode 中的 bundle 标识符应与项目根目录中 package.json 文件中的 "id" 相同。

与 Telerik 后端服务一起使用

为了使用插件与 Telerik Backend Services，请参阅官方示例

Telerik Backend Services NativeScript 推送示例

使用 Firebase Cloud Messaging 的 Android 配置

从版本 0.1.0 开始，Android 的 nativescript-push-notifications 模块依赖于 Firebase Cloud Messaging (FCM) SDK。以下步骤将指导您完成一些额外的步骤，以准备您的 Android 应用程序接收来自 FCM 的推送通知。

添加 FCM SDK

从版本 0.1.1 开始，通过钩子添加了 google-services 插件。对于 0.1.1 版本及以上，您可以跳过此步骤。

- Navigate to the project `platforms/android/` folder and locate the application-level `build.gradle` file
- Add the `google-services` plugin to the list of other dependencies in your app's `build.gradle` file


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

- Add the following line be at the bottom of your `build.gradle` file to enable the Gradle plugin

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

添加 google-services.json 文件

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

将文件放置在应用程序的 App_Resources/Android 文件夹中
获取 FCM 服务器密钥

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

如果您正在使用 Telerik 平台通知服务，请参阅此文章以获取设置此密钥的说明。

在 Android 上接收和处理来自 FCM 的消息

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

插件扩展了 FirebaseMessagingService 并覆盖了其 onMessageReceived 回调。在您的应用程序中，您需要使用 NativeScript 模块的 onMessageReceived(message, data, notification) 方法。

模块中 onMessageReceived 回调的行为遵循 FCM 服务的行怍。

处理数据消息

每次收到 data 通知时，都会调用插件的 onMessageReceived 方法。

当处于后台模式时，根据上面指定的键的值构造通知并将其放置在托盘中。点击通知启动应用程序并调用 onMessageReceived 回调。

处理通知消息

如果应用程序处于前台，则调用具有三个参数（消息、数据、通知）的 onMessageReceived 回调。

如果应用程序处于后台，则在托盘中放置通知。当点击通知时，启动应用程序，但不调用 onMessageReceived 回调。

处理混合消息

混合消息是包含加载中既包含数据又包含通知键的消息。当收到此类消息时

应用程序处于前台，onMessageReceived 回调被调用，参数为（消息、数据）
应用程序处于后台，onMessageReceived 回调不会被调用。一个通知被放置在系统托盘中。如果托盘中的通知被点击，混合消息的数据部分可以在活动的意图的额外部分中找到，并在 NativeScript 的相应应用程序事件中可用。

处理应用程序恢复事件中 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');
        }
    }
});

onMessageReceived 回调的参数

根据通知事件和负载，onMessageReceived 回调会带上最多三个参数。

message - 字符串。通知负载中 data.message 值的字符串表示。
data - 对象。通知负载中 data 值的 JSON 表示。
notification - RemoteMessage.Notification。表示 RemoteMessage.Notification 类，可以按照其公开方法访问。当回调从负载中包含 notification 键的消息调用时，此参数可用。

设置通知图标和颜色

从版本 0.1.0 开始，该模块不再默认添加大图标，因为这强制开发者始终使用大图标，这不是原生行为。

插件自动处理 data 对象中的某些键，如 message、title、color、smallIcon、largeIcon，并使用它们在托盘中构建通知条目。有关这些键的更多信息，请参阅 Telerik 平台通知服务的文档文章。

在 AndroidManifest.xml 中的 application 指令内可以为通知消息设置自定义默认颜色和图标

	<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" />

更多信息请访问编辑应用程序清单文章。

NativeScript 推送插件

入门

Android

iOS

API

故障排除

Android

iOS

与 Telerik 后端服务一起使用

使用 Firebase Cloud Messaging 的 Android 配置

在 Android 上接收和处理来自 FCM 的消息

处理 数据 消息

处理 通知 消息

处理 混合 消息

onMessageReceived 回调的参数

设置通知图标和颜色

处理数据消息

处理通知消息

处理混合消息