인앱 정보 조회 API
인앱 정보 조회 API는 웹 상점에 접속한 사용자의 앱 서버, 채널, 캐릭터 정보를 불러오기 위한 API입니다. 이 API는 Hive 서버가 개발사 앱 서버로 요청을 보내면, 개발사 서버에서 응답값을 Hive 서버로 돌려주는 API입니다.
개요¶
Hive 커뮤니티와 웹 상점을 이용할 때, 웹 상점에서 구매하기 UI를 구현하려면 아래와 같이 접속한 사용자의 앱 서버, 채널, 캐릭터 정보가 필요합니다.
이 API 사용을 포함한 전체 과정을 요약하면 아래와 같습니다.
- 앱 개발사: API 엔드포인트를 구성해 서버 URL을 준비
- 앱 개발사: Hive 콘솔 인게임 정보에서 Hive 서버에 전달할 정보를 설정
- Hive 서버: 앱 개발사가 등록한 서버 URL로 POST API 요청, 응답값으로 데이터 수령
- Hive 서버: 수령한 앱 서버, 채널, 캐릭터 정보를 프론트엔드로 전송
- 웹 상점 프론트엔드: 웹 상점 구매하기 UI에서 드롭다운 메뉴를 노출
API 엔드포인트 구성(서버 URL)¶
Hive 콘솔 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 인게임 정보에 API 엔드포인트를 등록합니다.
API 엔드포인트는 요청을 받을 때 요청 매개변수에 있는 사용자 정보(cs_code)를 받고, 응답으로 앱 서버, 채널, 캐릭터 정보를 전달해야 합니다. API 엔드포인트는 Hive 콘솔(상용, 샌드박스, 테스트)에 대응해 아래 예시와 같이 구성합니다.
| 콘솔 환경 | API 엔드포인트 |
|---|---|
| 상용 | https://{URL}/webstore-profile |
| 샌드박스 | https://{URL}/webstore-profile |
| 테스트 | https://{URL}/webstore-profile |
API 요청(Hive 서버 → 앱 서버) 구성¶
Hive 서버에서 앱 서버로 보내는 POST 요청 정보입니다. 앱 서버 리스트, 서버에 포함된 채널, 그리고 캐릭터 목록을 응답으로 받습니다.
| API 정보 | 설명 |
|---|---|
| Method | POST |
| Reponse Format | JSON |
| Content-type | application/json |
다음은 Request Body 정보입니다.
| 명칭 | 타입 | 필수 여부 (필수: O, 옵션: X) | 설명 |
|---|---|---|---|
| cs_code | String | O | 사용자 고유 식별자 |
다음은 Request Body 예시입니다.
API 응답(앱 서버 → Hive 서버) 구성¶
응답 성공 시, 앱 서버에서 Hive 서버로 전달해야 하는 응답값 정보입니다. 상품별로 캐릭터 레벨에 따른 구매 제한 기능을 위해, Hive 콘솔 인앱 정보에서 캐릭터를 선택하지 않았더라도 캐릭터 레벨 정보를 전달해야 합니다. 캐릭터를 미선택한 경우, 배열(data.channels.characters)에 캐릭터가 여러 개 있다면 배열 첫 번째 원소에 해당하는 캐릭터의 레벨을 사용합니다.
| 명칭 | 타입 | 필수 여부(필수: O, 옵션: X) | 설명 |
|---|---|---|---|
| result_code | Integer | O | 결과 코드 |
| result_message | String | O | 결과 메세지 |
| cs_code | String | O | 사용자 고유 식별자 |
| data | Array | O | 서버 리스트(사용자 정보 없을 경우 응답 값: "[ ]") |
| data.server_id | String | O | 서버 고유 식별자 |
| data.server_name | String | O | 서버의 이름 |
| data.channels | Array | O | 서버에 포함된 채널 리스트 |
| data.channels.channel_id | String | O | 채널 고유 식별자(채널 미사용시 응답 값: "0") |
| data.channels.channel_name | String | O | 채널의 이름(채널 미사용시 응답 값: "-") |
| data.channels.characters | Array | O | 채널에 포함된 캐릭터 리스트 |
| data.channels.characters.character_id | String | O | 캐릭터 고유 식별자(캐릭터 미사용시 응답 값: "-") |
| data.channels.characters.character_name | String | O | 캐릭터의 이름(캐릭터 미사용시 응답 값: "-") |
| data.channels.characters.character_level | String | O | 캐릭터의 레벨(캐릭터 레벨이 없는 경우 응답값: "0") |
다음은 응답 성공 시 응답값 예시입니다.
// 콘솔에서 서버, 채널, 캐릭터 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": "c_123412341234",
"data": [
{
"server_id": "1",
"server_name": "Server 1",
"channels": [{
"channel_id": "1",
"channel_name": "Channel 1",
"characters": [{
"character_id": "A",
"character_name": "Character A",
"character_level": "99"
},
{
"character_id": "B",
"character_name": "Character B",
"character_level": "10"
}
]
}]
}
]
}
// 콘솔에서 서버, 캐릭터 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": "c_123412341234",
"data": [
{
"server_id": "2",
"server_name": "Server 2",
"channels": [{
"channel_id": "0",
"channel_name": "-",
"characters": [{
"character_id": "C",
"character_name": "Character C",
"character_level": "11"
},
{
"character_id": "D",
"character_name": "Character E",
"character_level": "12"
}
]
}]
}
]
}
// 콘솔에서 서버, 채널 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": "c_123412341234",
"data": [
{
"server_id": "3",
"server_name": "Server 3",
"channels": [{
"channel_id": "2",
"channel_name": "Channel 2",
"characters": [{
"character_id": "-",
"character_name": "-",
"character_level": "99"
}]
}]
}
]
}
// 콘솔에서 서버만 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": "c_123412341234",
"data": [
{
"server_id": "4",
"server_name": "Server 4",
"channels": [{
"channel_id": "0",
"channel_name": "-",
"characters": [{
"character_id": "-",
"character_name": "-",
"character_level": "99"
}]
}]
}
]
}
// 콘솔에서 서버, 채널, 캐릭터 선택 시 - 채널이 여러 개인 경우
{
"result_code": 200,
"result_message": "success",
"cs_code": "c_123412341234",
"data": [
{
"server_id": "1",
"server_name": "Server 1",
"channels": [
{
"channel_id": "1",
"channel_name": "Channel 1",
"characters": [
{
"character_id": "A",
"character_name": "Character A",
"character_level": "99"
}, {
"character_id": "B",
"character_name": "Character B",
"character_level": "10"
}
]
}, {
"channel_id": "2",
"channel_name": "Channel 2",
"characters": [
{
"character_id": "A2",
"character_name": "Character A2",
"character_level": "99"
}, {
"character_id": "B2",
"character_name": "Character B2",
"character_level": "10"
}
]
}
]
}
]
}
다음은 응답 코드(result_code)입니다.
| 코드 | 설명 |
|---|---|
| 200 | 성공 |
| 204 | 사용자에 대한 정보 없음 |
| 500 | 서버 에러 |