타게팅 데이터 등록

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

'타게팅 데이터 등록' 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	Hive가 생성하는 인스턴스 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 검증 에러 코드를 참고하세요.