타게팅 데이터 등록¶

타게팅 푸시 발송에 사용할 대상 목록을 등록합니다.

'타게팅 데이터 등록' API는 앱 서버에서 Hive 노티피케이션 서버로 직접 호출하는 Server-to-Server 통신 방식으로 동작하며, 대상 목록을 담을 타게팅 데이터를 먼저 등록한 후 반환된 타게팅 ID로 대상 항목을 등록하는 순서로 사용합니다. 등록한 타게팅 ID는 캠페인 등록 및 수정 API의 targeting_id로 전달합니다.

Note

이 API를 연동하려면 OAuth 2.0 Access Token을 발급받아야 합니다. 토큰을 이미 발급받았다면 추가 권한만 요청합니다. OAuth Token 발급하기를 참고하세요.

'타게팅 데이터 등록' 기능으로 제공되는 API는 아래와 같습니다.

API Endpoint	설명
`POST /v2/push/targets`	타게팅 데이터 등록
`POST /v2/push/targets/{id}/direct/{action}`	타게팅 대상 항목 등록

타게팅 데이터 등록¶

대상 항목을 담을 타게팅 데이터를 등록하거나 이미 등록된 타게팅 데이터를 수정합니다. id를 1 이상으로 전달하면 기존 타게팅 데이터를 수정하고, 생략하면 타게팅 데이터를 새로 등록합니다.

Request URL¶

상용 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

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y

Note

JWT의 project_id가 요청 본문의 game.gameid와 일치해야 합니다. project 유형의 토큰을 사용할 때 적용됩니다. 타게팅 데이터를 수정할 때는 저장된 데이터의 앱을 먼저 확인한 후 요청 값과 대조합니다.

Request body¶

필드명	설명	타입	필수 여부
id	타게팅 데이터 ID. `1` 이상이면 기존 데이터 수정, 생략하면 신규 등록	Long	N
description	타게팅 데이터 제목 또는 설명	String	Y
game	타게팅 대상 게임 정보	Object	Y
game.gameid	게임 ID	String	Y

Note

이미 available 또는 locked 상태인 타게팅 데이터는 수정할 수 없습니다. 상태에 대한 자세한 내용은 타게팅 데이터 상태를 참고하세요.

Request example¶

신규 등록¶

{
  "description": "8월 복귀 유저 목록",
  "game": {
    "gameid": "com.com2us.mygame"
  }
}

기존 데이터 수정¶

{
  "id": 1024,
  "description": "8월 복귀 유저 목록 (수정)",
  "game": {
    "gameid": "com.com2us.mygame"
  }
}

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data.id	타게팅 데이터 ID. 신규 등록이면 서버에서 생성한 값	Long
data.game.gameid	게임 ID	String
data.game.game_index	서버가 조회하여 채운 게임 인덱스	Integer
data.description	타게팅 데이터 제목 또는 설명	String
data.registrant	등록자. 이 API로 등록한 데이터는 항상 `SYSTEM`	Object
data.timestamp	저장 시각. `date`는 문자열, `time`은 epoch milliseconds	Object
data.available	발송에 사용할 수 있는 상태 여부. 타게팅 데이터 상태 참고	Boolean
data.locked	대상 항목을 저장하는 중인지 여부. 타게팅 데이터 상태 참고	Boolean

응답 코드¶

코드값	설명
0	성공
1400	유효하지 않은 요청 필수 필드가 누락된 경우 요청한 `gameid`가 존재하지 않는 경우 이미 `available` 또는 `locked` 상태여서 수정할 수 없는 경우
1401	요청한 게임에 대한 권한이 없음
1500	서버 내부 오류
2499	JWT 검증 실패 (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": "8월 복귀 유저 목록",
    "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."
  }
}

타게팅 대상 항목 등록¶

등록된 타게팅 데이터에 발송 대상 항목을 넣습니다. 요청 검증 후 저장은 비동기로 처리되므로, 응답 코드 0은 등록 요청이 정상 접수되었다는 의미이며 저장 완료를 보장하지 않습니다.

Request URL¶

상용 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

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y

Note

저장된 타게팅 데이터의 게임을 먼저 확인한 후 요청 본문의 gameid와 대조합니다. 다른 게임의 타게팅 ID로 접근하는 것을 막기 위한 순서입니다.

Request path¶

필드명	설명	타입	필수 여부
id	타게팅 데이터 ID. `1` 이상의 정수	Long	Y
action	대상 항목 처리 방식. 대소문자를 구분하지 않음 `new`: 기존 항목을 모두 지우고 새로 등록 `add`: 기존 항목에 추가	String	Y

Request body¶

필드명	설명	타입	필수 여부
gameid	게임 ID. 저장된 타게팅 데이터의 값과 일치해야 함	String	Y
items	대상 항목 목록(최소 1개)	Array	Y
items[].identifier.player_id	Player ID	Long	조건부
items[].identifier.did	기기 ID	Long	조건부
items[].app.appid	App ID	String	Y

Note

player_id와 did 중 최소 하나는 0보다 큰 값이어야 합니다. 두 값을 모두 전달하면 player_id가 우선 적용됩니다.

Request example¶

{
  "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¶

이 API는 항목 등록 요청을 접수만 하므로 data 필드를 반환하지 않습니다.

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String

응답 코드¶

코드값	설명
0	성공. 존재하지 않는 타게팅 ID이거나 대상이 이미 `available` 상태인 경우에도 반환
1400	유효하지 않은 요청 경로의 `id`가 정수가 아니거나 `1` 미만인 경우 경로의 `action`이 `new` 또는 `add`가 아닌 경우 `items`가 비어 있거나 `app.appid`가 유효하지 않은 경우 대상이 `locked` 상태인 경우
1401	요청한 게임에 대한 권한이 없음
1500	서버 내부 오류
2499	JWT 검증 실패 (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."
  }
}

타게팅 데이터 상태¶

타게팅 데이터는 available과 locked 두 필드로 상태를 나타냅니다.

available	locked	설명
`false`	`false`	등록 직후 상태. 데이터를 수정하거나 대상 항목을 등록할 수 있음
`false`	`true`	대상 항목을 저장하는 중. 데이터를 수정할 수 없음
`true`	`false`	대상 항목 저장 완료. 발송에 사용할 수 있으며 데이터를 수정할 수 없음

Note

JWT 검증 실패 시, token_validation 필드로 자세한 오류 정보를 확인할 수 있습니다. 자세한 내용은 JWT 검증 에러 코드를 참고하세요.