Guide
#Hive5 v5 Guide
- 본 문서는 확정된 상태가 아니라 수정중에 있습니다.
- REST API가 정확하게 표현되지 않은 상태이므로, 개요를 파악하는 수준으로 활용하세요.
##Introduction 본 문서는 Hive5를 쉽게 개괄할 수 있도록 애니팡과 같은 간단한 게임의 개발을 가정하고, 필요한 요소와 작업들을 기술했습니다. 과정들을 따라가면서 다음과 같은 내용들에 알 수 있게 됩니다.
- 소셜 플랫폼에 로그인, 친구 순위 얻기
- 게임의 시작과 종료, 스코어 등 사용자 정보 저장
- 아이템의 구매와 사용
- 결제 처리와 아이템 충전
- 미션과 보상
- 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로 작성하며, 콘솔에서 미리 등록시켜 둡니다. get_player_info라는 프로시저를 다음과 같이 작성했습니다.
// 최초 로그인인 경우 player를 초기화한다. 플레이어 정보를 리턴받는다.
player = HObject.load("player"); //singleton
if (player.level == null) { // 최초 생성이라는 의미
//각종초기화..
player.level = 1;
player.exp = 0;
player.score = 0;
player.ruby = 5;
player.coin = 300;
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. 게임의 시작과 끝