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 and Facebook). 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.

URL

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

Basic data and request variables

Method POST
URL /push/send
Division Field Name Description Type Required
Header Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
Body notice

Whether to send announcement notification or not (Default: 'false')

      true
    • Send as announcement notifications.
    • Send notifications depending on the user agreement.
      false
    • Send as game notifications.
    • Send notifications regardless of user agreement.

Announcement and night-time notifications are the items required to get the user agreement.

  • If user doesn't agree to receive announcement notifications, all notices set as announcement are blocked to send.
  • Agreement on receiving night-time notifications are enable only after agreement on receiving announcement notifications; unless, all notices set as announcement are blocked to send at night. Night time is from 9 p.m. to 8 a.m.

Boolean O
identifiers Identifier information (up to 100) Check the identifier structureand example below. identifier[] O
game gameid Game ID String O
appids

The list of AppID Nothing is sent if the mapping AppID is invalid.

Recommendation

  • If device-base ID (did): Add the mapping AppID.
  • If account-base IDs (playerId, vid, uid): Add a list of the whole mapping AppIDs.
  • If various types of ID: Refer to the Identifier structure to check the priority.

String[] X
enableLocale

Whether to enable the locale of each language or not

    true
  • Send messages in the same language which target users set. It is based on the tokens and setting language code.
  • It determines the language when storing tokens.
  • Highest in priority: Game language
  • Second priority: Device language (Unless game language is sent)
    false
  • Ignore the language locale and send as the value of single in payload field.

Boolean O
payload single Request to single field if enableLocale=false Check the Message structure below. Message O
defaultLanguage Set with the value of default language if enableLocale=true. String
locale {{LANGUAGE}} Set with the value of locale field if enableLocale=true Same data with message information of single field. Message
option Refer to the optional information below. Option X
Note
  • For appropriate single push reception, it is recommended to enter only one data for the appids and identifiers fields.
    • Because search conditions cannot be specified, push delivery may be delayed if the request contains multiple identifiers and appids.
  • It is recommended to designate a value with a high priority for the identifier value, and avoid configuring the identifier only with the did value.
  • Requests with only gameid specified in the game field must be avoided.
    • Push delivery may be delayed if there is no information in the appids field since all appids included in the gameid are searched.
  • The option field is not applicable to Facebook.

Identifier structure

Division Field Name Description Type Required
identifier identifier playerId One of four identifiers should be included It prioritizes playerId, vid, uid and did in order. Long O
vid
uid
did

Identifier example

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

Message structure

iostitleTitleStringOfacebooktitleTitle (within 1~30 letters)StringO

Division Field Name Description Type Required
Message android title Title String O
message Message String O
messageExpanded Expanded message String O
imageUrl Image URL String X
ticker Ticker String X
summaryText Summerized message String X
message Message String O
mediaUrl Image path String X
body Body (within 10~180 letters) String O
media Image URL String O

Option information

Category Field Name Description Type Required
Option badge The numerical value displayed on the app icon when a push notification is received (default: 1) Integer X
overwrite Whether to use the push overwrite feature on Android (default: false) Boolean X
collapseKey The key value (string format of a number: "123") used when the push overwrite feature is enabled String X
engagement User engagement String X
comment Text String X
groupKey This is the group key value used to group notifications together when received on iOS and Android devices. The notification options set on the device OS will be applied by default. For more details on the options, please refer to the documents below. String X
android icon The file name of the icon image that appears when a push notification is received on the user's device. The image file must exist in /src/main/res/drawable. Supported image file formats can be found here. If you want 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 The file name of the notification sound that will be played when a push notification is received on the user's device. You can specify a sound file included in the app bundle, and the sound file must exist in /src/main/res/raw. If this field is empty, the system default sound will be used. String X
priority The priority of the message being sent to the Android device. This priority controls the timing of message delivery, a concept from FCM. It can have values of NORMAL or HIGH, with the default being NORMAL. For more details, refer to the Firebase guide.
  • NORMAL = The default priority for data messages. Normally prioritized messages are sent immediately when the device is not in sleep mode. When the device is in sleep mode, delivery may be delayed to save battery until the device exits sleep mode. Choose normal delivery priority for messages that are not time-sensitive, such as new email notifications, keeping UI in sync, and background app data synchronization.
  • HIGH = FCM attempts to send high-priority messages immediately and may wake the device from sleep mode if necessary, executing limited processing tasks, including very restricted network access. High-priority messages typically involve user interactions with the app or notifications.
enum(NORMAL, HIGH) X
ios sound The file name of the notification sound that will be played when a push notification is received on the user's device. The sound file must exist in the app container's Library/Sounds or the main app bundle. If this field is empty, it will automatically be set to "default," using the system default sound on the user's Apple device. String X

Output result

Division Field Name Description
Header Content-Type application/json;charset=utf-8
UUID {{UUID}}
Body - Body is empty if success

Response state code

Key Value Description
200 Success (Body is empty.)
400 Bad Request POST data is omitted.JSON format errorRequired element is omitted or invalid.
401 Unauthorized Authorization header in request message is omitted or invalid.Authorization key (API KEY) is not registered.No access permission to the relevant API
403 Forbidden Authentication scheme of Authorization header is not "Bearer". (Supported Bearer only)
404 Not Found Request URL is wrong.
500 Internal Server Error Internal error on server
502 Bad Gateway Push gateway server is overloaded.Network connects in a wrong way.
503 Service Unavailable API server or authentication server is frozen.

Sample code

  • Call ("enableLocale":false)

    curl -L -v
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -H "Content-Type: application/json"
    > -H "Authorization: Bearer {API KEY}"
    > https://sandbox-notification.qpyou.cn/push/send
    
  • Call ("enableLocale":true)

    {
        "notice": false,
        "identifiers": [
            {
                "playerId": 30000028045
    }
    ],
        "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": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "ios": {
                        "title": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "facebook": {
                        "title": "test_Korean_title",
                        "body": "test_Korean_message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                },
                "en": {
                    "android": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "ios": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "facebook": {
                        "title": "test_English title",
                        "body": "test_English message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                }
            },
            "option": {
                "badge": 1,
                "overwrite": true,
                "collapseKey": "99",
                "groupKey: "",
                "android": {
                    "icon": "GoogleIcon",
                    "sound": "GoogleSound",
                    "priority": "normal"
                },
                "ios": {
                    "sound": "AppleSound"
                }
            }
        }
    }
    
Note

It is recommended to send call data in a row without any space for server to check the logs immediately.

  • Request
> POST /push/send HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NDE1NzMyOTcsImp0aSI6ImFkbWluaXN0cmF0b3IifQ.23nG9RnbuOwnMbRSebBi2i-Qt_fOfqU_vUKUZ2JJlWU
> Content-Length: 502
  • Response
< HTTP/1.1 200 OK
< content-length: 0
< Content-Type: application/json
< UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9