Skip to content

Version 5

Jump to bottom Edit New page
Gilbok Lee edited this page May 8, 2015 · 68 revisions

Status

Draft

특징

  • Post의 경우 request body는 JSON으로 한다.
  • Authentication 정보는 HTTP Header에 같이 보낸다.
  • 모든 통신은 HTTPS로 한다.

서버 정보

종류 Host
Beta (Staging) https://beta.hornet.hive5.io
Production https://hornet.hive5.io

Header

필요한 경우에 다음 parameter를 HTTP Header에 실어서 보낸다.

Name Value
X-APP-KEY 게임에 발급된 app key. 모든 API 호출에 필요.
X-AUTH-UUID 디바이스 고유의 UUID. 모든 API 호출에 필요.
안드로이드의 경우에는 설치 직후 UUID를 생성하여 넘겨준다.(권고사항)
X-AUTH-TOKEN 서버에서 로그인 후 발급한 인증 token. 사용자 식별이 필요한 API호출에 필요
로그인 API를 호출하면 응답결과로 받음
X-AUTH-SESSION 서버에서 로그인 후 발급한 session key. session 검사를 하고 싶은 경우 헤더에 포함해서 보낸다.
로그인 API를 호출하면 응답결과로 받음
X-REQUEST-ID 이 값이 세팅 되어 있는 경우에, response header에 그대로 다시 넣어서 줌

API List

로그인

게임 클라이언트가 시작되고, 로그인을 위해 서버로 호출하는 함수

  • Path: /:version/auth/login
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
platform Option[String] Social Platform 종류. 'kakao', 'naver', 'facebook', 'google', 'none' 중의 하나.
default는 'none'
platform_user_id Option[String] Social platform 의 user_id
platform이 'none'인 경우 hive5에서 id를 발급한다.
platform_sdk_version Option[String] Social platform 의 sdk version이 있는 경우 세팅
os String 'android' 또는 'ios'
object_key Array of String 로그인 후 가져와야할 사용자 object의 key
config_key Array of String 로그인 후 가져와야할 사용자 configuration의 key
  • Request URI Example:

https://[server-url]/:version/auth/login?platform=kakao&platform_user_id=3432983&object_key=player&object_key=sword:1231242&config_key=version&config_key=is_under_maintenance

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
session_key String
platform String 로그인 시의 platform
platform_user_id String 로그인 시의 platform_user_id. platform이 'none'인 경우 hive5에서 id를 발급한다.
objects Array of JSON object TBD
configs JSON data config_key에 명시된 configuration 데이터들을 json 형태로 반환
agreements JSON data 사용자가 동의한 약관에 대한 정보
key는 약관의 이름, value는 다음과 같다.
Name Type Description
version String 약관의 버전
agreed_at String 약관을 동의한 시간
형식은 "yyyy-MM-dd'T'HH:mm:ss"와 같으며, 항상 UTC 시간임
promotions JSON Array 현재 진행 중인 promotion에 대한 목록
Name Type Description
id Number 프로모션의 id
name String 프로모션의 이름
apply_url String 프로모션 신청 웹페이지 주소
display_url String 앱내에 사용자에게 보여주는 페이지의 url.
order Number 복수개인 경우에 ordering 순서. partner에 세팅한 값으로 나옴
completed_missions JSON Object JSON object의 key는 mission key이고, value는 미션 완료한 시간
시간 형식은 "yyyy-MM-dd'T'HH:mm:ss
  • Response Body Example:
{
    "result_code": 0,
    "access_token": "iuojsdof-SDFSDF-sdf24-123",
    "configs":  {
        "config1": "value1",
        "config2": "value2"
    },
    "agreements": {
        "agreement1": {
            "version": "1.1.0",
            "agreed_at": "2013-10-05T14:19:53"
        },
        "agreement2": {
            "version": "2.2",
            "agreed_at": "2013-10-05T14:19:53"
        }
    },
    "promotions": [
        {
            "id": 1,
            "name": "pre_promotion",
            "apply_url": "http://hive5.io/promotions",
            "display_url": "http://hive5.io/promotions",
            "order":1
        }
     ],
     "completed_missions": {
        "mission_key_1": "2013-12-01T14:00:11",
        "mission_key_2": "2013-12-01T14:00:11"
     }
    }
}

Social Platform 연동 계정 변경

