如何使用远程推送
简介
Apple远程通知功能是指利用Apple提供的APNs(Apple Push Notification service),实现用户之间的通知以及游戏服务器到用户的通知。通知的内容会显示在手机的通知栏内,并且游戏也可以捕获通知栏中的通知内容。
Mobage ngCore SDK 1.7开始可以使用远程通知功能。
在Developer Portal,可以设定iOS应用程序的远程通知设定。
注意事项
- 远程通知无法保证一定能够把通知发送给用户。
- 远程通知的内容禁止让用户自行输入和编辑。因此用户到用户的通知内容必须用固定的文本构成。
- Mobage简体平台的Android Push Notification使用的是Mobage自制的Service,由于系统容量有限,暂时停止为新的应用提供Android Remote Notification服务。
- Mobage繁体平台暂时不支持Android Remote Notification。
iOS应用远程通知的设定方法
Mobage平台需要APNs的证书等信息.由于目前所有游戏由Mobage代理发行至苹果,所以将由Mobage平台提供证书等信息.
远程通知功能的使用方法
概念图如下。在下图中,您需要实现的部分是:由终端或服务器发送信息的部分①,接收终端上的部分②。

远程通知的发送方的实现。
发送方存在以下执行情况:
| Location | API |
|---|---|
| User to User | Client API |
| User to Game to User | RESTful API |
| Game to User | RESTful API |
关于发送的内容
远程通知的送信内容是以payload(JSON形式)制定的。
Payload的格式如下:
| name | 类型 | 必须/可选 | 说明 |
|---|---|---|---|
| message | String | Required | 远程通知的内容,出现在通知栏,使用UTF-8编码。 |
| badge | Integer | Optional | iOS终端的远程通信下,badge的数值用于显示在图标的右上角。如果没有指定badge将不会发送特定的数字。Android终端下,badge的值没有作用。 |
| sound | String | Optional | iOS终端的远程通信下,用作接收方的提示音。sound是包含在应用程序下的音频文件。音频文件不存在时,如果指定了"default"值,则使用默认的提示音。Android终端下,指定的声音不会生效。 |
| collapseKey | String | Optional | 信息送到Android终端的情况下,如果终端处于离线状态,只有最后的消息被送达。在Android终端上折叠显示通知。但是,远程通信的通知顺序无法保证,并且,collapseKey指定时,重复的通知将只保存最后的通知。iOS终端的情况下,collapseKey会被忽略。 |
| style | String | Optional | Android终端的情况下,标示消息在通知区域的风格。未设定风格或者风格无法使用时,使用默认的风格。有效的风格为"normal"和"largeIcon"。iOS终端的情况下,将会被忽略。 |
| iconUrl | String | Optional | Android终端的情况下,如果style被指定,则iconUrl用于确认适用于通知区域的图标。iOS终端的情况下,iconUrl被忽略。 |
| extras | Object | Optional | 设定Key/Value的形式。如:{"foo":1,"bar":"twenty one!"} |
用户到用户的通知发送方法说明
用户到用户的远程通知的发送如下:
ngCore Client API:
var recipientId = 10028;
var payload = {
"message": "Simon! Come join my quest.",
"extras": {
"foo": 1,
"bar": "twenty one!"
}
};
Social.Common.RemoteNotification.send(recipientId, payload, function(error, remoteNotification) {
if (error) {
/* error handling code is here */
} else {
/* successful queueing of the remote notification */
}
});
RESTful API:使用前必须进行3-legged认证
POST /social/api/restful/v2/remote_notification/@app/@all/{recipientId}
POST /social/api/restful/v2/remote_notification/@app/@all/10258
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="b9a19f5ceac92a7b99b7", oauth_signature="yY0IRUStlDYw1qcyPuz8fsD%2BIrs%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798387", oauth_token="sp_client_id%3A58cee178e5ea60732d2b6fae0294da9d", oauth_version="1.0"
{
"payload" : {
"message": "Simon! Come join my quest.",
"extras": {
"foo": 1,
"bar": "twenty one!"
}
}
}
201 Created
- recipientId指userId。
- payload需要json格式。
游戏到用户的通知发送方法说明
使用前必须进行2-legged的OAuth Request(Consumer Request)。具体实现如下。向用户发送消息和安装程序都是可以的。
向用户发送消息
POST /social/api/restful/v2/remote_notification/@app/@all/{recipientId}
POST /social/api/restful/v2/remote_notification/@app/@all/10258
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="5f5ae6a5688795cab25d", oauth_signature="tuLm4o%2FvwzdQK%2FuWAGii9ab3ZiI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798463", oauth_version="1.0"
{
"payload" : {
"message": "Simon! Come join my quest.",
"extras": {
"foo": 1,
"bar": "twenty one!"
}
}
}
201 Created
向全体用户发送消息
POST /social/api/restful/v2/remote_notification/@app/@all
POST /social/api/restful/v2/remote_notification/@app/@all
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c11bc5", oauth_nonce="5f5ae6a5688795cab25d", oauth_signature="tuLm4o%2FvwzdQK%2FuWAGii9ab3ZiI%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798463", oauth_version="1.0"
{
"payload" : {
"message": "Simon! Come join my quest.",
"extras": {
"foo": 1,
"bar": "twenty one!"
}
}
}
202 Accepted
限制事项* 游戏到用户的场合,每四小时只能发送1次远程通知。如果超过了限制,会返回429 Too Many Requests的错误。
- 关于上述4小时的限制,User个人和全体User是分开的。换句话说,从游戏向个人每天可以发送6条,向全体User每天可以发送6条,总计可以每天发送12条。
远程通知的接收方的实现
首先,Client API的setRemoteNotificationsEnabled()必须设置为true。
ngCore Client API:
Social.Common.RemoteNotification.setRemoteNotificationsEnabled(true, function(error) {
if (error) {
/* An error occurred in setting this value */
} else {
/* flag was set properly */
}
});
由于在以上的处理之前,远程通知的接收是无效的,因此推荐应用启动时就执行以上处理。
接收方的情况有以下几种:* 游戏进行中接收到通知
-
游戏在后台时接收到通知
-
游戏还没有启动时接收到通知
-
接下去分别介绍以上几种情况。
游戏进行中接收到通知
使用Device.NotificationEmitter.addListener(),可以直接监听到通知内容,就不会反映到操作系统的通知栏中去了。
gListener = new Core.MessageListener();
gListener.onEmit = function(notification) {
console.log(JSON.stringify(notification));
};
Device.NotificationEmitter.addListener(gListener, gListener.onEmit);
游戏在后台时接收到通知
这种场合,也需要注册如上的MessageListener。首先,通知会显示在操作系统的通知栏上。点击通知后,游戏会切回到前台,通知的内容会被Listener捕获。
游戏还没有启动时接收到通知
通知栏会显示通知,点击通知后会启动游戏。启动的时候,通过执行Device.NotificationEmitter.getPendingNotification()来取得通知内容。
点击通知栏的通知时的动作
当游戏有多个通知时,被点击的通知会被捕捉。当通知栏的通知被折叠显示时,此时点击后,只能获取到最新的一条通知。其他旧通知会被删除,无法获取。
参考资料
- ngCore的ClientAPI的详细请参见:ngCore API
- RESTful API的详细参见:RESTful API