Hive 아이템 v1 – Hive Developers

Hive SDK v1.19.1부터 IAP v1과 IAP v2의 지원을 종료합니다. Hive SDK v1.19.1 이상의 환경에서는 Hive IAP v4를 적용하시기 바랍니다.

목적

본 가이드는 개별 게임과 Hive 아이템 간의 원활한 연동을 위하여 작성되었다.
향후 게임 내의 재화/아이템 관리 부분은 모두 Hive 아이템에 적용될 것이기에 게임 서버 개발자와 시스템 개발자 간의 공통된 API를 마련하여 빠른 개발을 도모하려는 목적이다.

HTTP 통신

기본 사항

HTTP 프로토콜을 이용한 JSON 데이터 통신
Hive 아이템에서 게임 서버로 JSON데이터를 POST 로 전송하여 요청
게임 서버에서 Hive 아이템으로 JSON Data 결과 반환
결과 값은 결과 코드, 실패시 실패 목록과 사유 포함
서비스 오픈 이전 테스트 서버로 연동 테스트, 서비스 오픈 시 실 서버 전송
서비스 중인 경우에도 테스트 서버 연동 필수
접근 허용 포트는 80 또는 20080 Port

요청 명세(Hive 아이템 -> 게임서버)

처리 프로세스
Hive 아이템에서 요청 권한을 가진 관리자가 재화 요청(지급/회수)을 하면 처리 권한을 가진 관리자가 완료 또는 반려로 요청을 처리할 수 있으며 관리자가 완료 처리 시에 게임 서버로 재화를 요청하는 방식
HTTP Header: 해시 (데이터 유효성 검증위해 사용가능)
http header 중에 HTTP_APIHASH 키값으로 데이터 검증을 위한 해시값이 전달되며, 해당 값은 “!@#COM2US!@#” 과 JSON Data를 조합하여 생성한 sha1의 해시값(사용 예시 참조)

필드명	값	설명
request_id	string	각 요청을 구별하기 위한 식별자 (쿠폰은 중복 가능)
id_category	string	*아이디 구분 (‘vid’ / ‘hubuid’ / ‘hubid’ 등)
id_list	array	아이디 목록
type	string	요청항목 (‘1234’ / ‘asset_gold’ 등 통신용 항목코드)
amount	string	요청 수량 (양의 정수로 된 문자열)
category1	string	*지급수단 (‘p’ / ‘d’ 하단 설명 참조)
category2	string	*지급구분 (‘pa’ / ‘pi’ 하단 설명 참조)
reason	string	*요청사유 (하단 설명 참조)
req_comment	string	요청 코멘트 (UTF8 인코딩된 최대 500 자의 문자열)
req_admin	string	요청자 (UTF8 인코딩된 최대 60 자의 문자열)
user_msg	string	사용자에게 보여질 메세지

(* 표식이 앞에 붙어있는 항목은 하단 설명 참조)

* id_category 필드 코드 설명
“vid” : Hive 통합모듈 연동 게임의 경우
“hubuid” : 허브 연동 게임의 경우
“hubid” : 허브 연동 게임의 경우 (과거 재화 시스템 API 와의 호환성을 위해 유지)
“appcenterid” : 카카오톡 연동 게임의 경우
“momoid” : 중국 플랫폼 모모 연동 게임의 경우

* category1 필드 코드 설명
“p” : 지급의 경우 사용하며 우편함 (Postbox)
“d” : 회수의 경우 사용하며 데이터처리 (Dataprocessing)

* category2 필드 코드 설명
“pa” : 재화지급 (Present Asset)
“pi” : 아이템지급 (Present Item)
“ra” : 재화회수 (Retrieve Asset)
“ri” : 아이템회수 (Retrieve Item)

