Remote Notification
Endpoint for Social API
Note: Social API includes Appdata API, Blacklist API, People API, Profanity API, Leaderboard API, Remote Notification API.
Mobage Simplified Chinese Platform
| Production Social | http://sp.mobage-platform.cn/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.cn/social/api/restful/v2 |
Environment | URL |
|---|
Mobage Traditional Chinese Platform
Environment | URL |
|---|---|
| Production Social | http://sp.mobage-platform.tw/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.tw/social/api/restful/v2 |
Data Type Definition
RemoteNofication
| Name | Type | Required/Optional | Description |
|---|---|---|---|
| recipientId | UserId | Required | User identifier for the notification recipient. This identifier can be a gamertag or a user ID. |
| payload | Object | Required | Additional parameters passed to the device. |
| payload.message | String | Required | A UTF-8 formatted string that forms the body of the message. |
| payload.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. |
| payload.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. |
| payload.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. |
| payload.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. |
| payload.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. |
| payload.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. |
Description
Sends a remote notification, also called a push message, to a user's device. Â This API can send a message to a single user or a broadcast message to all users of a given app.
On the Android platform, remote notifications are delivered through the Android Google Cloud Messaging (GCM) infrastructure. On the iOS platform, remote notifications are delivered through Apple's Push Notification Service (APNS). When your app is ready to publish, and you submit it for review, the Mobage platform team automatically enables remote notifications for your app.
Examples of legitimate notifications using the Mobage Push Notifications API include:
- Inviting a user to the current app.
- Sending notifications announcing asynchronous app events.
- Announcing a user-initiated app invitation or challenge.
- Notifications promoting app features that a user has not yet explicitly engaged.
Examples of notifications that are not compliant with Mobage platform policies include:
- Notifications promoting other apps.
- Notifications generated on behalf of a user that are not explicitly approved by the user.
The Mobage platform team monitors the remote notifications sent from your app to make sure that in-app events written to the Mobage Remote Notification API comply with Mobage platform policies.
URI Fragment
/remote_notification/{appId}/@all/{recipientId}
/remote_notification/{appId}/@all
Supported Formats
JSON
HTTP Method
POST
Request Parameters
| Name | Type | Required/Optional | Parameter Type | Description |
|---|---|---|---|---|
recipientId | UserId | Required | URI Template Variable | The recipient's userId |
| appId | AppId | Required | URI Template Variable | @app or direct value |
Request Headers
Any request to the Mobage REST APIs must include the Authorization header. For more details, see How to add the Authorization Header .
Request Body
| Name | Type | Required/Optional | Description |
|---|---|---|---|
| senderId | UserId | Required | The sender's userId |
| payload | RemoteNotification | Required | The POST data payload for this remote notification |
Response Body
Response Status Code
| HTTP Status Codes | HTTP Status Message | Meaning |
|---|---|---|
| 200 | OK | Data successfully acquired |
| 400 | Bad Request | Corrupt request data on the client side |
| 401 | Unauthorized | Authorization error |
| 403 | Forbidden | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 429 | Too Many Requests | The number of leaderboard requests exceeds the throttling limit. |
| 500 | Internal Server Error | An error on the API server side |
| 503 | Service Unavailable | The API cannot be used temporarily |
Notes
- The delivery of remote notifications is not guaranteed.
- The API limits broadcast messages to 1 broadcast every 1 hours. Messages from one user to another are not throttled.
- Only a game server can send a broadcast remote notification to all users (@all). You must use game-server specific consumer secret tokens and keys to authenticate this request. Client OAuth sessions are not valid for the purpose of sending @all remote notifications.
Example 1. Sending a Remote Notification to a Single User
Example 2. Sending a Broadcast Notification to All Users
Example 3. Sending a Broadcast Notification to Multiple Users (Max:1000 users one time)
How to Add the Authorization Header
Step 1. Create the base string
1. build a string for OAuth parameters: firstly sort the following parameters alphabetically and URL encode the names and values, then join name and value with "=", finally join name/value pairs with "&"
| Parameter | Description | Value |
|---|---|---|
oauth_consumer_key | The Consumer Key for the application | Issued when resist the application |
oauth_nonce | Unique value for each request | Generated on the game server |
oauth_signature_method | Hash method | Only HMAC-SHA1 is specifiable |
oauth_timestamp | UNIX timestamp | Generated on the game server |
oauth_token | The token code | oauth_token is obtained from the token credential. |
oauth_version | OAuth version | Only 1.0 |
2. URL encode the following three parameters.
| Parameter | Description |
|---|---|
| Request Method | HTTP Method to the API Server |
| API URL | URL to the API Server (exclude query parameters) |
| OAuth Parameters | A string Built in previous step |
3. join the encoded parameters with "&".
Step 2. Generate the oauth_signature
1. Build a secret by joining the Consumer Secret and the Token Secret (obtained from the token credential) with "&".
2. Pass the base string and secret to the HMAC-SHA1 hashing algorithm.
3. the output of HMAC-SHA1 hashing algorithm is a binary string. Use base64 encode to produce the signature string.
A tool is provided to verify whether your signature is correct. Refer to Oauth Signature Tool.
Step 3. Build the Authorization Header
Follow the steps to build the “Authorization” header:
1. URL encode the parameter names and values in the table below
2. Double quote the value, join name and value with "=", join name/value pairs with ","
3. Add realm parameter as an option
4. Add "OAuth " (including the space at the end) to the beginning of the header.
| Parameter | Value |
|---|---|
| oauth_consumer_key | Issued when resist the application |
| oauth_nonce | Generated on the game server |
| oauth_signature | Generated on the game server, Refer to Step 2. Generate the oauth_signature |
| oauth_signature_method | only "HMAC-SHA1" is specifiable |
| oauth_timestamp | Generated on the game server |
| oauth_token | oauth_token is obtained from the token credential. |
| oauth_version | Only 1.0 |
Authorization Header Example