플레이어와 연동된 Social Platform을 변동한다. 익명 로그인 후 페이스북 계정으로 변경한다거나 또는 구글 계정에서 페이스북 계정으로 변경하는 등의 social platform 연동을 변경한다.

  • Path: /:version/auth/switch
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON
Name Type Description
platform String Social Platform 종류. 'kakao', 'naver', 'facebook', 'google' 중의 하나.
platform_user_id String Social platform 의 user_id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

사용 가능한 nickname 조회

플레이어의 nickname으로 사용가능한지 조회한다. nickname은 게임내 모든 사용자에 대해서 unique해야 한다.

  • Path: /:version/settings/nickname/is_available/:nickname
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
nickname String 사용하고자하는 nickname
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Nickname 설정하기

플레이어의 nickname을 설정한다. nickname은 게임내 모든 사용자에 대해서 unique해야 한다.

  • Path: /:version/settings/nickname/set
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON
Name Type Description
nickname String 변경하고자 하는 nickname
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Push 토큰 등록

Push 메시지를 보내기 위한 push token을 등록한다. 실제 push message는 Partner를 통해서 발송한다.

  • Path: /:version/pushes/register
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON
Name Type Description
push_platform String 'gcm' 또는 'apns'
push_token String 외부 push platform으로부터 발급받은 token
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Push 받기 on/off

Push 메시지를 받는 것을 on 또는 off하는 기능 보내기 위한 push token을 등록한다. 실제 push message는 Partner를 통해서 발송한다.

  • Path: /:version/pushes/activate/:flag
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
flag Boolean 'true' or 'false'
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

약관 동의

유저의 약관 동의를 처리합니다.

  • Path: /:version/agreements

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Parameter: 없음

  • Request Body: JSON JSON Object에 json으로 json key는 약관의 이름, json value에는 약관의 버전 명시

  • Request Body Example:

