Send a シングルプッシュ¶

Send a push notification immediately to the specified identifiers.

The Send a Single Push API uses server-to-server communication, called directly from the app server to the Hive Notification server. After request validation, sending is processed asynchronously. A response code of 0 means that the send request was accepted; it does not guarantee delivery.

Note

An OAuth 2.0 access token is required to use this API. If you already have a token, request only the additional permissions. See Issue an OAuth Token.

リクエスト URL¶

Production URL	https://notification.withhive.com/v2/push/send https://notification.qpyou.cn/v2/push/send
Sandbox URL	https://sandbox-notification.withhive.com/v2/push/send https://sandbox-notification.qpyou.cn/v2/push/send
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

リクエストヘッダー¶

Field	Description	Type	Required
X-Access-Token	OAuth 2.0 access token for app server authentication (see Issue an OAuth Token)	String	Y

Note

The JWT project_id must match game.gameid in the request body. This applies when using a project-type token.

リクエスト本文¶

Field	Description	Type	Required
identifiers	Recipient list. Must contain 1 to 100 valid items See Identifier structure	Array	Y
game	Target game information. See Game structure	Object	Y
enable_locale	Whether to apply language localization `true`: Use `payload.default_language` and `payload.locale` `false`: Use `payload.single`	Boolean	Y
payload	Message payload. See Payload structure	Object	Y
notice	Whether this is an announcement notification (default: `false`)	Boolean	N
action_info	Action button information. See ActionInfo structure	Object	N

Note

To avoid delays in push delivery, follow these recommendations:

We recommend specifying a single item in each of identifiers and game.appids. Sending multiple items can make the lookup criteria less specific and delay delivery.
Prefer the higher-priority player_id in identifiers; avoid using only did values.
Avoid specifying only gameid in game. If appids is empty, the lookup targets every app in the game and may delay delivery.

### Identifier Structure { #identifier }

At least one of player_id or did must be greater than 0. If both are provided, player_id takes precedence.

Field	Description	Type	Required
player_id	Player ID	Long	Conditional
did	Device ID	Long	Conditional

Note

Invalid items are removed during validation, and the item count is checked afterward. If all 100 submitted items are invalid, the API returns 1400.

### Game Structure { #game }

Field	Description	Type	Required
gameid	Game ID	String	Y
appids	App IDs to target. If omitted, all apps associated with `gameid` are targeted	Array	N

Payload Structure¶

Field	Description	Type	Required
single	Message to use when `enable_locale` is `false`. See Message structure	Object	Conditional
default_language	Default language code when `enable_locale` is `true`. Use lowercase; see Language codes	String	Conditional
locale	Messages by language code when `enable_locale` is `true`. Use lowercase keys and include a key matching `default_language` Each value follows the Message structure	Object	Conditional
option	Send options. See Option structure	Object	N

Message Structure¶

For at least one of android or ios, both title and message must be provided.

Field	Description	Type	Required
android.title	Android notification title	String	Conditional
android.message	Android notification body	String	Conditional
android.message_expanded	Body displayed when the notification is expanded	String	N
android.image_url	Image URL displayed in the notification	String	N
android.ticker	Ticker text displayed when the notification arrives	String	N
android.summary_text	Summary text that briefly describes the body	String	N
ios.title	iOS notification title	String	Conditional
ios.message	iOS notification body	String	Conditional
ios.media_url	Media URL displayed in a rich notification	String	N

Option Structure¶

Field	Description	Type	Required
badge	Number displayed on the app icon when a push is received (default: `1`)	Integer	N
overwrite	Whether to enable Android push overwrite (default: `false`)	Boolean	N
collapse_key	Key used for push overwrite. Specify a number as a string (for example, `"123"`)	String	N
comment	Description stored with a push overwrite	String	N
engagement	User engagement Scheme URL that the SDK executes when the push is tapped (for example, `push://hive/...`). Passed in the push payload's `action` field See Hive Scheme URL format	String	N
group_key	Group key used to display notifications together. Notification settings configured in the device OS apply by default See the iOS and Android documentation	String	N
android.icon	Image file name for the push notification icon. The image must be in the app's `/src/main/res/drawable` directory. See Android documentation for supported formats To use an image on the web, enter its URL instead of a file name If empty, the app icon is used	String	N
android.sound	Sound file name to play for the push notification. The file must be in the app's `/src/main/res/raw` directory If empty, the system default sound is used	String	N
android.priority	Priority of the message sent to Android devices (default: `NORMAL`). This FCM setting controls message delivery timing. See the Firebase guide `NORMAL`: Delivered immediately if the device is not in Doze mode; delivery may be delayed to save battery while the device is in Doze mode `HIGH`: Attempts immediate delivery and may wake the device from Doze mode if needed	String	N
ios.sound	Sound file name to play for the push notification. The file must be in the app container's `Library/Sounds` directory or the app's main bundle If empty, it is set to `default` and the system default sound is used	String	N

ActionInfo Structure¶

Field	Description	Type	Required
android.category	Action push category identifier	String	N
android.actions	Action buttons (up to 3). Each item must include `titles.default`	Array	N
ios.category	Action push category identifier. Required when using iOS actions	String	Conditional
ios.actions	Action buttons (up to 3). Each item must include `action_id`	Array	Conditional
actions[].action_id	Button identifier	String	Conditional
actions[].action_type	Button behavior. Case-insensitive. An unsupported or empty value is treated as `CLOSE` without an error `CURL`: Open the URL specified in `action` `CLOSE`: Only dismiss the notification (default)	String	N
actions[].action	Action to perform when the button is tapped. If `action_type` is `CURL`, this value is opened as a URL Required when `action_type` is not `CLOSE`	String	Conditional
actions[].titles	Button labels by language code. See Titles structure	Object	Conditional