* reason 필드 코드 설명 (추후 추가/변경될 가능성 존재)
“pe” : “과금오류” (Payment Error)
“rge” : “보상(게임오류)” (Reward Game Error)
“rcd” : “보상(고객불만)” (Reward Consumer Dissatisfaction)
“rce” : “보상(쿠폰오류)” (Reward Coupon Error)
“ro” : “보상(해외)” (Reward Overseas)
“ae” : “재화변경지급” (Asset Exchange)
“e” : “이벤트” (Event)
“ea” : “이벤트(자동)” (Event Automatic)
“mc” : “대량쿠폰” (Massive Coupon)
“uc” : “고유쿠폰” (Unique Coupon)
“b” : “인게임 빌링” (Billing – Hive IAP 2.0)
“lb” : “러비웹샵 빌링” (Lebi Billing)
“co” : “오퍼월” (Cpi Offerwall)
“ini” : “CPI 뉴스배너 자사” (cpI Newsbanner Inside)
“ino” : “CPI 뉴스배너 타사” (cpI Newsbanner Outside)
“ioi” : “CPI 오퍼월 자사” (cpI Offerwal Inside)
“ioo” : “CPI 오퍼월 타사” (cpI Offerwal Outside)
“ani” : “CPA 뉴스배너 자사” (cpA Newsbanner Inside)
“ano” : “CPA 뉴스배너 타사” (cpA Newsbanner Outside)
“aoi” : “CPA 오퍼월 자사” (cpA Offerwal Inside)
“aoo” : “CPA 오퍼월 타사” (cpA Offerwal Outside)
“tcs” : “테스트(CS)” (Test CS)
“tgm” : “테스트(GM)” (Test GM)
“tpm” : “테스트(PM)” (Test PM)
“tqa” : “테스트(QA)” (Test QA)
“td” : “테스트(개발)” (Test Developer)
“tg” : “테스트(외부지급)” (Test Guest)
“tmb” : “테스트(홍보/사업)” (Test Market , Business)
“to” : “테스트(해외)” (Test Overseas)
“re” : “회수(기타)” (Retrieve Etc)
“rr” : “회수(환불)” (Retrieve Refund)
“mr” : “대량요청” (Massive Request)
“etc” : “기타” (Etc)

요청 예시(Hive 아이템 개발자용, PHP)

<span class="guide_font_blue">// 요청 데이터 </span>
$data = array(
    'request_id'           => '12321',
    'id_category'         => 'hubid',
    'id_list'                  => array('12345', '54321'),
    'type'                     => '101',
    'amount'                => '100', <span class="guide_font_blue">// 수치의 경우에도 문자열로 표시 </span>
    'category1'            => 'p', <span class="guide_font_blue">// 우편함의 경우</span>
    'category2'            => 'pa', <span class="guide_font_blue">// 재화 지급의 경우</span>
    'reason'                 => 'e', <span class="guide_font_blue">// 이벤트의 경우</span>
    'req_comment'      => '특별 이벤트 보상',
    'req_admin'           => 'kimkangil',
    'user_msg'            => '선물이 도착했습니다!',
);


$jsonData = json_encode($data); <span class="guide_font_blue">// JSON 으로 변환</span>
<span class="guide_font_blue">/******************************************************************** </span>
<span class="guide_font_blue">변환 결과(가독성을 위해 임의로 개행 및 공백 추가) :</span>
<span class="guide_font_blue">{</span>
<span class="guide_font_blue">    "request_id":"12321",</span>
<span class="guide_font_blue">    "id_category":"hubid",</span>
<span class="guide_font_blue">    "id_list":["12345","54321"],</span>
<span class="guide_font_blue">    "type":"101",</span>
<span class="guide_font_blue">    "amount":"100",</span>
<span class="guide_font_blue">    "category1":"p",</span>
<span class="guide_font_blue">    "category2":"pa",</span>
<span class="guide_font_blue">    "reason":"e",</span>
<span class="guide_font_blue">    "req_comment":"특별 이벤트 보상",</span>
<span class="guide_font_blue">    "req_admin":"kimkangil",</span>
<span class="guide_font_blue">    "user_msg":"선물이 도착했습니다!"</span>
<span class="guide_font_blue">}</span>
<span class="guide_font_blue">********************************************************************/</span>

<span class="guide_font_blue">// header 를 application/json 으로 설정 & hash 설정</span> 
$hash = sha1(<a href="mailto:'!@#COM2US!@#'">'!@#COM2US!@#'</a> . $jsonData); 
$header = array(
    'Content-type: application/json',
    'Apihash: ' . $hash
);
$url = '<span class="guide_font_blue">http://game.com2us.com/gms.php</span>'; <span class="guide_font_blue">// 게임서버url</span>

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, $header); 
curl_setopt($curl, CURLOPT_URL, $url); 
curl_setopt($curl, CURLOPT_POST, true); 
curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData); 
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
$result = curl_exec( $curl );
curl_close( $curl );

<span class="guide_font_blue">// 결과 데이터 처리</span>
$response = json_decode($result);

// 요청 데이터

$data = array(

'request_id' => '12321',

'id_category' => 'hubid',

'id_list' => array('12345', '54321'),

'type' => '101',

'amount' => '100', // 수치의 경우에도 문자열로 표시

'category1' => 'p', // 우편함의 경우

'category2' => 'pa', // 재화 지급의 경우

'reason' => 'e', // 이벤트의 경우

'req_comment' => '특별 이벤트 보상',

'req_admin' => 'kimkangil',

'user_msg' => '선물이 도착했습니다!',

);

