ลงทะเบียนข้อมูล Targeting¶

Register a list of recipients for a targeting push.

The Register Targeting Data API uses server-to-server communication, called directly from the app server to the Hive Notification server. First register targeting data to hold the recipient list, then register recipient items using the returned targeting ID. Pass the targeting ID as targeting_id to the Register or Update Campaign API.

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.

The Register Targeting Data feature provides the following APIs:

API Endpoint	Description
`POST /v2/push/targets`	Register targeting data
`POST /v2/push/targets/{id}/direct/{action}`	Register targeting items

ลงทะเบียนข้อมูล Targeting¶

Register targeting data to hold recipient items, or update existing targeting data. If id is 1 or greater, the existing data is updated. If omitted, new targeting data is registered.

URL คำขอ¶

Production URL	https://notification.withhive.com/v2/push/targets https://notification.qpyou.cn/v2/push/targets
Sandbox URL	https://sandbox-notification.withhive.com/v2/push/targets https://sandbox-notification.qpyou.cn/v2/push/targets
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. When updating targeting data, the server first checks the app associated with the stored data and then compares it with the request value.

เนื้อหาคำขอ¶

Field	Description	Type	Required
id	Targeting data ID. Updates existing data when `1` or greater; omitted to register new data	Long	N
description	Targeting data title or description	String	Y
game	Game targeted by the targeting data	Object	Y
game.gameid	Game ID	String	Y

Note

Targeting data in the available or locked state cannot be modified. See Targeting Data States for details.

### ตัวอย่างคำขอ

#### Register New Data

{
  "description": "August returning-user list",
  "game": {
    "gameid": "com.com2us.mygame"
  }
}

Update Existing Data¶

{
  "id": 1024,
  "description": "August returning-user list (updated)",
  "game": {
    "gameid": "com.com2us.mygame"
  }
}

เนื้อหาการตอบกลับ¶

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
data.id	Targeting data ID; generated by the server for new data	Long
data.game.gameid	Game ID	String
data.game.game_index	Game index looked up and populated by the server	Integer
data.description	Targeting data title or description	String
data.registrant	Registrant. Always `SYSTEM` for data registered through this API	Object
data.timestamp	Save time. `date` is a string and `time` is epoch milliseconds	Object
data.available	Whether the data is ready to use for sending. See Targeting Data States	Boolean
data.locked	Whether recipient items are being saved. See Targeting Data States	Boolean

รหัสการตอบกลับ¶

Code	Description
0	Success
1400	Invalid request A required field is missing The requested `gameid` does not exist The data cannot be updated because it is already `available` or `locked`
1401	No permission for the requested game
1500	Internal server error
2499	JWT validation failed (see `token_validation`)

Response Example¶

สำเร็จ¶

{
  "result_code": 0,
  "result_msg": "success",
  "token_validation": {
    "result_code": 0,
    "result_msg": "success"
  },
  "data": {
    "id": 1024,
    "game": {
      "gameid": "com.com2us.mygame",
      "game_index": 1234
    },
    "description": "August returning-user list",
    "registrant": {
      "id": "SYSTEM",
      "name": "SYSTEM"
    },
    "timestamp": {
      "date": "2026-07-31 15:04:05.123",
      "time": 1785484045123
    },
    "available": false,
    "locked": false
  }
}

ล้มเหลว¶

{
  "result_code": 1400,
  "result_msg": "description 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."
  }
}

ลงทะเบียนรายการ Targeting¶

Add recipient items to registered targeting data. Items are saved asynchronously after request validation. A response code of 0 means that the registration request was accepted; it does not guarantee that saving is complete.

URL คำขอ¶

Production URL	https://notification.withhive.com/v2/push/targets/{id}/direct/{action} https://notification.qpyou.cn/v2/push/targets/{id}/direct/{action}
Sandbox URL	https://sandbox-notification.withhive.com/v2/push/targets/{id}/direct/{action} https://sandbox-notification.qpyou.cn/v2/push/targets/{id}/direct/{action}
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 server first checks the game associated with the stored targeting data, then compares it with gameid in the request body. This prevents access using a targeting ID belonging to another game.

### พาธคำขอ

Field	Description	Type	Required
id	Targeting data ID. An integer greater than or equal to `1`	Long	Y
action	How to process recipient items. Case-insensitive `new`: Remove all existing items and register new ones `add`: Add items to the existing list	String	Y

### Request Body

Field	Description	Type	Required
gameid	Game ID. Must match the value in the stored targeting data	String	Y
items	Recipient items (at least one)	Array	Y
items[].identifier.player_id	Player ID	Long	Conditional
items[].identifier.did	Instance ID generated by Hive	Long	Conditional
items[].app.appid	App ID	String	Y

Note

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

### ตัวอย่างคำขอ

{
  "gameid": "com.com2us.mygame",
  "items": [
    {
      "identifier": { "player_id": 20000044768 },
      "app": { "appid": "com.com2us.mygame.normal.freefull.google.global.android.common" }
    },
    {
      "identifier": { "did": 40000098765 },
      "app": { "appid": "com.com2us.mygame.normal.freefull.apple.global.ios.universal" }
    }
  ]
}

Response Body¶

This API only accepts the item registration 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. Also returned if the targeting ID does not exist or the data is already `available`
1400	Invalid request The path `id` is not an integer or is less than `1` The path `action` is neither `new` nor `add` `items` is empty or `app.appid` is invalid The data is `locked`
1401	No permission for the requested game
1500	Internal server error
2499	JWT validation failed (see `token_validation`)

Response Example¶

สำเร็จ¶

{
  "result_code": 0,
  "result_msg": "success",
  "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."
  }
}

สถานะข้อมูล Targeting¶

The state of targeting data is represented by the available and locked fields.

available	locked	Description
`false`	`false`	Initial state after registration. The data can be updated and recipient items can be registered
`false`	`true`	Recipient items are being saved. The data cannot be updated
`true`	`false`	Recipient items have been saved. The data is ready for sending and cannot be updated

Note

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