Skip to content

Single Push

Prerequisites

To sync with the Single Push API, make sure to issue an authorization token (API KEY). If you already have the key, request the additional permissions. Refer to Hive Server API > Notification > Push v4 > Authentication to check how to request and issue the authorization token.

Note

Single Puch API is asynchronous and processes as in sequence, API Request > Token Lookup > Send.

  • API Request: verifies request data and returns the response code to the request.
  • Token Lookup: looks up the push token to the request data. There might be situationswhere there is no token.
  • Send: transfers the data to the push servers of each market (such as ADM, APNS, FCM). The response received from markets shows the processing result.
  • When the processing fails in the token lookup and send steps, no response transfers to the client that called the push server. If you don't get a push in 10 minutes since you sent the data, please reach out to the Solution Architect team, Com2uS Platform.

Access URLs by environment

Server URL
Production https://notification.withhive.com
Sandbox https://sandbox-notification.withhive.com

Basic information and request parameters

Method POST
URL /push/send
Section Field name Description Type Required
Header Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
Body notice Whether to set as notification alert (default: false)

    true

  • Sent as a notification alert
  • Sent depending on recipient's consent

    • false

  • Sent as a game alert
  • Sent regardless of recipient's consent

    • Consent items include notification alert and night alert
  • If the recipient does not consent to notification alerts, all alerts set as notifications will not be sent
  • Night alert consent applies only if notification alert consent is given, so if not consented, all notification alerts set as notifications will not be sent at night. Night is defined as 9 PM to 8 AM the next day.
Boolean O
identifiers Identifier information (up to 100) identifier structure and example can be found below identifier[] O
game gameid Game ID String O
appids List of AppIDs
If the AppID mapped to the identifier is invalid, it will not be sent

Recommendations

  • For device-based identifiers (did): add the mapped AppID
  • For account-based identifiers (playerId): add all mapped AppIDs
  • If various identifiers exist: check the priority in Identifier structure
String[] X
enableLocale Whether to apply language locale

    true

  • Sends the message in the same language as set by the push recipient. Based on the language code saved with the token information
  • Criteria for determining language when saving token
  • 1st: game language
  • 2nd: device language (if no game language provided)

    • false

  • Ignores language locale and sends only via the single value in payload
Boolean O
payload single If enableLocale=false, request with the single field. Message structure is below. Message O
defaultLanguage If enableLocale=true, set as the default language String
locale {{LANGUAGE}} If enableLocale=true, set via the locale field. Same as Message info in single field Message
option Option info is below Option X
actionInfo android ActionPayload info is below ActionPayload X
ios ActionPayload info is below ActionPayload X
Note
  • For smooth single push reception, it is recommended to input only one data item for the appids and identifiers fields.
  • If multiple identifiers or appids are included in the request, it may cause delays in push delivery because the search conditions cannot be specified.
  • It is recommended to specify the identifier value with the highest priority, and avoid configuring the identifier with only the did value.
  • Avoid requests where only gameid is specified in the game field.
  • If there is no data in the appids field, all appids included in the gameid will be searched, which may cause delays in push delivery.

Identifier structure

Section Field name Description Type Required
identifier identifier At least one of the two must be included
Priority: playerId, then did		 Long O
playerId
did

Identifier example

    [
        {
            "playerId":51234,
            "did":1234
        }
    ]

Message structure

Section Field name Description Type Required
Message android title Title String O
message Body String O
messageExpanded Expanded body String O
imageUrl Image URL String X
ticker Ticker String X
summaryText Summary String X
ios title Title String O
message Body String O
mediaUrl Image URL String X

Option info

