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

Remote notification couldn't guarantee to be able to send notification to the user.
Users are forbidden to input or edit the content. So the content of notification between users must be a fixed text.
Android Push Notification service for Mobage Simplified Chinese Platform is made by Mobage itself. Due to limited capacity，the service is temporarily closed for new apps。
Mobage Traditional Chinese Platform does not support Android Remote Notification temporarily。

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

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.

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