How to use Remote Notification
Introduction
Apple remote notification features is the use of APNs(Apple Push Notification service) provided by Apple which implements notification between users and game server to users. The content of the notice will be displayed in the notification bar , the game can also capture the content.
The remote notification features could be used since Mobage ngCore SDK 1.7.
The remote notification features could be set in Developer Portal.
![]() | Attention
|
Setting the APNs in iOS App
APNs Certificate files and provision files are required by Mobage PF. Since DeNA is publisher of iOS games, DeNA will be responsible for providing the files and uploading to Mobage PF.
Usage of Remote Notification Features
The following diagram explains how to implement Remote Notification. You are required to implement the following two parts: 1) sending notifications to devices and servers, and 2) receiving the notifications on devices.
Implements of the sender.
Cases of the sender:
Location | API |
---|---|
User to User | Client API |
User to Game to User | RESTful API |
Game to User | RESTful API |
About the content
The content is based on payload(JSON form)
The format of the payload is as follows:
Name | Type | Required/Optional | Description |
---|---|---|---|
message | String | Required | A UTF-8 formatted string that forms the body of the message. |
badge | Integer | Optional | This number determines the badge used for notifications sent to iOS devices. If no badge is included, no numeric badge is sent. This field has no effect for Android target devices and does not count toward payload size constraints. |
sound | String | Optional | The name of the sound in the application bundle to play for notifications on iOS devices. Plays the default sound when the specified sound file is not found or when the value is default. This field has no effect for Android target devices and does not count toward payload size constraints. |
collapseKey | String | Optional | The collapse key to combine multiple messages on an Android device into a single group, displaying the most recent notification only. When no key is specified, all notifications use the same collapseKey. This field has no effect for iOS target devices and does not count toward payload size constraints. |
style | String | Optional | A hint that contains the preferred layout style for the system notification tray on Android devices. If no style is given or the provided style is not available, the default Mobage style will be used. Â Valid styles are normal and largeIcon. This field has no effect for iOS target devices and does not count toward payload size constraints. |
iconUrl | String | Optional | The icon URL that determines the image shown in the notification bar for Android devices for notification payloads that include a style attribute. If this field is not specified, the default Mobage icon image is shown. This field has no effect for iOS target devices and does not count toward payload size constraints. |
extras | Object | Optional | Custom 1 level hash of key/value parameters defined by the developer. The string key for each item in this section cannot contain any of the payload's defined key values. |
User to User
The implements of remote notification between user and user is as follows:
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 authentication is needed.
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 refers to "userId"。
- payload need to be json format。
Game to User
2-legged OAuth Request(Consumer Request) is needed. The implements are as follows. Messages and installers are allowed to be sent.
Send notification to one user
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
Send notification to all users
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
- Restrictions
- Game can only send one remote notification to a user every 4 hours. It will return error message with "429 Too Many Requests" if exceed the limit.
- Single user and all Users are separated from the limit of 4 hours above. In other words, Every day the game can send 6 notifications to individuals and 6 to all Users, up to a total of 12 a day.
Implements of the reciever.
At first,setRemoteNotificationsEnabled() in Client API must be set true。
ngCore Client API:
Because remote reception of the notification is invalid before processing above, starting the processing when the application is started is recommended.
- Cases of the reciever:
- recieve when the game running
- recieve when the game in the background
- recieve before the game starts
Recieve When the Game Running
Use Device.NotificationEmitter.addListener() to listen to the content of notifications, then it will not display in the notification bar.
Recieve When the Game in the Background
In this case, register of MessageListener above is also necessary.At first, the notification is displayed in the notification bar. The game will switch to front after clicking on the notification. The content will also ba captured by Listener.
Recieve Before the Game Starts
The notification will be displayed in the notification bar. The game will start on clicking on the notification. Use Device.NotificationEmitter.getPendingNotification() to capture the content when starts.
Action when click on the notification
When there are several notifications, the clicked notification will be captured. If notifications are collapsed when display, only the latest notification can be captured, and the previous notifications will be deleted.
References
- Detailed description of the ClientAPI:ngCore ClientAPI
- Detailed description of the RESTful API:RESTful API