Section Field name Description Type Required
Option badge Number displayed on the app icon when receiving a push (default: 1) Integer X
overwrite Whether to use Android push overwrite feature (default: false) Boolean X
collapseKey Key value when using push overwrite (string of numbers: "123") String X
engagement User engagement String X
comment Comment String X
groupKey Group key for grouping notifications on iOS and Android devices. For more details, see the documents below. String X
android icon Icon image file name displayed when a push notification appears on the user's device. The image file must exist in /src/main/res/drawable. For supported image file formats, see here. To display an image from the web, enter the image URL in this field instead of the file name. If this field is empty, the app icon image will be displayed. String X
sound Name of the sound file to play when a push notification appears on the user's device. The sound file must exist in /src/main/res/raw. If this field is empty, the system default sound is used. String X
priority Priority of the message sent to Android devices. This controls the delivery timing as per FCM. Can be NORMAL or HIGH, default is NORMAL. For more details, see the Firebase guide.
  • NORMAL = Default priority for data messages. Usually delivered immediately when the device is not in Doze mode. May be delayed to save battery if the device is sleeping. Use for messages where timing is not critical.
  • HIGH = FCM tries to deliver immediately, may wake the device from Doze mode. Use for messages that require user interaction.
 enum(NORMAL, HIGH) X
ios sound Name of the sound file to play when a push notification appears on the user's device. The sound file must exist in the app container's Library/Sounds or main bundle. If empty, "default" is used and the system default sound is played. String X

ActionPayload

ActionPayload is the data format delivered when using the push action button, an additional feature of the single push API.

The push action button is a notification feature available in the SDK, displayed as system buttons when long-pressing a push notification.

For more details about push action buttons, see the guides below.

Warning

Please note the following when using push action buttons:

  • Only available on SDK Android & iOS 4.25.5.0 or higher.
  • Only one identifier is valid in the identifiers field, and playerId is required.
  • The developer is responsible for security validation of URLs called by push action buttons.

ActionPayload data structure

When requesting the single push API, the data included in ActionPayload is as follows.

Field name Description Type Required
category Category identifier for the push action button set, used to identify the set. Hive SDK provides a default push action button set. See default push action button set
For more details on category, see the Apple developer site.
iOS: required, Android: optional and ignored		 String O iOS
X Android
actions List of system buttons to display in the push notification
(Android: up to 3 / iOS: depends on push action button set)
See Action info below		 Action[] O

Action

Action is the data for each system button in ActionPayload. The parameters included in Action are as follows.

Field name Description Type Required
actionId Action identifier for the push action button set, used to identify the system button in the push notification.
For more details, see the Apple developer guide.
iOS: required, Android: optional and ignored		 String O iOS
X Android
titles Button multilingual text, applied according to the enableLocale parameter. If a valid language code is not found, default is used.
key = language code, default key is required, value = button name
If the button name is too long, it may be truncated. Please set an appropriate length.
Android only		 Map O Android
X iOS
actionType Action type (CURL, CLOSE) default: CLOSE
CURL executes a URL call with the value of the action field.
CLOSE closes the push.		 enum(CURL, CLOSE) O
action Action to execute according to the action type
e.g., https://....
Required if actionType is CURL.		 String X

Output > response parameter structure

Section Field name Description
Header Content-Type application/json;charset=utf-8
UUID {{UUID}}
Body - Empty if successful

Response status codes

Key Value Description
200 Success (Body is empty)
400 Bad Request Missing POST data, JSON format error, required element missing or invalid
401 Unauthorized Authorization header missing or invalid, API KEY not registered, no access rights to this API
403 Forbidden Authorization header scheme is not "Bearer" (only Bearer supported)
404 Not Found Request URL is incorrect
500 Internal Server Error Internal server error
502 Bad Gateway Push gateway server overload, network attempted a bad connection
503 Service Unavailable API server or authentication server is down

