Guide
#Hive5 v5 Guide
- 본 문서는 확정된 상태가 아니라 수정중에 있습니다.
- REST API가 정확하게 표현되지 않은 상태이므로, 개요를 파악하는 수준으로 활용하세요.
##Introduction 본 문서는 Hive5를 쉽게 개괄할 수 있도록 애니팡과 같은 간단한 게임의 개발을 가정하고, 필요한 요소와 작업들을 기술했습니다. 과정들을 따라가면서 다음과 같은 내용들에 알 수 있게 됩니다.
- 로그인과 Social 링킹 얻기
- 게임의 시작과 종료, 스코어 등 사용자 정보 저장
- 아이템의 구매와 사용
- 결제 (In-App Purchase)
- 미션과 보상
- Push
##1. 로그인과 Social 랭킹
먼저 관리콘솔에서 신규 게임을 생성합니다. 게임을 생성하면, App Access Key가 발급됩니다. REST API 호출의 인증에는 3개의 헤더 X-APP-KEY, X-AUTH_UUID, X-AUTH-TOKEN가 필요합니다. X-APP-KEY가 App Access Key에 해당합니다. (X-AUTH-TOKEN은 이후에서 언급하게 될 로그인의 결과로 얻어옵니다.)
이제 본격적으로 애니팡 스타일의 게임을 만들어 보겠습니다. 소셜 플랫폼으로는 카카오를 선택하겠습니다. 이 외에도 Hive5에는 페이스북, 구글, 네이버, 익명 로그인을 제공합니다. 익명 로그인은 별도의 소셜 플랫폼이 없는 형태입니다.
카카오의 경우 개발사와 카카오 간의 계약이 선행되어야 합니다. 계약 이후에 카카오 API를 호출할 수 있는 key 등을 발급받게 됩니다. 페이스북이나 구글의 경우는 이와 달리 웹상에서 바로 앱을 생성해서 key를 발급받아 해당 플랫폼의 API를 호출할 수 있습니다.
이제 게임 화면을 구성합니다. 게임을 실행하면 먼저 로그인을 해야 합니다. 카카오 로그인을 해보겠습니다.
로그인 버튼을 누르면, 우선 카카오 API를 통해 로그인을 수행합니다. 이때 아이디와 친구목록도 받게 됩니다. 자세한 내용은 카카오 API 문서를 참조해주세요. 보통 아래와 같은 형태로 로그인을 수행합니다.
[카카오 로그인 api call]
카카오에 로그인에 성공했으면 Hive5에도 로그인과 친구목록 업데이트를 수행해야 합니다. 그렇게 해야 Hive5에서 데이터들이 유지되고 이 데이터들을 이용해서 통계 분석이나 리더보드 업데이트가 이루어집니다.
로그인은 다음과 같이 호출합니다. 본 문서에서는 REST API로 표현했으나, Unity용 SDK를 사용하시면 관련된 함수 호출을 수행하시면 됩니다.
GET http://hornet.hive5.io/v5/auth/login?platform=kakao&platform_user_id=3432983
최초로 로그인을 하는 경우라면 이 때 사용자가 생성됩니다. 로그인에 성공하면 결과값이 리턴됩니다. 결과 값에는 다양한 데이터들이 있습니다. 이 중 access_token은 향후 API 호출에 반드시 필요하니, 잘 저장해 두어야 합니다.
이제 스코어나, 하트 개수 등 사용자의 정보를 얻어올 차례입니다. 신규 플레이어라면 이런 정보들을 디폴트로 저장해야 합니다. 이를 위해 프로시저를 사용합니다. 프로시저는 javascript 기반으로 콘솔에서 미리 등록시킵니다. 그리고 클라이언트에서 호출을 하면, 서버에서 실행되는 구조입니다. 프로시저를 통해 데이터를 불러오거나 저장할 수 있으며, 미리 정의된 테이블을 참조해서 비교 판단할 수 있습니다. 그 외에도 Hive5에서 제공하는 메일이나, 리더보드 등의 기능에 대해 제어가 가능합니다. 프로시저에 대한 자세한 내용은 Procedure 문서를 참조하세요. 지금은 Hive5 object를 이용해서 플레이어 정보를 초기화하는 get_player_info라는 프로시저를 다음과 같이 만들어 보겠습니다.
function get_player_info(params) {
// 최초 로그인인 경우 player를 초기화한다. 플레이어 정보를 리턴받는다.
player = HObject.load("player"); //singleton으로 player라는 클래스 이름의 객체를 얻어온다.
if (player.level == null) { // level 필드가 정의되지 않았으면, 최초 사용자이므로, 초기화하여 저장한다.
//각종 필드 초기화
player.level = 1;
player.exp = 0;
player.score = 0;
player.highscore = 0;
player.topaz = 5;
player.coin = 500;
player.items = new Array();
HObject.save(player);
}
return player;
}이 프로시저를 호출하는 API는 다음과 같습니다. 로그인의 결과로 획득한 access token도 헤더에 추가해야 합니다.
GET http://hornet.hive5.io/v5/procedures/call/get_player_info
이 프로시저의 호출 결과로 플레이어의 레벨, 점수, 코인과 토파즈 수 등을 받아오게 되므로, 클라이언트에서 적절하게 표시합니다.
player라는 클래스 이름의 싱글턴 객체가 있는 건데 여기에 다른 어떤 정보도 저장하거나 업데이트 할 수 있습니다. 물론 프로시저를 통해 값을 추가하거나 변경할 수 있지만, Object를 생성하거나, 읽어오거나, 저장하는 API도 존재합니다. Objects API를 참조해주세요.
로그인까지 성공했으면 그 다음 화면은 보통 친구 목록과 순위가 표시됩니다.
친구 목록은 카카오 로그인 API에서 얻어왔는데, 이 친구 목록은 hive5에도 동일하게 유지를 시켜주어야 하기 때문에 hive5 API를 이용해서 아래와 같이 갱신시켜주어야 합니다. request body에 JSON 형식으로 친구들의 platform user id를 넘기게 됩니다.
POST http://hornet.hive5.io/v5/friends/update
친구들 간의 순위가 social 랭킹입니다. social 랭킹을 얻어오기 위해서는 우선 리더보드를 관리콘솔에서 생성합니다. 그리고 생성된 리더보드 id를 이용해서 다음과 같이 호출합니다.
GET http://hornet.hive5.io/v5/leaderboards/1/social_scores
이제 social 랭킹을 얻어왔기 때문에 클라이언트에서 순위에 관련된 부분도 완성할 수 있습니다.
##2. 게임의 시작과 끝
이제 게임 시작 화면입니다. 애니팡 스타일의 게임은 시작을 위해 하트가 필요합니다. 그리고 하트는 일정시간 마다 자동으로 충전됩니다. 먼저 하트의 개수를 가져오는 get_heart 프로시저를 만들어보겠습니다. 이 프로시저에는 하트가 자동충전되는 부분도 포함되어 있습니다. inner-function을 사용했다는 점도 확인해주세요.
function get_heart(params) {
function update_heart() {
// 초기화 안된 경우 추가
if (player.heart_max==null) {
player.heart=5;
player.heart_max=5;
player.heart_recharging_interval=10*1000; // test로 10초
}
// 하트가 최대치이거나, 충전시간에 도달안됐으면 리턴
if (player.heart_max==player.heart || Date.now()<player.heart_next_recharge) {
return;
}
// 경과 시간으로 충전가능 하트 수 계산
var now = Date.now();
var elapsed_time = now - (player.heart_next_recharge - player.heart_recharging_interval);
var rechargable_heart_count = Math.floor(elapsed_time/player.heart_recharging_interval);
// 최대치 고려하여 그 수 만큼 충전
player.heart = player.heart + rechargable_heart_count;
if (player.heart > player.heart_max)
player.heart = player.heart_max;
// 다음 충전시간 갱신
if (player.heart == player.heart_max)
player.heart_next_recharge = null; // 최대치이므로, 다음 충전시간은 없음
else
player.heart_next_recharge = now + player.heart_recharging_interval - (elapsed_time % player.heart_recharging_interval);
}
var player = HObject.load("player");
update_heart(); //자동충전을 위한 업데이트 함수
HObject.save(player);
return {heart:player.heart, next_recharge:player.heart_next_recharge, now:Date.now()};
}프로시저는 다음과 같이 호출합니다. 그 결과로 현재의 하트 개수와, 다음 충전시간이 넘어오므로, 클라이언트에서도 타이머를 돌려서 충전되는 시간 효과를 낼 수 있습니다.
GET http://hornet.hive5.io/v5/procedures/call/get_heart
이제 게임 시작 버튼을 누르면 게임시 시작됩니다. 게임을 시작하면 1개의 하트가 소모되므로, 이를 위한 프로시저도 만들겠습니다. 이름을 start_game이라고 하겠습니다. 이 프로시저 내에서는 다음 하트 충전시간도 계산해서 저장합니다.
function start_game(params) {
// 하트 감소
var player=HObject.load("player");
if (player.heart==0)
throw "사용가능 하트 없음";
player.heart--;
// 다음 충전시간이 null이면 충전가능 시간을 계산해 세팅
if (player.heart_next_recharge==null) {
player.heart_next_recharge = Date.now() + player.heart_recharging_interval;
}
// save
HObject.save(player);
return {heart:player.heart, next_recharge:player.heart_next_recharge};
}프로시저 호출은 위와 동일합니다. 이제 클라이언트에서는 게임을 진행하면 됩니다.
게임이 종료되면 스코어를 산출할 수 있습니다. 이제 스코어를 파라미터로 하여 게임의 종료 처리를 수행하는 프로시저를 호출합니다. 이 프로시저에서는 스코어를 저장하고, 리더보드에도 등록하며, 각종 보상을 수행합니다. 다음은 이런 작업의 예를 보여주는 end_game 프로시저입니다. 신기록을 갱신할 경우 100코인의 보상이 지급되고 있음을 확인해 주세요.
function end_game(params) {
//params
//score: 획득한 점수
var score = parseInt(params.score);
var player = HObject.load("player");
player.score += score; //개인 점수를 누적시켜 줌.
var rewards = new Array();
// high score 를 달성했는지 확인
if (score>player.highscore) {
player.highscore = score;
// 하이스코어 달성 보상 수행
player.topaz+=20;
rewards.push({name:"highscore", msg:"100코인이 지급되었습니다."});
}
HObject.save(player);
// 스코어를 리더보드에 제출
var leaderboard_id = 1;
HLeaderboard.submitScore(leaderboard_id, score);
return {player:player, rewards:rewards};
}이 프로시저는 파라미터가 필요합니다. score를 다음과 같이 query string 형식으로 넘겨서 호출합니다.
GET http://hornet.hive5.io/v5/procedures/call/end_game?score=300
##3. 아이템 구매와 사용
예제 게임에서는 토파즈와 코인이라는 두 종류의 화폐가 통용됩니다. 토파즈는 현금 결제를 통해서만 구입이 가능하며, 코인은 가입시에도 기본으로 제공되고 게임에 대한 각종 보상으로도 지급됩니다. 이번 장에서는 실제 현금 결제가 아닌 코인을 이용해서 아이템을 구매하는 경우를 다룹니다.
최초 가입시 제공되는 기본 코인과 신기록 갱신에 대한 보상으로 화폐를 증가시키는 법은 앞 장의 프로시저 내용에서 이미 다루었습니다.
아래는 게임 시작 직접의 아이템샵 UI입니다. 황금폭탄을 구매하면, 코인 590이 차감되고, 게임에서 이 아이템을 사용할 수 있습니다.
게임시작을 누르면 선택된 start_game 프로시저를 호출했는데, 여기에 아이템들의 구매 처리를 추가시켰습니다.
function start_game(params) {
// params
// items : 구매하려는 아이템 3개 (item no를 |로 구분)
// item table 로드
var item_tbl = HDataTable.load("item");
function getItem(no) {
for (i=0; i<item_tbl.length; i++) {
if (no == item_tbl[i].no)
return item_tbl[i];
}
return null;
}
// 하트 감소
var player=HObject.load("player");
if (player.heart==0)
throw "no heart";
player.heart--;
// 다음 충전시간이 null이면 충전가능 시간을 계산해 세팅
if (player.heart_next_recharge==null) {
player.heart_next_recharge = Date.now() + player.heart_recharging_interval;
}
// 아이템 구매
var buying_items = params.items.split("|");
if (buying_items.length>3)
throw "too many items";
for (i=0; i<buying_items.length; i++) {
var item = getItem(buying_items[i])
if (item==null)
throw "item not found.";
player.coin -= item.price;
}
if (player.coin<0)
throw "no coin.";
// save
HObject.save(player);
return "ok";
}이 프로시저는 다음과 같이 구매하려는 아이템의 고유번호를 최대 3개까지 |로 구분해서 넘깁니다.
GET http://hornet.hive5.io/v5/procedures/call/start_game?items=3|4
프로시저에서 HDataTable 라이브러리를 사용하고 있습니다. 콘솔의 Data Table에서 item이라는 아이템의 목록을 미리 정의시켜 두었고, 이를 로드한 것입니다. 다음은 아이템을 정의한 테이블의 예입니다.
| no | name | price |
|---|---|---|
| 1 | 돋보기 | 180 |
| 2 | 긴급폭탄 | 200 |
| 3 | 시간 보너스 | 270 |
| 4 | 황금폭탄 | 590 |
테이블에서 정의된 가격 만큼 사용자 코인에서 차감해서 저장했습니다. 이를 통해 아이템 구매를 처리할 수 있었으며, 남은 코인이 있는지를 비롯해서 각종 조건들도 검사할 수 있습니다. 이제 클라이언트에서는 구매한 아이템을 발동할 수 있도록 게임을 구성하면 됩니다.
아래의 화면은 토파즈를 이용해서 코인을 구매하는 UI입니다. 역시 프로시저를 이용할 수 있습니다. 구현의 예입니다. 지불하려는 topaz를 파라미터로 넘기게 됩니다.
function buy_coin(params) {
var topaz = parseInt(params.topaz);
var tbl = HDataTable.load("coin_topaz", {topaz:topaz});
if (tbl.length!=1)
throw "product not found";
var player=HObject.load("player");
player.topaz -= tbl[0].topaz;
player.coin += tbl[0].coin;
if (player.topaz<0)
throw "no topaz.";
// save
HObject.save(player);
return "ok";
}HDataTable.load 함수에서 이전의 예와는 다르게 조건을 추가해 특정 row만을 가져오게 할 수 있음을 확인해 주세요.
어떤 아이템은 1번의 게임에만 적용되지 않고, 특정시간 동안 유효하기도 합니다. 이런 아이템은 Player 정보에 기록을 해두어야 다음 로그인 때도 사용이 가능합니다. 아래와 같은 경험치 물약이 좋은 예입니다.
player의 items 필드에 필요한 정보들을 저장할 수 있습니다. 다음 프로시저가 구현 예입니다.
function buy_exp_potion(params) {
var topaz = parseInt(params.topaz);
var tbl = HDataTable.load("potion_topaz", {topaz:topaz});
if (tbl.length!=1)
throw "product not found";
var player=HObject.load("player");
player.topaz -= tbl[0].topaz;
if (player.topaz<0)
throw "no topaz.";
// 물약 아이템이 이미 있는지 조사
for (i=0; i<player.items.length; i++) {
if (player.items[i].type == "exp_potion")
throw "already possessed";
}
// 물약 아이템 추가
var potion = {type:"exp_potion"};
potion.expired = Date.now() + tbl[0].duration*1000;
player.items.push(potion);
// save
HObject.save(player);
return potion;
}물약 효과의 만기시간을 expired 필드에 저장했습니다. 이제 start_game 등에서 만기시간을 넘겼으면, 그 아이템을 삭제하는 처리를 수행하고, 유효하다면 클라이언트에서 경험치를 계산하는데 이용할 수 있을 것입니다.
##4. 결제 (In-App Purchase)
토파즈를 증가시키기 위해서는 실제 현금 결제를 해야 합니다. 결제는 약간의 과정이 더 추가되며, 안드로이드인지 아이폰인지에 따라 구현이 다소 달라집니다.
다음은 토파즈 구매의 UI입니다. 1100원을 결제해서 토파즈 20개를 살 수 있는 상품 등 총 5가지가 있습니다.
이 개별 상품은 먼저 해당 마켓에 등록을 해 두어야 합니다. 안드로이드의 경우 구글에 먼저 상품을 등록합니다. 해당 상품들은 Hive5에도 등록이 되어 있어야 합니다. 상품은 IAP(In App Purchase) conversion을 이용하는데, 역시 관리콘솔에서 등록합니다. 상품코드는 구글 마켓과 동일해야 합니다. 그리고 실행시킬 프로시저를 연결해야 합니다. 토파즈 20개를 증가시키는 프로시저를 다음과 같이 정의할 수 있습니다. 이 프로시저는 외부에서 그냥 호출할 경우, topaz가 바로 증가되기 때문에 반드시 protected로 설정해야 합니다. protected로 설정하면 REST로 호출할 수 없고, IAP conversion에서의 호출은 가능해집니다.
function buy_topaz_20(params) {
var player=HObject.load("player");
player.topaz += 20;
HObject.save(player);
return player;
}이제 설정은 준비되었습니다. 실제 결제는 어떻게 이루어 질까요? Hive5와 구글 API를 모두 사용해야 한다는 사실이 중요합니다. 먼저 1) Hive5 구글 결제시작 API를 호출하고, 2) 구글 결제 API를 호출하고, 3) 마지막으로 Hive5 구글 결제 완료 API를 호출하면, 위에서 정의한 프로시저가 실행됩니다. 자세히 알아보겠습니다.
가장 먼저 구글 구매 시작이라는 API를 호출하니다. 구글에 등록한 상품코드가 json 형태로 request body에 포함되어야 합니다.
POST http://hornet.hive5.io/v5/google_purchases
그리고 구글 SDK를 통해 결제 API를 호출합니다. 자세한 내용은 구글 SDK문서를 참조해 주십시오. 에러가 없다면, 마지막으로 Hive5의 구매 종료 API를 호출합니다. 위에서 받은 구매 id를 넘깁니다.
POST http://hornet.hive5.io/v5/google_purchases/complete/(id)
지금까지의 과정이 모두 성공하면, IAP 컨버전에 등록한 프로시저인 buy_topaz_20가 수행됩니다. 즉, 지정된 만큼의 토파즈가 증가될 것입니다.
iOS의 경우에도 과정은 유사합니다. Hive5의 API는 google_purchases대신 apple_purchases입니다. Apple의 결제 API의 사용을 위해서는 Apple의 API 문서를 참조해 주세요.
##5. 미션과 보상
게임에서는 적절한 보상을 통해 동기를 유발합니다. 아래 화면은 베스트 스코어를 넘어설 때의 보상입니다.
베스트 스코어에 대한 보상은 이미 2장에서 살펴본 바 있습니다. 이처럼 프로시저를 호출해서 미션을 충족시키는 조건을 검사해서 다양한 보상을 부여할 수 있습니다.
Hive5에서는 미션과 보상을 위한 Mission 객체와 API도 있습니다. 이에 대한 알아보기 전에 프로시저를 이용하는 방법을 먼저 살펴보겠습니다. 누적 스코어가 3만점을 넘기는 미션을 가정합니다. 그리고, 이에 대한 보상으로 200 코인을 지급하겠습니다. 프로시저는 다음과 같은 형태가 될 것이며, 클라이언트에서 누적 스코어가 3만점 이상일 때 이 프로시저를 호출합니다.
function complete_score_mission(params) {
var player=HObject.load("player");
if (player.score >= 30000) {
player.topaz += 20;
HObject.save(player);
}
return player;
}그러나 이런 방식에는 보안상 약간의 문제가 있습니다. 이 프로시저 호출 API를 반복적으로 수행하는 replay attack을 한다면, 계속해서 topaz가 증가하는 문제가 생깁니다. 이 미션에 대한 보상을 이미 지급했는지를 추가적으로 object를 이용해 관리한다면 이 문제를 막을 수 있지만, 관리가 용이하지는 않습니다. Mission 객체를 사용하면 관리도 이런 기능을 쉽게 사용하고 관리할 수 있습니다. 콘솔에서 미션을 생성합니다. key는 score_30000로 하고, 이 미션에 complete_score_mission 프로시저를 연결합니다. 미션의 속성 중 즉시 변경 항목이 있는데, true로 합니다. false의 경우는 뒤에서 다시 다루겠습니다. complete_score_mission 프로시저는 REST로 호출할 수 없도록 protected로 변경합니다. 이렇게 한 후, 프로시저 호출 대신 등록한 미션에 대한 완료 API를 다음과 같이 호출합니다.
POST http://hornet.hive5.io/v5/missions/complete/score_30000
호출 결과로 연결된 프로시저인 complete_score_mission이 실행됩니다. 그리고 이 미션은 무효화가 되어 반복적으로 호출해도 재실행되지 않습니다.
이제 즉시 수행이 아닌 메일함을 통해서 보상을 받는 형태의 미션을 살펴보겠습니다. 미션이 수행됐음을 즉시 확인하기가 어렵거나, 다음에 다시 로그인을 하도록 유도하여 그 때 보상을 지급하려는 경우에 사용할 수 있습니다. 위와 같은 방법으로 미션을 하나 더 만들겠습니다. 즉시수행은 false로 합니다. 메일 컨텐츠에는 플레이어가 받게될 메일의 내용을 입력하면 됩니다. 이렇게 한 후, 동일한 방법으로 미션 완료 API를 호출합니다. 즉시 수행때와는 달리 mail_id와 reward_id를 리턴받습니다. mail_id는 메일함에 들어가는 메일을 가르킵니다. Mail에 관련한 내용은 다음 장에서 다루겠습니다. reward_id는 보상 아이템을 가르킵니다. 언제든지 이 reward_id로 보상을 수행하는 API를 호출할 수 있습니다. 보통 메일함에서 보상 수행을 클릭할 때 호출하게 됩니다. 호출하는 방법은 다음과 같습니다. :id 부분에 리턴받은 reward_id가 들어갑니다.
POST http://hornet.hive5.io/v5/rewards/apply/:id
request_body에는 연결된 메일의 삭제 여부를 지정할 수 있습니다. 이 호출의 결과로 연결된 프로시저가 호출되며, 한번 수행된 보상에 대해서는 반복적으로 적용되지는 않습니다.
##6. Mail
친구 관계를 이용해서 친구간의 도전이나 선물하기 기능을 넣을 수 있는데, 이 때 커뮤니케이션의 수단으로 메일을 사용합니다. 플레이어간의 메일도 있지만, 시스템에서 플레이어에게 메시지를 전달하는 수단으로도 유용합니다. 앞 장에서 살펴본 미션 수행 내용이나 보상을 전달하는 경우가 좋은 예입니다.
메일들의 내용을 보여주기 위해서 먼저 메일의 개수를 알아올 필요가 있습니다. 메일 개수는 다음과 같이 알 수 있습니다.
GET http://hornet.hive5.io/v5/mails/count
파라미터로 tag도 있습니다. 위 화면처럼 하트, 선물, 도전이라는 태그를 두어서 나누어 표현할 때 유용합니다.
메일의 내용은 다음과 같이 얻어옵니다. 특정 태그가 포함된 것만 받아올 수 도 있고, 순서와 얻어올 개수를 지정할 수도 있습니다.
GET http://hornet.hive5.io/v5/mails
메일을 생성할 때는 다음 API를 이용합니다. 파라미터에는 메일 내용 외에도 복수의 태그를 추가할 수 있습니다. 친구에게 보낼 경우 해당 플랫폼의 user id를 파라미터로 넘겨야 하며, 생략하면 플레이어에게 보내는 메일이 됩니다.
POST http://hornet.hive5.io/v5/mails
어떤 보상에 대해 메일을 생성해야 할 필요성이 많기 때문에 프로시저에서도 메일 생성이 가능합니다. 다음과 같이 사용할 수 있습니다.
// system에서 플레이어에게로
HMail.create("Level2 미션을 완수했습니다. 하트 1개를 받습니다.", ["하트"]);
// 친구에게 메일
HMail.send("friend_platform_user_id_1234", "하트 1개를 보냈습니다.", ["하트", "선물"]);사용자가 메일을 삭제할 수 도 있습니다. 삭제하기를 누르면 다음을 호출합니다.
POST http://hornet.hive5.io/v5/mails/delete/:id
이외에 메일내용을 수정하기, 모두 삭제하기, 메일에 태그를 추가, 삭제하기 등이 가능합니다. 자세한 내용은 API 문서를 참조해주세요.