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 this is a notice alert (default: false).
• true: Sent as a notice alert.
Will not be sent to recipients who have not agreed to receive notices. If sent during nighttime hours (21:00~08:00), additional nighttime consent is required. See Notice Alert Workflow for details.
• false: Sent as a game alert (required operational alert). Sent regardless of consent to receive notices.
※ If notifications are blocked at the device/OS level, alerts may not be delivered regardless of the notice setting.		 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

Notice alert workflow

Notice alerts are sent only to game app users who have agreed to receive them. If the notice alert is sent between 21:00~08:00, additional consent for nighttime alerts is required.

Details of the notice alert workflow are as follows:

  • If the user does not agree to receive notice alerts, all messages set as notices will not be sent.
  • Only users who have agreed to receive notice alerts can give consent for nighttime alerts.
Warning

Regulations for advertising notice alerts to Korean users

When sending notice alerts to Korean users, they are considered advertising alerts and must comply with Article 50 of the 「Information and Communications Network Act」. The advertising alert message must include a phrase indicating it is an advertisement and instructions for opting out.

  • Example of advertising alert message: (Ad) {message_body} (Opt-out: change in settings)
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