Example code

  • Request ("enableLocale":false) 

      POST /push/send HTTP/1.1
    Host: sandbox-notification.qpyou.cn
    Content-Type: application/json
    Authorization: Bearer {API KEY}
    Content-Length: [auto calculated]

  {
      "notice": false,
      "identifiers": [
          {
              "playerId": 200001358,
              "did": 300010915
          }
      ],
      "game": {
          "gameid": "com.com2us.hivesdk",
          "appids": [
              "com.com2us.hivesdk.normal.freefull.google.global.android.common",
              "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
          ]
      },
      "enableLocale": false,
      "payload": {
          "single": {
              "android": {
                  "title": "android title",
                  "message": "android message",
                  "messageExpanded": "",
                  "imageUrl": "",
                  "ticker": "",
                  "summaryText": ""
              },
              "ios": {
                  "title": "ios title",
                  "message": "ios message",
                  "mediaUrl": ""
              }
          },
          "option": {
              "badge": "1",
              "overwrite": false,
              "collapseKey": "",
              "engagement": "",
              "groupKey": "",
              "android": {
                  "icon": "",
                  "sound": "",
                  "priority": "normal"
              },
              "ios": {
                  "sound": ""
              }
          }
      },
      "actionInfo": {
          "android": {
              "actions": [
                  {
                      "titles": {
                          "default": "OK"
                      },
                      "actionType": "CURL",
                      "action": "https://examplecurl.com"
                  },
                  {
                      "titles": {
                          "default": "Cancel"
                      },
                      "actionType": "CLOSE",
                      "action": ""
                  }
              ]
          },
          "ios": {
              "category": "CONFIRM_CATEGORY",
              "actions": [
                  {
                      "actionId": "CONFIRM_ID",
                      "actionType": "CURL",
                      "action": "https://examplecurl.com"
                  },
                  {
                      "actionId": "CLOSE_ID",
                      "actionType": "CLOSE",
                      "action": ""
                  }
              ]
          }
      }
  }

  • Request ("enableLocale":true) 

    POST /push/send HTTP/1.1
Host: sandbox-notification.qpyou.cn
Content-Type: application/json
Authorization: Bearer {API KEY}
Content-Length: [auto calculated]

{
    "notice": false,
    "identifiers": [
        {
            "playerId": 200001358,
            "did": 300010915
        }
    ],
    "game": {
        "gameid": "com.com2us.hivesdk",
        "appids": [
            "com.com2us.hivesdk.normal.freefull.google.global.android.common",
            "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
        ]
    },
    "enableLocale": true,
    "payload": {
        "defaultLanguage": "en",
        "locale": {
            "ko": {
                "android": {
                    "title": "테스트_한국어 제목",
                    "message": "테스트_한국어 메세지"
                },
                "ios": {
                    "title": "테스트_한국어 제목",
                    "message": "테스트_한국어 메세지"
                }
            },
            "en": {
                "android": {
                    "title": "test_English title",
                    "message": "test_English message"
                },
                "ios": {
                    "title": "test_English title",
                    "message": "test_English message"
                }
            }
        },
        "option": {
            "badge": 1,
            "overwrite": true,
            "collapseKey": "99",
            "groupKey": "",
            "android": {
                "icon": "GoogleIcon",
                "sound": "GoogleSound",
                "priority": "normal"
            },
            "ios": {
                "sound": "AppleSound"
            }
        }
    },
    "actionInfo": {
        "android": {
            "actions": [
                {
                    "titles": {
                        "default": "OK",
                        "en": "OK",
                        "ko": "확인"
                    },
                    "actionType": "CURL",
                    "action": "https://examplecurl.com"
                },
                {
                    "titles": {
                        "default": "Cancel",
                        "en": "Cancel",
                        "ko": "취소"
                    },
                    "actionType": "CLOSE",
                    "action": ""
                }
            ]
        },
        "ios": {
            "category": "CONFIRM_CATEGORY",
            "actions": [
                {
                    "actionId": "CONFIRM_ID",
                    "actionType": "CURL",
                    "action": "https://examplecurl.com"
                },
                {
                    "actionId": "CLOSE_ID",
                    "actionType": "CLOSE",
                    "action": ""
                }
            ]
        }
    }
}

Note

It is recommended to send the request data in a single line without line breaks so that the server logs can be checked immediately.

  • Response 
    HTTP/1.1 200 OK
Content-length: 0
Content-Type: application/json
UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9