How to use the RemoteNotification

Grade 1 users are able to use user to user remote notification function from March 19 2014.

You can only use fixed phrase when using remote notification service.

Introduction

Remote Notification is a service to send notifications between users (User to User), and from game servers to users (Game to User). For Android, it uses C2DM (Cloud to Device Messaging) provided by Google, and for iOS, it uses APNs (Apple Push Notification service) provided by Apple. If an application receives a notification, the messages of the notification are displayed in the notification area on the device. An application can also handle the messages of the received notification in the implementation by using Remote Notification API.

The following SDKs can use Client API of Remote Notification.

Introduction
Configurations on DevSite
How to implement Remote Notification
Regarding devices that receive remote notifications

SDK	Version
Mobage Native SDK	1.3.0.1 or later

Note

Please be aware that there is no guarantee that Remote Notification Service sends notifications to the users successfully.
It is prohibited for the users to edit the contents of notifications. Please let the users select the contents of notifications from fixed phrases in the case of User to User notifications.

Configurations on DevSite

To start using Remote Notification, you are required to configure the Android or iOS Application Settings in "Application details” section on the Developer’s Site. Click the link of "Remote Notification Settings” that appears at the lower left. (the following image).

Configurations for Android (GCM/C2DM Settings)

If you are using any SDK versions before ngCore 1.10, Native/Unity 1.4 and ShellApp 1.0.1, please follow the following instructions.

For Android, select the "GCM/C2DM Settings” tab as described below.

Check "Enable C2DM” and then click "Verify contents”.

When clicking the "Verify contents” button within the "C2DM Settings” section, service status of Google C2DM will change from "Not set" into "enabled", and then the Remote Notification service can be used as shown below.

Configurations for iOS

For iOS, select the "APN Settings" tab as shown below.

You are required to upload SSL certificates for Sandbox and Production. The certificates to upload must be the .pem file format.

For more information on the creation of .pem file, see the below description. Or you can download a PDF document from here.

1. Access the iOS Provisioning Portal in iOS Dev Center.
2. Click "App IDs” on the left-hand menu.
3. If the application is already created, click the "Configure” button of the desired App ID. To create a new application entry, click on "New App ID” on the upper right and create the new App ID. (For more information on creation of App IDs, see Upload to iTunesConnect.)
4. Check "Enable for Apple Push Notification service” in the middle of the screen.
5. For Sandbox, click the "Configure” button of the Development Push SSL Certificate. For Production, click the "Configure” button of the Production Push SSL Certificate. After clicking "Configure” button, the Apple Push Notification service SSL Certificate Assistant is activated.
6. Activate Keychain Access and create CertificateSigningRequest.certSignningRequest as described below.
　　a. From top of the menu bar, click "Keychain Access” > ”Certificate Assistant” >”Request Certification to Certificate Authority”
　　b. Enter "User email address ” and ”Nickname”, choose ”Save to Disk” on "Process of Request” and then click "Continue.” (For a CA email address, you can leave the checkbox empty next to CRS.)
　　c. Choose the desired location and click "Save” to save the CertificateSigningRequest.certSignningRequest
7. Return to the "Apple Push Notification service SSL Certificate Assistant” and click the "Continue” button.
8. You will be transferred to the "Submit Certificate Signing Request” screen. Click the "File Selection” button to choose the "CertificateSigningRequest.certSignningRequest” file that was created.
9. A message "Your APNs SSL Certificate has been generated” will be displayed. Click the "Continue” button.
10. Click the "Download” button to download the Certificate. After the download has finished, click the "Done” button on the bottom right. Make sure the Push SSL Certificate Status has switched to "Enabled.”
11. Double click on the downloaded Certificate to register it to the Keychain.
12. From pane at the bottom left of Keychain Access, select "Type” and the registered "Apple Development IOS Push Services.” From the menu bar, select "File” > "Write” and save the "Personal Information Exchange File (p12)” to the desired location. Optional password settings are necessary when writing the file.
13. From terminal, convert "Personal Information Exchange File (p12)” into .pem file using the following command.