$jsonData = json_encode($data); // JSON 으로 변환

/********************************************************************

변환 결과(가독성을 위해 임의로 개행 및 공백 추가) :

{

"request_id":"12321",

"id_category":"hubid",

"id_list":["12345","54321"],

"type":"101",

"amount":"100",

"category1":"p",

"category2":"pa",

"reason":"e",

"req_comment":"특별 이벤트 보상",

"req_admin":"kimkangil",

"user_msg":"선물이 도착했습니다!"

}

********************************************************************/

// header 를 application/json 으로 설정 & hash 설정

$hash = sha1(<a href="mailto:'!@#COM2US!@#'">'!@#COM2US!@#'</a> . $jsonData);

$header = array(

'Content-type: application/json',

'Apihash: ' . $hash

);

$url = 'http://game.com2us.com/gms.php'; // 게임서버url

$curl = curl_init();

curl_setopt($curl, CURLOPT_HTTPHEADER, $header);

curl_setopt($curl, CURLOPT_URL, $url);

curl_setopt($curl, CURLOPT_POST, true);

curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData);

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec( $curl );

curl_close( $curl );

// 결과 데이터 처리

$response = json_decode($result);

응답(게임서버 -> Hive 아이템)

Hive 아이템으로부터 재화 처리 요청을 받은 게임 서버에서는 해당 데이터를 처리 후에 결과를 응답
값의 경우 string 은 문자열, array 는 배열, 숫자도 문자열로 표기
실패 이유의 순서와 실패 아이디 목록은 동일한 순서로 구성

필드	값	설명
result_code	‘100’	전부 성공
	‘200’	일부 실패
	‘300’	전부 실패 (아이디 한 개 일 경우의 실패)
failure_id_list	array	지급에 실패한 아이디 목록
failure_reason_list	array	지급에 실패한 이유 목록

응답 예시(서버 개발자용, PHP)

<span class="guide_font_blue">// php header 선언</span>
header('Content-type: application/json');
<span class="guide_font_blue">// json Data</span>
$rawData = file_get_contents('php://input');
<span class="guide_font_blue">//Hash값 확인</span>
$hash = sha1(<a href="mailto:'!@#COM2US!@#'">'!@#COM2US!@#'</a> . $rawData);
$requestHash = $_SERVER['HTTP_APIHASH'];
if ($requestHash != $hash) { 
<span class="guide_font_blue">/*****************************************************************</span>
<span class="guide_font_blue">해쉬값이 다를 경우의 처리 (해쉬 사용 여부는 선택사항) </span>
<span class="guide_font_blue">*****************************************************************/</span> 
}


<span class="guide_font_blue">// 요청받은 JSON 데이터를 다시 디코딩</span> 
$requestData = json_decode($rawData); 
<span class="guide_font_blue">// 필요한 데이터만을 추출</span>
$requestId = $requestData->request_id; 
$idList = $requestData->id_list; 
$amount = $requestData->amount; 
$category1 = $requestData->category1; 
$category2 = $requestData->category2; 
$type = $requestData->type;

<span class="guide_font_blue">/*****************************************************************</span>
<span class="guide_font_blue">요청에 따른 재화 처리</span>
<span class="guide_font_blue">*****************************************************************/</span>

<span class="guide_font_blue">// 지급/회수 처리 결과를 반환, 아래의 경우 모두 실패인 300 </span>
<span class="guide_font_blue">// 실패 이유는 실패 아이디와 동일한 순서</span>
$returnData = array(
    'result_code'              => '300',
    'failure_id_list'            => array('12345', '54321'),
    'failure_reason_list'   => array('not exists', 'not exists'),
);

<span class="guide_font_blue">//UTF8BOM이 붙는 것을 방지하기 위해</span>
ob_clean()
<span class="guide_font_blue">//JSON으로 변환하여 응답 전송</span>
echo json_encode($returnData); 
<span class="guide_font_blue">/***************************************************************** </span>
<span class="guide_font_blue">변환 결과(임의로 개행 삽입) :</span>
<span class="guide_font_blue">{</span>
<span class="guide_font_blue">    "result_code":300,</span>
<span class="guide_font_blue">    "failure_id_list":["12345","54321"],</span>
<span class="guide_font_blue">    "failure_reason_list":["not exists","not exists"]</span>
<span class="guide_font_blue">}</span>
<span class="guide_font_blue">*****************************************************************/</span>

// php header 선언

header('Content-type: application/json');

// json Data

$rawData = file_get_contents('php://input');

//Hash값 확인

