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

Hive 아이템(v2)이란?

  • 게임 내 재화와 아이템 지급/회수 기능을 통합하여 관리하기 위한 시스템
  • 쿠폰, 이벤트, 오퍼월, CPI 등과 연동되어 아이템의 지급/회수 기능 제공
  • 관리자용 백오피스를 제공하여 수동으로 지급/회수 및 이력 검색 가능
  • Hive IAP v2를 사용하는 게임에 한해 적용

지급/회수 요청 API

기본 사항

  • HTTP 또는 소켓을 이용한 JSON String 통신
  • Hive 아이템에서 게임 서버로 JSON String을 전송해 지급/회수 요청
  • 게임 서버에서 Hive 아이템으로 JSON String을 이용해 결과 반환
  • 응답 결과는 처리 코드와 메시지 포함
  • JSON String은 모두 UTF8로 인코딩
  • 아이템은 기본적으로 우편함에 지급
  • 서비스 오픈 전 테스트 서버로 연동 테스트하며, 서비스 오픈 후 상용 서버로 전송
  • 서비스 중에도 테스트 서버와 필수 연동
  • 서버 통신을 목적으로 게임 서버에서는 아래 IP의 방화벽 인바운드 규칙 해제 필요
    • 112.175.229.175
    • 112.175.229.176
    • 112.175.60.55
    • 112.175.60.56

 

HTTP 통신

기본 사항
  • 80이 기본 포트이며 다른 포트는 방화벽 해제 신청 필요
  • Hive 아이템에서 게임 서버로 요청할 때는 POST로 전송

 

요청 명세(Hive 아이템 > 게임 서버)
  • HTTP Header: HTTP_APIHASH
    데이터 유효성 검증을 목적으로 HTTP_APIHASH라는 키 값으로 해쉬값 전송
    해쉬값은 sha1 사용 (본문 JSON String에 접두어 “!@#COM2US!@#” 추가)
  • HTTP Body
    필드 1 필드 2 값 설명
    *transactionId string 요청을 구별하는 식별자(중복 요청 확인용)
    id string ID
    detail array 아래 세 항목 객체의 배열
    action string 지급/회수 여부
    s: 지급(Send)
    w: 회수(Withdraw)
    assetCode string 지급할 항목 코드
    amount int 지급 수량
    *reason string 요청 사유(하단 설명 참조)
    userMessage string 사용자가 보는 메시지
    *purchaseInfo object 인앱 구매 정보(reason필드 값: b, IAP 구매 시에만 존재)
    market int 마켓 구분값(하단 설명 참조)
    marketPid string 마켓에 등록된 상품의 PID(하단 설명 참조)
    gamePid string Hive IAP 2.0에서 생성한 상품의 PID(하단 설명 참조)
    iapTransactionId string Hive IAP v2의 결제 건당 식별 ID(하단 설명 참조)
    receipt JSON
    string    		 마켓에서 구매 시 보내주는 영수증 정보(하단 설명 참조)
    purchaseTimeUTC int 마켓에서 결제된 시간(Unix timestamp milliseconds)
    price double 결제 금액
    currency string 결제 통화 코드(ISO 4217)
    serverId string 대상 유저가 접속한 서버(서버 구분값)
    additionalinfo string 게임 서버로 보내기 위해 클라이언트에서 전송한 추가 정보(모두 소문자로 구성)

    (*이 표시된 항목은 하단 설명 참조)

    transactionId

    • 지급/회수 요청의 응답을 제대로 받지 못한 경우 동일한 요청을 재전송
    • 이미 처리된 요청인지 transactionId로 식별하여 판단(중복 지급/회수 방지)
    • 중복 요청의 경우 응답값에 해당 사항 명시(응답 명세 참고)

     

    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 v2)
    • “lb”: “러비웹샵 빌링” (Lebi Billing)
    • “co” : “오퍼월” (Cpi Offerwall)
    • “p” : “프로모션” (Promotion) – 크로스배너, 오퍼월, UA 모두 동일하게 사용
    • “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)

     

    purchaseInfo

    • reason이 b일 경우에만 존재
    • market: 구매한 마켓에 대한 구분값(1:Apple, 2:Google, 3:러비, 4:원스토어)
    • marketPid: 마켓에서 등록한 상품의 PID. 마켓에서 상품을 등록하면 부여되는 고유값
    • gamePid: Hive IAP에서 생성한 상품의 PID. Hive 콘솔> Hive 빌링 > Hive IAP v2 > 상품등록 메뉴에서 상품별로 생성되는 고유값으로, 마켓 PID와 게임 PID는 1:N 구조
    • iapTransactionId: Hive IAP v2의 결제 건당 생성되는 식별 ID
    • receipt: 마켓에서 구매 시 보내는 영수증 정보. 개발사에서 자체적으로 구매한 영수증 검증이나 결제 확인용 참고 정보
    • purchaseTimeUTC: 영수증 값에 표시되는 결제 시간. 마켓에서 결제된 시간을 의미
    • price: 결제 금액. 컴투스홀딩스 사업기획팀과 컴투스 서비스기획팀에서 관리하는 Google, Apple Matrix에서 구하는 가격으로, 가격 정책 변경 시 마켓과 Matrix 수동 반영하기 때문에 시간에 따라 약간의 오차가 발생 가능
    • currency: 결제 통화 코드(ISO 4217)
      예. USD, KRW, GBP
