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:

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

 

About the content

The content is based on payload(JSON form)
The format of the payload is as follows:

NameTypeRequired/OptionalDescription
messageStringRequiredA UTF-8 formatted string that forms the body of the message.
badgeIntegerOptionalThis 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.
soundStringOptionalThe 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.
collapseKeyStringOptionalThe 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.
styleStringOptionalA 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.
iconUrlStringOptionalThe 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.
extrasObjectOptionalCustom 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

PREVIOUS

How to make one binary to suit both Sandbox and Production

NEXT

Native App Upload Process