The SSL Certificate (.pem file) created by the above processes can be uploaded from the buttons on the APN Settings Tab. Upload a Development Push SSL Certificate for Sandbox, and a Production Push SSL Certificate for Production.

After uploading the certificates, the effective period is displayed as below, and the “Input Confirmation” button is activated. The status of Apple Push Notification service will change to “Disabled”.

In order to use the iOS Remote Notification Service, set the utilization situation to “Enabled”, and click the “Verify contents” button.

If you just want to test remote notification, there is no need to have the CFBundleIdentifier and SSL certificate (.pem) to be associated as setup in Mobage Developers Japan. The remote notification will work if the SSL certificate and the signed provisioning file are associated.

Notice that incase of both Production and Sandbox SSL certificate (.pem) are expired, you won't be able to send remote notification. In this case you are able to send remote notification again if you renew the SSL certificate uploaded.

How to implement Remote Notification

Summary

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.

Implementation to send notifications

Remote Notification Service has the two location types: "User to User" and "Game to User". In addition, Remote Notification API can be classified by the two caller types: Client API (called from application) and RESTful API (called from Game Server).

The all possible combinations of Remote Notification features are summarized as the following table.

Location	API
User to User	Client API or RESTful API
Game to User	RESTful API

For more details on RESTful API, please refer to this page.

The data types of Remote Notification

The contents of Remote Notification can be specified by payload (JSON format). The payload format is described in the below table. All content within payload can be received by using receiving API.

Name	Type	Required	Description
message	String	Required	The contents of Remote Notification message (UTF-8 only). This message can be displayed in the notification area on devices.
badge	Integer	Optional	(iOS only) This value is used as an icon badge in receiver applications. If it is not specified, Client API will not send any value. In the case of Android, this feature is ignored.
sound	String	Optional	(iOS only) If this value is specified, receiver applications will play warning sounds. The “sound” value must be the name of the audio file included in applications. If the file does not exist, then they will play the default warning sound as well as "default" is specified. In the case of Android, this feature is ignored (they play no sound).
collapseKey	String	Optional	(Android only) An arbitrary key string that collapses a group of similar notifications except the last notification when the device is offline. Note that there is no guarantee of the order of Remote Notification. In other words, the "last notification" may be different from the actual last notification sent by the senders. If this feature is not specified, RemoteNotification.id, which is a unique id, will be specified as "collapseKey". In the case of iOS, this feature is ignored.
style	String	Optional	(Android only) This feature specifies the style of the notification area. Valid styles are “normal” and “largeIcon”. If the style is not specified or invalid, then the default style will be specified. In the case of iOS, this feature is ignored.
iconUrl	String	Optional	(Android only) If both "style" and "iconUrl“ are specified, this value will be used for specifying the icon image displayed in the notification area on the device. In the case of iOS, this feature is ignored.
extras	Object	Optional	You can set any associative array with depth = 1 as key-value pairs. e.g.: { "foo" : 1, "bar" : "twenty one" }

Implementation of User to User notifications

You can implement “User to User” Remote Notification as below.

For the “recipientId”, specify the recipient’s UserId.
For the “payload”, specify the contents of the notification in “JSON” format.

Native iOS Client API :

Native Android Client API :

RESTful API: “3-legged authentication" is required. POST the following data from the Game Server to the following endpoint.

For more details on RESTful API, please refer to this page.

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

Implementation of Game to User notifications

In the case of "Game to User", you are required to send Consumer Request (2-legged OAuth Request). In this case, a game server can send the notifications of two types: a notification to a particular user, and simultaneous notifications to the all users who installed the application.

For more details on RESTful API, please refer to this page.

Notification to a particular 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

Notifications to the 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
- In the case of “Game to All Users”, you can only send a set of notifications once every one hours. If you have exceeded this limit, you will receive the error status “429 Too Many Requests.”

Implementation to receive notifications

Initialization of Remote Notification receiver

In order to receive Remote Notification, the receiver application is required to perform the following initialization processes.

Native iOS Client API :
- Add the following processes into AppDelegate.mm.