Titles Structure¶

An object whose keys are language codes and whose values are the labels displayed on the buttons. The default key provides the fallback label when no key exists for the recipient's language.

{
  "default": "Open",
  "ko": "열기",
  "en": "Open"
}

Key	Description	Type	Required
default	Default button label. Required for Android actions; if empty, the API returns `1400`	String	Conditional
<language code>	Button label displayed in the specified language. See Language codes	String	N

The label is selected at send time as follows:

If enable_locale is true and a key exists for the recipient's language, that value is used.
Otherwise, the default value is used.

Note

If both category and actions are empty, the platform is treated as having no actions and validation is skipped.

titles is not validated for iOS actions, but button labels are selected in the same way as for Android. Provide titles for iOS as well.

リクエスト例¶

単一言語で送信¶

{
  "identifiers": [
    { "player_id": 20000044768 },
    { "did": 40000098765 }
  ],
  "game": {
    "gameid": "com.com2us.mygame",
    "appids": ["com.com2us.mygame.normal.freefull.google.global.android.common"]
  },
  "enable_locale": false,
  "notice": true,
  "payload": {
    "option": {
      "badge": 1,
      "group_key": "notice"
    },
    "single": {
      "android": {
        "title": "Maintenance notice",
        "message": "Server maintenance starts at 2:00 AM today."
      },
      "ios": {
        "title": "Maintenance notice",
        "message": "Server maintenance starts at 2:00 AM today."
      }
    }
  }
}

複数言語で送信¶

{
  "identifiers": [
    { "player_id": 20000044768 }
  ],
  "game": {
    "gameid": "com.com2us.mygame",
    "appids": [
      "com.com2us.mygame.normal.freefull.google.global.android.common",
      "com.com2us.mygame.normal.freefull.apple.global.ios.universal"
    ]
  },
  "enable_locale": true,
  "payload": {
    "default_language": "ko",
    "locale": {
      "ko": {
        "android": { "title": "점검 안내", "message": "오늘 02시 점검" }
      },
      "en": {
        "android": { "title": "Maintenance", "message": "Server maintenance at 2 AM" }
      }
    }
  }
}

アクションボタン付きで送信¶

{
  "identifiers": [
    { "player_id": 20000044768 }
  ],
  "game": {
    "gameid": "com.com2us.mygame",
    "appids": ["com.com2us.mygame.normal.freefull.apple.global.ios.universal"]
  },
  "enable_locale": false,
  "payload": {
    "single": {
      "ios": {
        "title": "Reward received",
        "message": "Check your mailbox."
      }
    }
  },
  "action_info": {
    "ios": {
      "category": "REWARD",
      "actions": [
        {
          "action_id": "open_mail",
          "action_type": "CURL",
          "action": "https://example.com/mail",
          "titles": {
            "default": "Open",
            "ko": "열기",
            "en": "Open"
          }
        },
        {
          "action_id": "dismiss",
          "action_type": "CLOSE",
          "titles": {
            "default": "Close",
            "ko": "닫기",
            "en": "Close"
          }
        }
      ]
    }
  }
}

Response header¶

Field	Description	Type
UUID	Request tracking ID. Uses the value provided in the request header, or a value generated by the server if none was provided	String

レスポンス本文¶

This API only accepts the send request and does not return a data field.

Field	Description	Type
result_code	Response code. Details	Integer
result_msg	Result message	String
token_validation	JWT validation result (JWT validation errors)	Object
token_validation.result_code	JWT validation result code	Integer
token_validation.result_msg	JWT validation result message	String

レスポンスコード¶

Code	Description
0	Success
1400	Invalid request A required field is missing A field has an invalid format `identifiers` contains no valid items or contains more than 100 items The message in `payload` is invalid
1401	No permission for the requested app
1500	Internal server error
2499	JWT validation failed (see `token_validation`)

レスポンス例¶

成功¶

{
  "result_code": 0,
  "result_msg": "success",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  }
}

失敗¶

{
  "result_code": 1400,
  "result_msg": "identifiers field is required.",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  }
}

JWT 検証失敗¶

{
  "result_code": 2499,
  "result_msg": "JWT validation failed.",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "The access token is expired. Please refresh your token."
  }
}

言語コード¶

The following language codes can be used for payload.default_language and the keys in payload.locale.

Language code	Language
ko	Korean
zh-hans	Simplified Chinese
zh-hant	Traditional Chinese
en	English
ja	Japanese
ar	Arabic
fr	French
de	German
es	Spanish
pt	Portuguese
th	Thai
it	Italian
ru	Russian
id	Indonesian
vi	Vietnamese
tr	Turkish
tl	Filipino

お知らせ通知の動作¶

Announcement notifications are sent only to app users who have agreed to receive them.

If a user has not agreed to receive announcement notifications, messages with notice set to true are not sent to that user.
If the send time falls during nighttime hours (21:00–08:00 the following day), the user must also have agreed to receive nighttime notifications.

Warning

When sending announcement notifications to users in Korea, follow Article 50 of Korea's Network Act, which treats them as advertising messages. Advertising notifications must include a label identifying the message as an advertisement and instructions for opting out.

Example advertising notification: (Ad) {message_body} (To opt out: change your settings)

Note

If JWT validation fails, check the token_validation field for details. See JWT validation error codes.