{
	"general_agreement": "1.1.1",
  "partnership_agreement": "0.1"
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

약관 동의 기록 조회

처리된 약관 동의 내역을 조회합니다.

  • Path: /:version/agreements

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: GET

  • Parameter: 없음

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
agreements JSON data 사용자가 동의한 약관에 대한 정보
key는 약관의 이름, value는 다음과 같다.
Name Type Description
version String 약관의 버전
agreed_at String 약관을 동의한 시간
형식은 "yyyy-MM-dd'T'HH:mm:ss"와 같으며, 항상 UTC 시간임

회원 탈퇴

서버에 저장된 사용자 정보를 삭제하고 회원 탈퇴 처리

  • Path: /:version/auth/delete

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Parameter: 없음

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mail 생성

  • Path: /:version/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
content String 내용
platform Option[String] 친구에게 보내고자 할 때 친구의 platform을 세팅한다.
platform_user_id Option[String] 친구에게 보내고자 할 때 친구의 platform_user_id을 세팅한다.
tags Option[Array of String] 메일에 tag를 붙이고자 할때 세팅. 복수개의 tag를 세팅할 수 있고, 생략 가능

*Request Body Example:

{
    "content": "mail입니다.",
    "platform": "none",
    "platform_user_id": "1231233",
    "tags": [
        "notice",
        "event"
    ]
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id Number 추가된 mail의 id

Mail 내용 얻어오기

메일의 내용을 얻어온다.

  • Path: /:version/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
order Option[String] 'asc' 또는 'dec' 중 하나. asc이면 오래된 것부터, dec이면 최신 것부터 가져온다.
default는 asc
after_mail_id Option[Number] after_mail_id 다음 것부터 얻어온다
limit Number 가져올 최대 개수. default는 10개
tag Option[String] 특정 tag가 붙은 것의 메일만 얻어오고자 할때 세팅
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
mails JSON Array
Name Type Description
id Number mail의 id
content String json 형식을 따르는 임의의 데이터.
reward_id Option[Number] 이 mail 아이템과 관련된 보상(reward) 아이템이 있는 경우 그것의 id
tags Array of String 메일의 tag 목록. 없으면 empty
  • Response Example:
{
    "result_code": 0,
    "mails": [
        {
            "id": 1235324,
            "content": "\"title\": \"선물이도착했어요~\",\"body\": \"별이1개지급되었습니다\", \"read\": true, \"expires_at\":\"2013/11/30T00: 00: 00+0000\" }",
            "reward_id": 542
        },
        {
            "id": 1235320,
            "content": "\"title\": \"메시지가 왔습니다~~\",\"body\": \"1월1일 점수가 리셋됩니다.\", \"read\": true, \"expires_at\":\"2013/11/30T00: 00: 00+0000\" }"
        }
    ]
}

Mail 개수 얻어오기

  • Path: /:version/mails/count
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
after_mail_id Option[Number] after_mail_id 다음 것부터 얻어옴
order Option[String] 'asc' 또는 'dec' 중 하나. after_mail_id가 있을 때, asc이면 오래된 것부터, dec이면 최신 것부터 개수를 센다.
default는 asc
tag Option[String] 특정 tag가 붙은 것 듯의 개수만 알고 싶을 때 세팅
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
count Number 메일 개수

Mail 아이템 1개 내용 업데이트

  • Path: /:version/mails/update/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    content String 새롭게 갱신할 데이터

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mail 아이템 1개 삭제

  • Path: /:version/mails/delete/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:없음

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mail 아이템 모두 삭제

해당 user_id에 속한 mail을 모두 삭제한다. 현재는 1,000개까지 한번에 삭제하는 걸로 제한이 걸려있으므로 유의.

  • Path: /:version/mails/delete_all

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Parameter: 없음

  • Request Body:

    Name Type Description
    from_mail_id Option[Number] 삭제 시작할 메일의 id. 이 값이 없으면 처음 메일부터 삭제
    to_mail_id Option[Number] 삭제 끝낼 메일의 id. 이 id 포함. 이 값이 없으면 마지막 메일까지 삭제

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mail에 Tag 추가

  • Path: /:version/mails/:id/add_tags
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id Number mail의 id
  • Request Body:
Name Type Description
tags Array of String 메일에 추가하고자 하는 tag 목록

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음
    tags Array of String 메일의 모든 tag 목록

Mail에서 Tag 삭제

  • Path: /:version/mails/:id/remove_tags
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id Number mail의 id
  • Request Body:
Name Type Description
tags Array of String 메일에서 삭제 하는 tag 목록

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음
    tags Array of String 메일의 모든 tag 목록

Mission 수행 완료

미션을 완료하는 경우 호출한다. 미리 Partner를 통해 정의된 보상이 지급되고, 메일이 송신된다.

  • Path: /:version/missions/complete/:key

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Parameter:

    Name Type Description
    key String 수행 완료할 mission의 key.
    파트너를 통해 먼저 정의되어 있어야 한다.

  • Request Body: 없음

  • Response Body:

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음
    reward_id Number 미션이 완료되어 생성된 reward의 id. 'change_immediately'가 true이면 null.
    mail_id Number 미션이 완료되어 발송된 mail의 id. 'change_immediately'가 true이면 null.

완료한 Mission 조회

  • Path: /:version/missions/completed

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: GET

  • Request Parameter: 없음

  • Response Body: JSON으로 다음과 같은 결과값 리턴

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
completed_missions JSON Object JSON object의 key는 mission key이고, value는 미션 완료한 시간
시간 형식은 "yyyy-MM-dd'T'HH:mm:ss
  • Response Example:
{
    "result_code": 0,
    "completed_missions": {
        "mission_key_1": "2013-12-01T14:00:11",
        "mission_key_2": "2013-12-01T14:00:11"
    }
}

Reward 조회

  • Path: /:version/rewards/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter: 없음
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
reward JSON Object
Name Type Description
call JSON Object 보상의 결과를 실행할 procedure
Name Type Description
procedure String procedure 이름
params JSON Object procedure 호출 시 전달되는 params
invalidated_at Option[String] valid한 경우에는 null
mail_id Option[Number] 관련된 메일이 있는 경우. 없으면 null
purchase_id Option[Number] 관련된 purchase가 있는 경우

Reward 아이템 사용

reward를 사용하여, reward 변화 조건을 실행하게 만든다. 한번 사용된 reward 아이템은 두번 사용하지 못하도록 invalidate된다.

  • Path: /:version/rewards/apply/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    delete_mail Boolean 보상과 관련된 mail이 있는 경우 삭제. default는 false

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음
    call_return JSON Object 보상과 연결된 call을 실행한 결과

Reward 아이템 모두 사용

현재 사용자에게 유요한 reward 아이템을 모두 사용한다.

  • Path: /:version/rewards/apply_all

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    delete_mail Boolean 보상과 관련된 mail이 있는 경우 삭제. default는 false

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Reward 아이템 무효화

  • Path: /:version/rewards/invalidate/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    delete_mail Boolean 보상과 관련된 mail이 있는 경우 삭제. default는 false

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Leaderboard에 Score 제출

  • Path: /:version/leaderboards/:leaderboard_key/scores/:score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: 없음
  • Request Parameter:
Name Type Description
leaderboard_key String 리더보드 key
score Number 새로 득점한 값
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
updated_at Option[String] 최고 기록이 경신되어 업데이트 되었으면 시간이 있고, 그렇지 않으면 null임

Leaderboard에서 순위 목록 얻어오기

순위 목록은 최대 10개까지만 얻어올 수 있다.

  • Path: /:version/leaderboards/:leaderboard_key/scores
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_key String 조회하고자 하는 leaderboard key
object_class Array of String score 정보에 포함될 사용자별 object들의 class 이름
rank_min Number 조회하고자 하는 순위 목록의 시작 순위 (1에서 부터 시작되는 순위)
rank_max Number 조회하고자 하는 순위 목록의 끝 순위 (가져올 수 있는 최대 개수는 20개)
range_min Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최소 값
range_max Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최대 값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores JSON Array Score의 JSON Array 객체.
Score에 대해서는 'Score' 참고

Score

Score JSON Object는 다음과 같다.

Name Type Description
platform String platform
platform_user_id String platform user id
value Number score 값
rank Number 순위
objects Array of JSON object Object 참고

  • Response Example:

    Request를 다음과 같이 object_class를 세팅해서 보내면 response는 다음처럼 나올 수 있다.

    http://[server_url]/:version/leaderboard/3312/scores?object_class=candy&range_min=0&range_max=100000&rank_min=31&rank_max=20

{
    "result_code": 0,
    "scores": [
        {
            "platform": "none",
            "platform_user_id": "234331",
            "value": 10002,
            "rank": 31,
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        },
        {
            "platform": "none",
            "platform_user_id": "114331",
            "value": 9900,
            "rank": 32,
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        },
        {
            "platform": "none",
            "platform_user_id": "44332",
            "value": 10002,
            "rank": 33,
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        }
    ]
}

Leaderboard에서 내 순위 정보 얻어오기

  • Path: /:version/leaderboards/:leaderboard_key/my_score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_key String 조회하고자 하는 leaderboard key
range_min Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최소 값
range_max Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최대 값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores_count Number 해당 range내의 스코어 목록의 전체 개수
value Option[Number] 내 점수. 단, 기존에 점수가 없는 경우 null
rank Option[Number] 내 순위. 단, 기존에 점수가 없는 경우 null

Social 랭킹 가져오기

나와 친구들의 점수 정보를 가져온다.

  • Path: /:version/leaderboards/:leaderboard_key/social_scores
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameter:
Name Type Description
leaderboard_key String leaderboard의 key
object_class Array of String score 정보에 포함될 사용자별 object들의 class 이름
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores JSON Array
Name Type Description
value Number 점수
rank Number 등수. 1부터 시작
scored_at String 점수를 기록한 시간. 형식은 "yyyy-MM-dd'T'HH:mm:ss"
platform String platform
platform_user_id String platform user_id
objects Array of JSON object
  • Response Body Example:
{
    "result_code": 0,
    "last_prized_at": "2013-11-06T13:58:18",
    "scores": [
        {
            "platform": "none",
            "platform_user_id": "user_id_99",
            "value": 17524,
            "rank": 1,
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        },
        {
            "platform": "none",
            "platform_user_id": "user_id_98",
            "value": 17523,
            "rank": 2,
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        }
    ]
}

친구들의 object 얻어오기

친구들의 object를 얻어온다.

  • Path: /:version/friends/info
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameter:
Name Type Description
platform_user_id Array of String 얻어오고자 하는 친구들의 platform user id
platform Option[String] 친구들이 속한 platform
object_class Array of String object의 class
  • Request URI Example:

https://[server-url]/:version/friends/info?platform_user_id=1235342&platform_user_id=222&object_class=candy

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
friends JSON Array
Name Type Description
platform String platform
platform_user_id String platform user_id
objects Array of JSON object
  • Response Body Example:
{
    "result_code": 0,
    "friends": [
        {
            "platform": "none",
            "platform_user_id": "user_id_99",
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        },
        {
            "platform": "none",
            "platform_user_id": "user_id_98",
            "objects": [
                {
                    "class":"candy",
                    "value":"200"
                }
            ]
        }
    ]
}

네이버 빌링 처리 process

네이버 빌링 처리 process

네이버 상품 구매 등록

상품을 구매하기 전에, 구매를 위한 id를 발급 받는다. 구매를 처리하기 전에 partner를 통해서 product를 등록해야 한다.

  • Path: /:version/naver_purchases
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
product_code String 네이버에 등록된 상품의 code
payment_sequence String 네이버 결제 완료후 전달받은 paymentSeq 값
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id Number 구매 id

네이버 상품 구매 완료 처리

결제 일련번호를 확인하고, 정상 결제이면 앞서 설정된 유료 아이템 변경 값을 적용한다.

  • Path: /:version/naver_purchases/complete/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
  • Request Body:
Name Type Description
list_price Number 원래 상품의 가격
purchased_price Number 실제 구매한 가격
currency String 'KRW', 'USD', 'JPY' 중 하나. default는 'KRW'
params JSON Object 구매 완료 procedure에 전달할 params
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
call_return JSON Object 구매 완료에 연동된 procedure가 있는 경우, 이 procedure의 결과 값

네이버 구매 상태 확인

구매 id를 이용해 상태를 조회할 수 있다. 네이버 구매 시작 API를 호출했다면 결과의 이 API의 결과는 status가 "created"가 되고, 네이버 구매 완료 처리 API까지 호출했다면, status는 "completed"가 된다.

  • Path: /:version/naver_purchases/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
purchase JSON Object
Name Type Description
id Number 구매 id
product_code String 네이버에 등록된 상품의 code
status String 구매의 현재 상태. 구매시작만 호출해 성공했으면 "created", 구매완료까지 호출해 성공했으면 "completed"

Google 구매 시작

상품을 구매하기 전에, 구매를 위한 id를 발급 받는다. 구매를 처리하기 전에 partner를 통해서 product를 등록해야 한다.

  • Path: /:version/google_purchases
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
product_code String Google에 등록된 상품의 code
receiver_platform Option[String] 구매한 것을 친구에게 선물하고자 할때 사용. 선물할 사용자의 platform
receiver_platform_user_id Option[String] 구매한 것을 친구에게 선물하고자 할때 사용. 선물할 사용자의 platform user id
mail_for_receiver Option[String] 친구에게 선물할 때 메일을 같이 보내려고 할 때, 메일의 content를 세팅
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id Number 구매 id

Google 구매 완료 처리

결제 일련번호를 확인하고, 정상 결제이면 앞서 설정된 유료 아이템 변경 값을 적용한다.

  • Path: /:version/google_purchases/complete/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
  • Request Body:
Name Type Description
params JSON Object 구매 완료 procecure에 전달할 params
purchase_data String Google IAP API에서 응답받은 내용 중 purchase data
signature String Google IAP API에서 응답받은 내용 중 signature
list_price Number 원래 상품의 가격
purchased_price Number 실제 구매한 가격
currency String 'KRW', 'USD', 'JPY' 중 하나. default는 'KRW'
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
call_return JSON Object 구매와 연결된 procedure의 실행(call) 결과

Google 구매 상태 확인

구매 id를 이용해 상태를 조회할 수 있다. Google 구매 시작 API를 호출했다면 결과의 이 API의 결과는 status가 "created"가 되고, Google 구매 완료 처리 API까지 호출했다면, status는 "completed"가 된다.

  • Path: /:version/google_purchases/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
purchase JSON Object
Name Type Description
id Number 구매 id
product_code String Google에 등록된 상품의 code
status String 구매의 상태. 구매시작만 호출해 성공했으면 "created", 구매완료까지 호출해 성공했으면 "completed"

Apple 구매 시작

상품을 구매하기 전에, 구매를 위한 id를 발급 받는다. 구매를 처리하기 전에 partner를 통해서 product를 등록해야 한다.

  • Path: /:version/apple_purchases
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
product_code String Apple에 등록된 상품의 code
receiver_platform Option[String] 구매한 것을 친구에게 선물하고자 할때 사용. 선물할 사용자의 platform
receiver_platform_user_id Option[String] 구매한 것을 친구에게 선물하고자 할때 사용. 선물할 사용자의 platform user id
mail_for_receiver Option[String] 친구에게 선물할 때 메일을 같이 보내려고 할 때, 메일의 content를 세팅
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id Number 구매 id

Apple 구매 완료 처리

정상 결제이면 앞서 설정된 유료 아이템 변경 값을 적용한다.

  • Path: /:version/apple_purchases/complete/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
params JSON Object 구매 완료 procecure에 전달할 params
  • Request Body:
Name Type Description
receipt String Apple 결제 후 받은 'receipt'. Base 64 Encoding이 되어 있어야 함
애플의 [관련문서](https://developer.apple.com/library/ios/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html#//apple_ref/doc/uid/TP40010573-CH104-SW1) 참고
is_sandbox Option[Boolean] receipt가 apple의 sandbox용 일 경우에 이값을 true로 한다. default는 false
list_price Number 원래 상품의 가격
purchased_price Number 실제 구매한 가격
currency String 'KRW', 'USD', 'JPY' 중 하나. default는 'KRW'
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
call_return JSON Object 구매와 연결된 procedure의 실행(call) 결과

Apple 구매 상태 확인

구매 id를 이용해 상태를 조회할 수 있다. Apple 구매 시작 API를 호출했다면 결과의 이 API의 결과는 status가 "created"가 되고, Apple 구매 완료 처리 API까지 호출했다면, status는 "completed"가 된다.

  • Path: /:version/apple_purchases/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
id Number 구매 등록시 발급 받은 구매 id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
purchase JSON Object
Name Type Description
id Number 구매 id
product_code String Apple에 등록된 상품의 code
status String 구매의 현재 상태. 구매시작만 호출해 성공했으면 "created", 구매완료까지 호출해 성공했으면 "completed"

친구 목록 업데이트

친구 목록을 업데이트 한다.

  • Path: /:version/friends/update
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
group String 업데이트할 친구 목록의 group
platform Option[String] 친구들이 속한 platform
friends Array of String 친구들의 platform_user_id 목록
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

친구 목록에 추가

친구 목록에 추가 한다.

  • Path: /:version/friends/add
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
group String 업데이트할 친구 목록의 group
platform Option[String] 친구들이 속한 platform
friends Array of String 추가할 친구들의 platform_user_id 목록
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

친구 목록에서 삭제

친구 목록에 삭제한다.

  • Path: /:version/friends/remove
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
group String 업데이트할 친구 목록의 group
platform Option[String] 친구들이 속한 platform
friends Array of String 삭제할 친구들의 platform_user_id 목록
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

친구 목록 조회

친구 목록을 조회 한다.

  • Path: /:version/friends
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
group String 특정 group 내에서 조회하고자 할 경우
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
friends Array of String 친구들의 platform_user_id 목록

Configuration 데이터 얻어오기

Partner를 통해 미리 정의해둔 configuration을 얻어올 수 있다.

  • Path: /:version/configurations

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: GET

  • Parameters:

    Name Type Description
    key Array of String 얻어오고자 아는 Configuration 데이터의 key 목록

  • Request URI Example:

https://[server-url]/:version/configurations?key=app_version&key=agreement_version

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
configs JSON Object
key String data의 key
value String data의 value
  • Response Body Example:
{
    "result_code": 0,
    "configs": {
        "key1": "value1",
        "key2": "value2"
    }
}

Analytics 로그 API

분석을 위해 로그를 쌓기 위한 API이다. 로그가 쌓인 후 분석은 별도로 바이트코드랩과 협의하여 처리하여야 한다.

  • Path: /:version/logs
  • Authentication Header: X-APP-KEY
  • Method: POST
  • Request Body: JSON
Name Type Description
event_type String 어떠한 종류의 event인지 구분하기 위한 값. 클라이언트에서 정해서 사용.
data String 로그 데이터
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

플랫폼 계정 생성

플랫폼 계정을 생성한다

  • Path: /:version/accounts
  • Authentication Header: X-PLATFORM-KEY
  • Method: POST
  • Request Body: JSON
Name Type Description
name String 계정의 이름. unique해야함
password String
display_name Option[String] display를 위한 이름. 생략된 경우 'name'의 것을 사용한다.
email Option[String] 계정의 email
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id String 사용자 id(platform_user_id)

플랫폼 계정으로 사용가능한 이름 확인

플랫폼 계정을 생성하기 전에 사용가능한 이름인지 확인한다.

  • Path: /:version/accounts/is_avaliable_name/:name
  • Authentication Header: X-PLATFORM-KEY
  • Method: GET
  • Request Body: 없음
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

플랫폼 계정으로 사용가능한 이메일 확인

플랫폼 계정을 생성하기 전에 사용가능한 이메일인지 확인한다.

  • Path: /:version/accounts/is_avaliable_email/:email
  • Authentication Header: X-PLATFORM-KEY
  • Method: GET
  • Request Body: 없음
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

플랫폼 계정 인증

플랫폼 계정에 대해 인증을 한다.

  • Path: /:version/accounts/authenticate
  • Authentication Header: X-PLATFORM-KEY
  • Method: POST
  • Request Body: JSON
Name Type Description
name String 계정의 이름
password String
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id String 사용자 id(platform_user_id)

App 관련 데이터 삭제하기 (for test)

테스트를 위해서 app 관련 데이터를 삭제한다. 삭제 대상은 다음과 같다.

  1. player_shard에서 관리하는 데이터(objects, mails, ...)
  2. app_shard에서 관리하는 데이터(scores, purchase 기록, ...)

이 API는 beta와 production phase에서는 동작하지 않는다.

  • Path: /:version/apps/reset_for_test

  • Authentication Header: X-APP-KEY

  • Method: POST

  • Request Body: 없음

  • Response Body: Json

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Platform 관련 데이터 삭제하기 (for test)

테스트를 위해서 platform 관련 데이터를 삭제한다. 삭제 대상은 다음과 같다.

  1. accounts 정보

이 API는 beta와 production phase에서는 동작하지 않는다.

  • Path: /:version/platforms/reset_for_test

  • Authentication Header: X-PLATFORM-KEY

  • Method: POST

  • Request Body: 없음

  • Response Body: Json

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Coupon 적용(apply)하기

기 발급된 coupon을 적용한다.

  • Path: /:version/coupons/:serial/apply
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Parameters:
    Name Type Description
    serial String 쿠폰의 serial
  • Response:
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
call_return Option[JSON Object] coupon이 포함된 campaign에서 정의된 call을 실행한 결과. campaign에 call이 null이 었을 경우에는 이 값도 null이 됨

Error Code

Value Description
0 Success
1001 Invalid parameter
1002 Data dose not exist
2101 Invalid reward
2201 Invalid purchase status
2202 Invalid payment sequence
2203 Invalid apple receipt
2204 Invalid google purchase data
2205 Invalid google signature
2206 No google iap public key is registered
2207 Invalid google iap public key
2208 No kakao app auth info
2303 No iap conversion
2401 Mission already completed
2504 Expired coupon
2505 The player has already consumed the coupon
2506 The coupon is no more applicable
2701 Not friend
2702 The item is not able to gift
2703 The item cannot gift because it has recently gifted
2704 Too many count to gift
2705 Too many friends
2801 Already existing nickname
2802 Forbidden nickname
3001 Javascript Exception: Procedure(javascript) 실행 때 예외 발생. 내용은 result_message를 참조
3101 Undefined Procedure: 정의되지 않은 프로시저
3102 Protected Procedure: REST로 외부에서 직접 호출할 수 없는 프로시져
3103 Protected Method: ClassDescriptor에서 protected-method로 지정된 메소드를 REST로 호출
3104 Undefined Library: 정의되지 않은 라이브러리
3105 Undefined Library Method: 해당 라이브러리에 내에 정의되지 않은 method
3201 Object Not Found: load/save/destroy의 대상 객체를 찾을 수 없다
3202 Can Not Destroy Singleton: 싱글턴이라 destroy가 불가능
3203 Invalid object field
3204 Too many object fields
3205 Invalid object
3301 Data Table Not Found: 정의된 Data Table이 없다
3401 Invalid Return: return 불가능한 타입이 포함됨
3501 Undefined AppData Key: 정의되지 않은 HAppCounter, HAppDictionary, HAppQueue Key
3901 Execution Timeout: 수행 시간 타임아웃
3902 Stack overflow, 스택사이즈 초과
3903 Unsupported Library or Function: 지원되지 않는 라이브러리/함수
3904 Unsupported Data Type: 지원되지 않는 데이터 형식
4001 Already existing platform user name
4002 Already existing platform user email
4003 Invalid name or password
5001 Invalid push payload
8001 The user has been disabled
8002 The session key is invalid
9001 Internal Error: invalid app configuration
9002 Internal Error: invalid service name
9003 Internal Error: invalid job item
9999 Unknown error
Add a custom footer
Add a custom sidebar

Clone this wiki locally