Native Android Client API :
- Add the following flag field to the main Activity class.
- Add the following processes into onCreate() in the main Activity.
- The main activity class is required to override onNewIntent(), and then to call handleIntent() as the followings.
- Override handleIntent() in the main activity class as the followings. In the case that the application is not active and alive in background, tapping the messages displayed in the notification area will trigger a call of the following method.
- The image file "drawable/icon.png" is required to exist, because the image will be displayed in the notification area.
- The following descriptions are required to be added within the <application> tag in the AndroidManifest.xml.
- The following descriptions are required to be added within the <application> tag in the AndroidManifest.xml.
- Specify the "launchmode" depending on the SDK version you are using, for the main Activity within the <application> tag in the AndroidManifest.xml.
  
  Mobage Native SDK older than 1.4
  
  android:launchMode="singleTask"
  
  Mobage Native SDK 1.4 or later
  
  android:launchMode="standard"
  OR
  android:launchMode="singleTop"
  
  Configuration to enable Remote Notification receiver
  In order to enable Remote Notification receiver, the “setRemoteNotificationsEnabled()” of Client API must be set to “true”. The method setRemoteNotificationsEnabled() should be called after login process.

Native iOS Client API :
Native Android Client API :

The receiver APIs of Remote Notification don't work while the above “setRemoteNotificationsEnabled()” is not complete.
Therefore, calling the API just after launching the application is preferred. You can check whether the application is enabled to receive notifications or not by using “getRemoteNotificationsEnabled().”

Behavior of Remote Notification receiver

Remote Notification receiver changes its behaviors depending on the status of the application. The following is the all possible cases.

The case that an application running in the foreground receives a notification
The case that an application running in the background receives a notification
The case that an application, which is not running, receives a notification

Native iOS Client API

Running in foreground

The messages of the notification will be emitted into didReceiveRemoteNotification. The contents won't be shown in the OS notification area. In this case, UIApplicationState will be UIApplicationStateActive.

Running in background

The contents will be displayed in the notification area on the device. If tapping the messages displayed in the notification area, the application will be in foreground, and the contents of the notification will be emitted into didReceiveRemoteNotification. In this case, UIApplicationState will be UIApplicationStateInactive.

Not running

The contents will be displayed in the notification area on the device. Tapping the messages will launch the application. The contents of the notification can be received by performing the following code that is required to be added into didFinishLaunchWithOptions in AppDelegate.mm.

Native Android Client API

Running in foreground

The contents of the notification will be emitted into RemoteNotificationListener#handleReceive() that is set by calling RemoteNotification.setListener(). Calling RemoteNotification.displayStatusBarNotification() will display the messages in the OS notification area. If you don't call this method, the behavior will be as well as that of ngCore SDK and Native iOS. This behavior can be implemented as follows.

Add a member isPaused as a flag in the main Activity.
Add the following code in onPause() and onResume().
If and only if isPaused is true, then call RemoteNotification.displayStatusBarNotification().

Running in background

The contents will be emitted into RemoteNotificationListener#handleReceive() as well as in the case of foreground. In order to display the messages in the notification area, call RemoteNotification.displayStatusBarNotification(). This is also as well as the previous case. Tapping the messages in the notification area will make the application be in foreground.

Not running

When the application is not running, the messages are always displayed in the notification area. Tapping the messages in the notification area will launch the application.
The contents of the notification will be received in handleIntent() implemented in the receiver when the application is launched.

Sound and vibration for Native Android(Mobage Native SDK 1.4.7 or later)

By customising the tweakNotification method on RemoteNotificationClient class as below, you can use sound or vibration.

The RemoteNotificationClient class has handleRegistration、handleMessage、tweakNotification which you can use to handle on specific event.

Sound and vibration for Unity Android(Mobage Unity SDK 1.4.7 or later)

See "samples/RemoteNotificationClient/README.txt" on Mobage Unity 1.4.7 or later package for more details. You can customize the remote notification.

Note for Native / Unity Android when using iconUrl or style=largeIcon

When you use Mobage Native / Unity SDK for Android in combination with iconUrl or style=largeIcon in payload, beware the followings.

