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 中的捆绑标识符应与项目根目录中 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 Platform 通知服务，请参阅此文章了解如何设置此密钥的说明。

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

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

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

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

处理数据消息

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

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

处理通知消息

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

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

处理混合消息

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

应用程序处于前台，将调用 onMessageReceived 回调并带有参数（消息，数据）
应用程序处于后台，不会调用 onMessageReceived 回调。在系统托盘放置通知。如果托盘中的通知被点击，混合消息的数据部分可在活动的 intent 的 extras 中找到，并在 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');
        }
    }
});

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指令内设置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" />

更多详情请访问编辑应用清单文章。

NativeScript 推送插件

入门指南

Android

iOS

API

故障排除

Android

iOS

与 Telerik 后端服务一起使用

使用 Firebase Cloud Messaging 的 Android 配置

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

处理 数据 消息

处理 通知 消息

处理 混合 消息

onMessageReceived回调函数的参数

设置通知图标和颜色

处理数据消息

处理通知消息

处理混合消息