요청 예시(Hive 아이템 개발자용, PHP)
// 요청 데이터
$data = array(
‘transactionId’ => ‘12321’,
‘id’ => ‘828292’,
‘detail’ => array(
array(
‘action’ => ‘s’,
‘assetCode’ => ‘gold’,
‘amount’ => 500,
), array(
‘action’ => ‘s’,
‘assetCode’ => ‘gem’,
‘amount’ => 200,
),
),
‘reason’ => ‘e’,
‘userMessage’ => ‘선물이 도착했습니다!’,
‘serverId’ => ‘ GLOBAL’,
‘additionalinfo’ => ‘{“character”:1}’
);

$jsonData = json_encode($data); // JSON 으로 변환
/********************************************************************
변환 결과(가독성을 위해 임의로 개행 및 공백 추가) :
{
“transactionId”:”12345″,
“id”:”828292″,
“detail”:[
{
“action”:”s”,
“assetCode”:”gold”,
“amount”:500
},
{
“action”:”s”,
“assetCode”:”gem”,
“amount”:200
}
],
“reason”:”e”
 “userMessage”:”선물이 도착했습니다!”
 “serverId”:”GLOBAL”
 “additionalinfo”:”{“character”:1}”
}
********************************************************************/

// header 를 application/json 으로 설정 & hash 설정
$hash = sha1(‘!@#COM2US!@#’ . $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 아이템으로부터 재화 처리 요청을 받은 게임 서버에서는 해당 데이터를 처리 후에 결과를 응답
  • 한 개의 요청은 반드시 전체가 하나의 트랜잭션처럼 처리되어야 함
    (여러 개의 아이템 지급 시 한 개의 항목이라도 처리가 실패한다면 전부 지급되지 않아야하며 실패로 응답)
필드 값 설명
*code int 처리 결과 코드(하단 설명 참조)
message string 지급 실패 이유

(*이 표시된 항목은 하단 설명 참조)

code

  • 2xxxx: 요청 이상 없음 & 처리 성공
    • 20000 요청 이상 없음 & 처리 성공
    • 20001 요청 이상 없음 & 이미 성공 처리된 경우가 있음 (중복 요청의 경우)
      => 이미 정상 처리된 transactionId가 존재할 경우
  • 4xxxx: 요청 파라미터 오류
    • 40001 요청 JSON 에러
    • 40002 해쉬 오류
    • 40003 필수 파라미터 키 누락
    • 40004 필수 파라미터 키 타입 오류
    • 40005 필수 파라미터 값 비어있음
    • 40006 잘못된 필수 파라미터 값 (예. 음수)
  • 5xxxx: 서버 처리 오류
    • 50001 존재하지 않는 유저
    • 50004 DB 등록 오류
    • 50005 파라미터 오류 (예. 존재하지 않는 항목코드)

 

응답 예시(서버 개발자용, PHP)
// php header 선언
header(‘Content-type: application/json’);
// json Data
$rawData = file_get_contents(‘php://input’);
//Hash값 확인
$hash = sha1(‘!@#COM2US!@#’ . $rawData);
$requestHash = $_SERVER[‘HTTP_APIHASH’];
if ($requestHash != $hash) {
/*****************************************************************
해쉬값이 다를 경우의 처리 (해쉬 사용 여부는 선택사항)
*****************************************************************/
}

// 요청받은 JSON 데이터를 디코딩
$requestData = json_decode($rawData, TRUE);
foreach ($requestData[‘detail’] as $item) {
/*****************************************************************
요청에 따른 재화 처리
*****************************************************************/
}

$returnData = array(
‘code’ => 50001,
‘message’ => ‘user not exists’,
);

//UTF8BOM이 붙는 것을 방지하기 위해
ob_clean()
//JSON으로 변환하여 응답 전송
echo json_encode($returnData);
/*****************************************************************
변환 결과(임의로 개행 삽입) :
{
“code” : 50001,
“message” : “user 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 문자열

 

응답 명세(게임서버 > Hive 아이템)
패킷 4 byte 가변
내용 전체 길이 Body
  • 첫 4byte 의 경우 해당 4byte 를 포함한 패킷 전체의 길이를 명시
  • Body의 경우 HTTP 통신에서의 응답값과 동일한 JSON 문자열

 

게임 서버 개발자 준비 사항

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

  • 서버 정보
  • 게임 서버 한글명, 영문명
  • 게임 서버 url
  • 서버 지역 코드 (서버가 여러 개일 경우)
    => “Hive 로케일 식별자 정책” 문서 참조 [다운로드]
  • 유저에게 보내줄 기본 메세지와 최대길이(UTF8 기준, 가능한 경우)
  • 아이템 정보
    CSV 형식으로 작성하여 전달. 구분자는 콤마(,) 사용
  • 한 줄에 순서대로 코드명, 영문명, 지급/회수 가능 여부(하단 참조)
    1: 지급만 가능
    2: 회수만 가능
    3: 지급/회수 모두 가능
  • 한글명, 영문명, 코드의 경우 게임 내에서 유일한 값이어야 함