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.

URL¶

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

Basic data and request variables¶

Division	Field Name		Description	Type	Required
Method	POST
URL	/push/send
Header	Content-Type		application/json;charset=utf-8
Header	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
	game	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.

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¶

Category	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 Text	String	X
	ios	title	Title	String	O
		message	Body	String	O
		mediaUrl	Image URL	String	X

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. iOS Android	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":""}},"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"
                },
            },
            "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"
            }
        }
    }
}

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