$hash = sha1(<a href="mailto:'!@#COM2US!@#'">'!@#COM2US!@#'</a> . $rawData);

$requestHash = $_SERVER['HTTP_APIHASH'];

if ($requestHash != $hash) {

/*****************************************************************

해쉬값이 다를 경우의 처리 (해쉬 사용 여부는 선택사항)

*****************************************************************/

}

// 요청받은 JSON 데이터를 다시 디코딩

$requestData = json_decode($rawData);

// 필요한 데이터만을 추출

$requestId = $requestData->request_id;

$idList = $requestData->id_list;

$amount = $requestData->amount;

$category1 = $requestData->category1;

$category2 = $requestData->category2;

$type = $requestData->type;

/*****************************************************************

요청에 따른 재화 처리

*****************************************************************/

// 지급/회수 처리 결과를 반환, 아래의 경우 모두 실패인 300

// 실패 이유는 실패 아이디와 동일한 순서

$returnData = array(

'result_code' => '300',

'failure_id_list' => array('12345', '54321'),

'failure_reason_list' => array('not exists', 'not exists'),

);

//UTF8BOM이 붙는 것을 방지하기 위해

ob_clean()

//JSON으로 변환하여 응답 전송

echo json_encode($returnData);

/*****************************************************************

변환 결과(임의로 개행 삽입) :

{

"result_code":300,

"failure_id_list":["12345","54321"],

"failure_reason_list":["not exists","not exists"]

}

*****************************************************************/

소켓통신

기본 사항

TCP/IP 프로토콜을 이용한 패킷 데이터 통신으로 포트는 20080
기본적으로 데이터는 HTTP 통신 때와 동일한 JSON 형식
Byte Order 는 Network Byte Order (Big Endian)
서비스 오픈 이전 테스트 서버로 연동 테스트, 서비스 오픈 시 실 서버 전송
서비스 중인 경우에도 테스트 서버 연동 필수

요청 명세(Hive 아이템 -> 게임서버)

요청 패킷 명세

사이즈	4 byte	4 byte	가변	4 byte		가변
내용	전체 길이	Header 길이	Header	Body 길이		Body

첫 4byte 의 경우 해당 4byte 를 포함한 패킷 전체의 길이를 명시
(header 가 46byte, body가 100byte라면 4 + 4 + 46 + 4 + 100 = 158byte)
그 다음 4bype의 경우 바로 뒤에 이어질 Header의 길이를 표기
Header 는 HTTP 통신에서의 해쉬값과 동일한 JSON 문자열
예.{“apihash”:”912ec803b2ce49e4a541068d495ab570″}
그 다음 4byte 의 경우 바로 뒤에 이어질 Body 의 길이를 명시
Body 의 경우에는 HTTP 통신에서의 요청값과 동일한 JSON 문자열
예. {request_id”:”12321″,”id_category”… …”user_msg”: “선물이도착했습니다!”}
JSON 문자열의 경우 기본적으로 UTF8 을 기준으로 인코딩

응답 명세(게임서버 -> Hive 아이템)

응답 패킷 명세

사이즈	4 byte	가변
내용	전체 길이	Body

첫 4byte 의 경우 해당 4byte 를 포함한 패킷 전체의 길이를 명시
Body의 경우 HTTP 통신에서의 응답값과 동일한 JSON 문자열

서버 개발자 준비 사항

Hive 아이템과 연동을 위해 아래 사항을 작성하여 담당자에게 전달
[요청 서식 다운로드]

Hive 아이템에서 호출된 URL (테스트 & 상용)
해당 게임의 아이디 구분 (vid or hubuid or etc…)
연동할 재화/아이템의 한글, 영문 이름과 전송코드, 지급, 회수 가능 여부 명시
유저에게 메세지 전송이 가능한 경우, 메세지 길이(UTF8 인코딩기준)와 기본메세지
명칭, 영문명, type은 각각 게임 내에서 유일한 값이어야함 (중복 불가능)
서버가 여러개일 경우 *서버 지역 코드 사용 (additionalinfo 의 server 값)
*서버 지역 코드의 경우 “Hive 로케일 식별자 정책” 문서 참조 [다운로드]

목적

HTTP 통신

기본 사항

요청 명세(Hive 아이템 -> 게임서버)

요청 예시(Hive 아이템 개발자용, PHP)

응답(게임서버 -> Hive 아이템)

응답 예시(서버 개발자용, PHP)

소켓통신

기본 사항

요청 명세(Hive 아이템 -> 게임서버)

응답 명세(게임서버 -> Hive 아이템)

서버 개발자 준비 사항

시작하기

SDK 개발

콘솔 가이드

다운로드

API 문서

지원