Skip to content

Guide

Jump to bottom Edit New page
Artie Choi edited this page May 30, 2014 · 13 revisions

#Hive5 v5 Guide

  • 본 문서는 확정된 상태가 아니라 수정중에 있습니다.
  • REST API가 정확하게 표현되지 않은 상태이므로, 개요를 파악하는 수준으로 활용하세요.

##Introduction 본 문서는 Hive5를 쉽게 개괄할 수 있도록 애니팡과 같은 간단한 게임의 개발을 가정하고, 필요한 요소와 작업들을 기술했습니다. 과정들을 따라가면서 다음과 같은 내용들에 알 수 있게 됩니다.

  • 소셜 플랫폼에 로그인, 친구 순위 얻기
  • 게임의 시작과 종료, 스코어 등 사용자 정보 저장
  • 아이템의 구매와 사용
  • 결제 처리와 아이템 충전
  • 미션과 보상
  • Mail
  • 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

API 자세히 보기

최초로 로그인을 하는 경우라면 이 때 사용자가 생성됩니다. 로그인에 성공하면 결과값이 리턴됩니다. 결과 값에는 다양한 데이터들이 있습니다. 이 중 access_token은 향후 API 호출에 반드시 필요하니, 잘 저장해 두어야 합니다.

이제 스코어나, 하트 개수 등 사용자의 정보를 얻어올 차례입니다. 신규 플레이어라면 이런 정보들을 디폴트로 저장해야 합니다. 이를 위해 프로시저를 사용합니다. 프로시저는 javascript 기반으로 콘솔에서 미리 등록시킵니다. 그리고 클라이언트에서 호출을 하면, 서버에서 실행되는 구조입니다. 프로시저를 통해 데이터를 불러오거나 저장할 수 있으며, 미리 정의된 테이블을 참조해서 비교 판단할 수 있습니다. 그 외에도 Hive5에서 제공하는 메일이나, 리더보드 등의 기능에 대해 제어가 가능합니다. 프로시저에 대한 자세한 내용은 Procedure 문서를 참조하세요. 지금은 Hive5 object를 이용해서 플레이어 정보를 초기화하는 get_player_info라는 프로시저를 다음과 같이 만들어 보겠습니다.

// 최초 로그인인 경우 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.ruby = 5;
    player.coin = 300;
    player.items = new Array();
   
    HObject.save(player);
}

return player;

이 프로시저를 호출하는 API는 다음과 같습니다. 로그인의 결과로 획득한 access token도 헤더에 추가해야 합니다.

GET http://hornet.hive5.io/v5/procedures/call/get_player_info

API 자세히 보기

이 프로시저의 호출 결과로 플레이어의 레벨, 점수, 코인과 루비 수 등을 받아오게 되므로, 클라이언트에서 적절하게 표시합니다.

player라는 클래스 이름의 싱글턴 객체가 있는 건데 여기에 다른 어떤 정보도 저장하거나 업데이트 할 수 있습니다. 물론 프로시저를 통해 값을 추가하거나 변경할 수 있지만, Object를 생성하거나, 읽어오거나, 저장하는 API도 존재합니다. Objects API를 참조해주세요.

로그인까지 성공했으면 그 다음 화면은 보통 친구 목록과 순위가 표시됩니다.

친구 목록은 카카오 로그인 API에서 얻어왔는데, 이 친구 목록은 hive5에도 동일하게 유지를 시켜주어야 하기 때문에 hive5 API를 이용해서 아래와 같이 갱신시켜주어야 합니다. request body에 JSON 형식으로 친구들의 platform user id를 넘기게 됩니다.

POST http://hornet.hive5.io/v5/friends/update

API 자세히 보기

친구들 간의 순위가 social 랭킹입니다. social 랭킹을 얻어오기 위해서는 우선 리더보드를 관리콘솔에서 생성합니다. 그리고 생성된 리더보드 id를 이용해서 다음과 같이 호출합니다.

GET http://hornet.hive5.io/v5/leaderboards/1/social_scores

API 자세히 보기

이제 social 랭킹을 얻어왔기 때문에 클라이언트에서 순위에 관련된 부분도 완성할 수 있습니다.

##2. 게임의 시작과 끝

이제 게임 시작 화면입니다. 애니팡 스타일의 게임은 시작을 위해 하트가 필요합니다. 그리고 하트는 일정시간 마다 자동으로 충전됩니다. 먼저 하트의 개수를 가져오는 check_heart 프로시저를 만들어보겠습니다. 이 프로시저에는 하트가 자동충전되는 부분도 포함되어 있습니다. inner-function을 사용했다는 점도 확인해주세요.

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/check_heart

이제 게임 시작 버튼을 누르면 게임시 시작됩니다. 게임을 시작하면 1개의 하트가 소모되므로, 이를 위한 프로시저도 만들겠습니다. 이름을 decrease_heart로 합니다. 이 프로시저 내에서는 다음 하트 충전시간도 계산해서 저장합니다.

// 하트 감소
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코인의 보상이 지급되고 있음을 확인해 주세요.

//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.coin+=100;
    
    rewards.push({name:"highscore", msg:"100코인이 지급되었습니다."});
}

HObject.save(player);

// 스코어를 리더보드에 제출
HLeaderboard.submitScore(1, score);

return {player:player, rewards:rewards};
Add a custom footer
Add a custom sidebar

Clone this wiki locally