The device to receive notifications is required to be Android 2.3 or later.
- If the device is Android 2.2 or earlier, the default drawable/icon.png file is used for iconUrl. The specification style=largeIcon will be ignored.
Project Target API Level is required to be over 10.
- android:minSdkVersion is required to be over 10.
If you use either iconUrl or style=largeIcon, some models may have a problem on displaying the contents.
drawable/icon.png is required.
In the case of Mobage Native SDK
- You are required to copy MobageNativeAndroid/res_rn_v9/layout-v9 folder in the SDK package into under the res folder in the Eclipse project.
In the case of Mobage Unity SDK
- You are required to copy MobageNativeAndroid/res_rn_v9/layout-v9 in the SDK package into under the Plugins/res folder in the Unity project.

If you want to use iconUrl or style=largeIcon, we recommend to develop your application in "Project Target API Level 8 or under", and just before releasing the application, copy MobageNativeAndroid/res_rn_v9/layout-v9 into res folder.

If you set Project Target API Level into under 8 and copy MobageNativeAndroid/res_rn_v9/layout-v9 into under res folder, then it will cause a build error.

Regarding devices that receive remote notifications

Remote notifications are sent to devices based on the following rules:

On logging in to Mobage, the user’s Mobage UserId and the device’s DeviceId are linked, and it becomes possible to send remote notifications to the device.
On logging out of Mobage, the information linking the UserId and DeviceId is deleted, and it therefore becomes impossible to send remote notifications to the device.
When a user logs in with the same UserId on multiple devices, remote notifications are only sent to the last device the application was used. If the user logs out from an Android device, remote notifications will no longer be sent to their Android devices. Likewise, if the user logs out from an iOS device, remote notifications will not be sent to their iOS devices.

Reference

For more details on RESTful API, please refer to this page.

Revision History

09/12/2014
- Added reference for remote notification customization for Mobage SDK 1.4.7 or later
03/19/2014
- Grade 1 users are able to use user to user remote notification.
11/14/2013
- Added about GCM
11/13/2013
- Modified AndroidManifest launchMode for Unity
05/09/2013
- Added description for the main activity launch mode due to difference per SDK.
04/17/2013
- Added description for Android Manifest when using Mobage Unity SDK
01/07/2013
- Added "Regarding devices that receive remote notifications”
09/04/2012
- Update with the latest information.
07/06/2012
- Additions made with remote notification function now available for Mobage Unity SDK 1.3.
- Revision for clarity.
07/05/2012
- Latest available version revised to Mobage Native SDK 1.3.0.1.
- Added: setRemoteNotificationsEnabled to be called after login.
- Revised:About the recipient side for Mobage Native SDK.
06/27/2012
- Additions made with remote notification function now available for Mobage Native SDK 1.3.
06/13/2012
- Additions made with remote notification function now available for Mobage ngCore Android production environment.
05/30/2012
- Modify step12 in creation of .pem file
04/25/2012
- C2DM Settings flow has been changed from "Not set" to "enabled" directly
04/12/2012
- Add re-sign tool for Remote Notification
04/11/2012
- Initial Release.

Mobage Native SDK older than 1.4	android:launchMode="singleTask"
Mobage Native SDK 1.4 or later	android:launchMode="standard" OR android:launchMode="singleTop"

How to use the RemoteNotification

Introduction

Note

Configurations on DevSite

Configurations for Android (GCM/C2DM Settings)

Configurations for iOS

How to implement Remote Notification

Summary

Implementation to send notifications

The data types of Remote Notification

Implementation of User to User notifications

Implementation of Game to User notifications

Implementation to receive notifications

Initialization of Remote Notification receiver

Configuration to enable Remote Notification receiver

Behavior of Remote Notification receiver

Native iOS Client API

Running in foreground

Running in background

Not running

Native Android Client API

Running in foreground

Running in background

Not running

Sound and vibration for Native Android(Mobage Native SDK 1.4.7 or later)

Sound and vibration for Unity Android(Mobage Unity SDK 1.4.7 or later)

Note for Native / Unity Android when using iconUrl or style=largeIcon

Regarding devices that receive remote notifications

Reference

Revision History