メインコンテンツまでスキップ

如何使用远程推送

简介​

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平台提供证书等信息.

远程通知功能的使用方法​

概念图如下。在下图中,您需要实现的部分是:由终端或服务器发送信息的部分①,接收终端上的部分②。

 

远程通知的发送方的实现。​

发送方存在以下执行情况:

LocationAPI
User to UserClient API
User to Game to UserRESTful API
Game to UserRESTful API

关于发送的内容​

远程通知的送信内容是以payload(JSON形式)制定的。
Payload的格式如下:

name类型必须/可选说明
messageStringRequired远程通知的内容,出现在通知栏,使用UTF-8编码。
badgeIntegerOptionaliOS终端的远程通信下,badge的数值用于显示在图标的右上角。如果没有指定badge将不会发送特定的数字。Android终端下,badge的值没有作用。
soundStringOptionaliOS终端的远程通信下,用作接收方的提示音。sound是包含在应用程序下的音频文件。音频文件不存在时,如果指定了"default"值,则使用默认的提示音。Android终端下,指定的声音不会生效。
collapseKeyStringOptional信息送到Android终端的情况下,如果终端处于离线状态,只有最后的消息被送达。在Android终端上折叠显示通知。但是,远程通信的通知顺序无法保证,并且,collapseKey指定时,重复的通知将只保存最后的通知。iOS终端的情况下,collapseKey会被忽略。
styleStringOptionalAndroid终端的情况下,标示消息在通知区域的风格。未设定风格或者风格无法使用时,使用默认的风格。有效的风格为"normal"和"largeIcon"。iOS终端的情况下,将会被忽略。
iconUrlStringOptionalAndroid终端的情况下,如果style被指定,则iconUrl用于确认适用于通知区域的图标。iOS终端的情况下,iconUrl被忽略。
extrasObjectOptional设定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()来取得通知内容。

点击通知栏的通知时的动作​

当游戏有多个通知时,被点击的通知会被捕捉。当通知栏的通知被折叠显示时,此时点击后,只能获取到最新的一条通知。其他旧通知会被删除,无法获取。

参考资料​