Skip to content

Version 6

Jump to bottom Edit New page
Artie Choi edited this page Oct 12, 2015 · 57 revisions

Status

Draft

특징

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

서버 정보

종류 Host
Alpha http://alpha.hornet.hive5.io
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/log_in

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

  • Method: POST

  • Response Body: JSON

Name Type Description
user JSON object(Optional)
Name Type Description
platform String Social Platform 종류. 'kakao', 'naver', 'facebook', 'google' 등이 될 수 있다. 콘솔의 플랫폼 연동 메뉴에서 미리 사용하려는 auth platform을 추가시켜야 한다.
id String Social platform 의 user id
user를 보내지 않으면, platform을 'anonymous'으로 하여, hive5에서 id를 발급한다.
platform_params JSON object(Optional) user의 platform을 지정할 경우, 해당 platform의 인증 정보를 지정한다. 이 인증 정보의 형식은 콘솔의 auth platform 연동 메뉴를 참조한다.
os String(Optional) 'android' 또는 'ios'
build String(Optional) client의 build version. script에서 BUILD라는 상수로 활용할 수 있다. client version에 따라 분기가 필요한 경우 사용할 수 있다.
locale String(Optional) 로케일 정보. 언어는 ISO 639-1 형식으로, 국가는 ISO 3166-1 형식으로 en-us, ko-kr 과 같이 지정한다.
  • Request Body Example:
{
	"user": {
    	"platform":"kakao",
        "id":"3432983"
    },
    "os":"android",
    "locale":"en-us"
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
session_key String session key
user JSON object
Name Type Description
platform String 로그인 사용자의 platform
id String 로그인 사용자의 id. platform에 대해 unique하다. platform이 'anonymous'인 경우 hive5에서 id를 발급한다.
nickname String 설정한 nickname (Nickname 설정 참조)
new_mail_count Number 지난 로그인 이후 도착한 메일 수
extras JSON data 세팅된 추가데이터. (플레이어 추가데이터 설정하기 참조)
  • Response Body Example:
{
    "result_code": 0,
    "access_token": "iuojsdof-SDFSDF-sdf24-123",
    "user" : {
    	"platform":"anonymous",
        "id":"213345435"
    },
    "nickname": null,
    "new_mail_count": 1,
    "extras": {
        "agreement": {
            "version": "1.1.0",
            "agreed_at": "2013-10-05T14:19:53"
        },
        "email": "james@hive5.io"
    }
}

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
user String
Name Type Description
platform String Social Platform 종류. 'kakao', 'naver', 'facebook', 'google' 등이 올 수 있다. 콘솔의 플랫폼 연동 메뉴에서 미리 사용하려는 auth platform을 추가시켜야 한다.
id String Social platform 의 user id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

사용 가능한 nickname 조회

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

  • Path: /:version/players/me/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 String(Optional) 실패한 경우에 메시지 있을 수 있음
available Boolean 사용할 수 있는 nickname인지의 여부

Nickname 설정하기

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

  • Path: /:version/players/me/nickname
  • 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 String(Optional) 실패한 경우에 메시지 있을 수 있음

플레이어 추가 데이터 세팅하기

플레이어의 추가 데이터를 세팅합니다. 약관동의 내역이나, 이메일 등의 정보를 자유로운 형식으로 저장할 수 있으며, 로그인 결과에 이 데이터가 포함됩니다.

  • Path: /:version/players/me/extras
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Parameter: 없음
  • Request Body: JSON
Name Type Description
extras JSON 추가데이터
JSON Object에 json으로 json key는 약관의 이름, json value에는 약관의 버전 명시
  • Request Body Example:
{
	"extras": {
    	"agreement": {
            "version": "1.1.0",
            "agreed_at": "2013-10-05T14:19:53"
        },
        "email" : "james@hive5.io"
    }
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

플레이어 추가데이터 가져오기

세팅된 플레이어 추가데이터를 가져옵니다.

  • Path: /:version/players/me/extras

  • 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
extras JSON 저장된 추가데이터
  • Example:
{
    "result_code": 0,
    "extras": {
    	"agreement": {
            "version": "1.1.0",
            "agreed_at": "2013-10-05T14:19:53"
        },
    	"email": "james@hive5.io"
    }
}

회원 탈퇴

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

  • Path: /:version/auth/unregister

  • 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 String(Optional) 실패한 경우에 메시지 있을 수 있음

Push 토큰 등록

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

  • Path: /:version/settings/push_tokens/update
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON
Name Type Description
platform String push platform으로 Android의 경우'gcm'이 되고, Apple의 경우 'apns'가 된다. 콘솔의 플랫폼 연동 메뉴에서 미리 사용하려는 push platform을 추가시켜야 한다.
token String push platform으로부터 발급받은 token
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

Push 받기 허용

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

  • Path: /:version/settings/pushes/activate

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

  • Method: POST

  • Request Parameter:

  • Response Body: JSON

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

Push 받기 거부

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

  • Path: /:version/settings/pushes/deactivate

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

  • Method: POST

  • Request Parameter:

  • Response Body: JSON

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

Mail 생성

  • Path: /:version/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
content String 내용
user JSON object(Optional) 친구에게 보낼 때는 친구의 platform과 user id 정보를 설정한다
Name Type Description
platform String 친구에게 보낼 때 친구의 platform
id String 친구의 user id
extras JSON(Optional) 추가 데이터. 자유로운 형식으로 추가할 수 있다. 지정하지 않으면 null.
tags Array of String(Optional) 메일에 tag를 붙이고자 할때 세팅. 복수개의 tag를 세팅할 수 있고, 생략 가능

*Request Body Example:

{
    "content": "mail입니다.",
    "user" : {
    	"platform": "anonymous",
        "id": "1231233"
    },
    "extras": {"icon":"130", "count":5},
    "tags": [
        "notice",
        "event"
    ]
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
id String 추가된 mail의 id

Mail 내용 얻어오기

메일의 내용을 얻어온다.

  • Path: /:version/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
order String(Optional) 'asc' 또는 'dec' 중 하나. asc이면 오래된 것부터, dec이면 최신 것부터 가져온다.
default는 asc
offset Number(Optional) 가져올 위치를 지정한다.
limit Number 가져올 메일의 개수로 20개가 최대다. default도 20개
tag String(Optional) 특정 tag가 붙은 것의 메일만 얻어오고자 할때 세팅
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
mails JSON Array
Name Type Description
id String mail의 id
content String 메일의 내용
extras JSON 추가 데이터
reward Boolean 이 mail에 reward가 있는지의 여부. 보상이 있는 경우 accept를 하면 지정된 스크립트가 실행된다(HMail 참조). 한 번 보상을 받게 되면 다시 false가 된다.
reward_accepted_at String(Optional) 보상을 받은 경우, 받은 날짜와 시간.
tags Array of String 메일의 tag 목록. 없으면 empty
  • Response Example:
{
    "result_code": 0,
    "mails": [
        {
            "id": "1235324",
            "content": "별이1개지급되었습니다",
            "extras": { "title": "선물이도착했어요~", "expires_at":"2013/11/30T00: 00: 00+0000" },
            "reward": true
        },
        {
            "id": "1235320",
            "content": "1월1일 점수가 리셋됩니다.",
            "extras": null,
            "reward": false
        }
    ]
}

Mail 개수 얻어오기

  • Path: /:version/mails/count
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
tag String(Optional) 특정 tag가 붙은 것 듯의 개수만 알고 싶을 때 세팅
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
count Number 메일 개수

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

  • Path: /:version/mails/:id

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

  • Method: PUT (PUT으로 전송하기가 어려운 경우에는 POST로 전송하되 쿼리스트링에 _method=PUT을 추가하면 동일한 동작을 수행한다)

  • Request Body:

    Name Type Description
    content String 새롭게 갱신할 메일 내용
    extras JSON 새롭게 갱신할 추가 데이터

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

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

Mail 아이템 1개 삭제

  • Path: /:version/mails/:id

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

  • Method: DELETE (DELETE로 전송하기가 어려운 경우에는 POST로 전송하되 쿼리스트링에 _method=DELETE를 추가하면 동일한 동작을 수행한다)

  • Request Body:없음

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

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

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 Number(Optional) 삭제 시작할 메일의 id. 이 값이 없으면 처음 메일부터 삭제
    to_mail_id Number(Optional) 삭제 끝낼 메일의 id. 이 id 포함. 이 값이 없으면 마지막 메일까지 삭제

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

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

오래된 Mail 삭제

특정 일 수 이전의 메일을 모두 삭제한다.

  • Path: /:version/mails/delete_older_than/:days

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

  • Method: POST

  • Request Parameter:

    Name Type Description
    days Number 일수를 지정한다. 1이라면, 1일 이전의 메일을 모두 삭제한다.

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

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

특정 개수를 초과한 Mail 삭제

메일함의 최대 용량 이상의 메일을 모두 삭제한다. 오래된 메일부터 삭제된다.

  • Path: /:version/mails/delete_over_limit/:limit

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

  • Method: POST

  • Request Parameter:

    Name Type Description
    limit Number 최대 보관 메일 개수를 지정한다. 100이라면, 최신 메일 100개만 보관하고 그 이전의 메일을 모두 삭제한다.

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

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

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 String 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
    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 String 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
    tags Array of String 메일의 모든 tag 목록

Mail의 reward 받기

mail에 reward가 첨부된 경우 reward를 받는다. 실제로는 reward에 지정된 스크립트가 실행되는 것이며, reward의 생성슨 HMail.create()를 참조한다. 한번 받은 reward는 다시 받을 수 없다.

  • Path: /:version/mails/:id/rewards/accept

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

  • Method: POST

  • Request Parameter:

Name Type Description
id String mail의 id
  • Request Body:
Name Type Description
delete_mail Boolean(Optional) 보상을 받으면서 메일을 삭제할 때 true로 한다. 따로 지정하지 않으면 false.

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

    Name Type Description
    result_code Number Error Code 참고
    result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
    call_return JSON Object reward와 연결된 call을 실행한 결과

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 String(Optional) 실패한 경우에 메시지 있을 수 있음
    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 String(Optional) 실패한 경우에 메시지 있을 수 있음
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 String(Optional) 실패한 경우에 메시지 있을 수 있음
reward JSON Object
Name Type Description
call JSON Object 보상의 결과를 실행할 script
Name Type Description
script String script 이름
params JSON Object script 실행 시 전달되는 params
invalidated_at String(Optional) valid한 경우에는 null
mail_id Number(Optional) 관련된 메일이 있는 경우. 없으면 null
purchase_id Number(Optional) 관련된 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
    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 String(Optional) 실패한 경우에 메시지 있을 수 있음

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 String(Optional) 실패한 경우에 메시지 있을 수 있음

Leaderboard에 Score 제출

  • Path: /:version/leaderboards/:leaderboard_key/scores
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON
Name Type Description
score Number 새로 득점한 값
extras JSON(Optional) 추가 데이터. 이 값을 세팅하면, 목록을 가져올 때 이 데이터도 가져올 수 있다.
  • Request Parameter:
Name Type Description
leaderboard_key String 리더보드 key
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
updated_at String(Optional) 최고 기록이 경신되어 업데이트 되었으면 시간이 있고, 그렇지 않으면 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_key String score 정보에 포함될 사용자별 object의 key 이름. key가 여러개면 컴마(,)로 구분한다.
rank_min Number 조회하고자 하는 순위 목록의 시작 순위 (1에서 부터 시작되는 순위)
rank_max Number 조회하고자 하는 순위 목록의 끝 순위 (가져올 수 있는 최대 개수는 20개)
range_min Number(Optional) 특정 score 구간내의 목록으로 얻어오고자 할 때, 구간의 최소값
range_max Number(Optional) 특정 score 구간내의 목록으로 얻어오고자 할 때, 구간의 최대값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
scores JSON Array Score의 JSON Array 객체.
Score에 대해서는 'Score' 참고

Score

Score JSON Object는 다음과 같다.

Name Type Description
user JSON object
Name Type Description
platform String Social Platform
id String user id
value Number score 값
rank Number 순위
extras JSON submit때 세팅한 추가 데이터. 없으면 null
objects Array of JSON object Object 참고

  • Response Example:

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

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

{
    "result_code": 0,
    "scores": [
        {
        	"user": {
            	"platform": "anonymous",
	            "id": "234331"
            },
            "value": 10002,
            "rank": 31,
            "extras": null,
            "objects": [
                {
                    "_key":"candy",
                    "value":"200"
                }
            ]
        },
        {
        	"user": {
            	"platform": "anonymous",
	            "id": "114331"
            },
            "value": 9900,
            "rank": 32,
            "extras": null,
            "objects": [
                {
                    "_key":"candy",
                    "value":"200"
                }
            ]
        },
        {
        	"user": {
            	"platform": "anonymous",
	            "id": "44332"
            },
            "value": 10002,
            "rank": 33,
            "extras": null,
            "objects": [
                {
                    "_key":"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 Number(Optional) 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최소 값
range_max Number(Optional) 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최대 값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
scores_count Number 해당 range내의 스코어 목록의 전체 개수
value Number(Optional) 내 점수. 단, 기존에 점수가 없는 경우 null
rank Number(Optional) 내 순위. 단, 기존에 점수가 없는 경우 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_key Array of String score 정보에 포함될 사용자별 object의 key 이름. key가 여러개면 컴마(,)로 구분한다.
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
scores JSON Array
Name Type Description
value Number 점수
rank Number 등수. 1부터 시작
user JSON object
Name Type Description
platform String Social Platform
id String user id
extras JSON submit때 세팅한 추가 데이터. 없으면 null
objects Array of JSON object
  • Response Body Example:
{
    "result_code": 0,
    "scores": [
        {
        	"user": {
	            "platform": "anonymous",
    	        "id": "user_id_99"
            },
            "value": 17524,
            "rank": 1,
            "extras": null,
            "objects": [
                {
                    "_key":"candy",
                    "value":"200"
                }
            ]
        },
        {
        	"user": {
	            "platform": "anonymous",
    	        "id": "user_id_98"
            },
            "value": 17523,
            "rank": 2,
            "extras": null,
            "objects": [
                {
                    "_key":"candy",
                    "value":"200"
                }
            ]
        }
    ]
}

결제를 위한 구매 시작

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

  • Path: /:version/purchases
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
platform String Billing platform을 지정한다. "apple" 또는 "google"이 될 수 있는데, 콘솔의 플랫폼 연동 메뉴에서 미리 사용하려는 billing platform을 추가해야 한다.
platform_params JSON object(Optional) 해당 billing platform에 필요한 파라미터들을 지정한다. platform이 "apple", "google"은 불필요 하며 "naver"인 경우는 다음과 같다.
Name Type Description
payment_sequence String 네이버 결제 완료후 전달받은 paymentSeq 값
product_code String 마켓에 등록된 상품의 code
receiver JSON object(Optional)
Name Type Description
platform String 선물할 사용자의 social platform
id String 선물할 사용자의 user id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
id String 구매 id

결재 후 구매 완료 처리

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

  • Path: /:version/purchases/complete/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Parameter:
Name Type Description
id String 구매 등록시 발급 받은 구매 id
  • Request Body:
Name Type Description
platform String Billing platform을 지정한다. "apple" 또는 "google"이 될 수 있는데, 콘솔의 플랫폼 연동 메뉴에서 미리 사용하려는 billing platform을 추가해야 한다.
platform_params JSON object 해당 billing platform에 필요한 파라미터들을 지정한다. 콘솔의 플랫폼 연동 메뉴에서 자세한 정보를 확인할 수 있다.
platform이 "google"인 경우는 다음과 같다.
Name Type Description
purchase_data String Google IAP API에서 응답받은 내용 중 purchase data
signature String Google IAP API에서 응답받은 내용 중 signature
platform이 "apple"인 경우는 다음과 같다.
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 Boolean(Optional) receipt가 apple의 sandbox용 일 경우에 이값을 true로 한다. default는 false
platform이 "naver"인 경우는 이 필드가 불필요하다. 
  </td>
</tr>
list_price Number 원래 상품의 가격
purchased_price Number 실제 구매한 가격
currency String 'KRW', 'USD', 'JPY' 중 하나. default는 'KRW'
params JSON Object(Optional) 구매 완료 후 실행될 script에 전달할 추가적인 params
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
call_return JSON Object 구매와 연결된 script의 실행 결과

구매 상태 확인

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

  • Path: /:version/purchases/:id
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Request Parameter:
Name Type Description
id String 구매 등록시 발급 받은 구매 id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
purchase JSON Object
Name Type Description
id String 구매 id
product_code String 마켓에 등록된 상품의 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
friends Array of JSON object
Name Type Description
platform String 친구의 Social Platform
id String 친구의 user id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

친구 목록에 추가

친구 목록에 추가 한다.

  • 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
friends Array of JSON object
Name Type Description
platform String 친구의 Social Platform
id String 친구의 user id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

친구 목록에서 삭제

친구 목록에 삭제한다.

  • 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
friends Array of JSON object
Name Type Description
platform String 친구의 Social Platform
id String 친구의 user id
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음

친구 목록 조회

친구 목록을 조회 한다.

  • 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
friends Array of JSON object
Name Type Description
user String 친구의 user platform과 id
Name Type Description
platform String 친구의 Social Platform
id String 친구의 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 String(Optional) 실패한 경우에 메시지 있을 수 있음
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 String(Optional) 실패한 경우에 메시지 있을 수 있음

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 String(Optional) 실패한 경우에 메시지 있을 수 있음

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 String(Optional) 실패한 경우에 메시지 있을 수 있음

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 String(Optional) 실패한 경우에 메시지 있을 수 있음
call_return JSON Object(Optional) coupon이 포함된 campaign에서 정의된 call을 실행한 결과. campaign에 call이 null이 었을 경우에는 이 값도 null이 됨

Data Table 가져오기

콘솔에서 등록된 Data Table을 JSON 형태로 가져온다.

  • Path: /:version/data_table/:name

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

  • Method: GET

  • Parameters:

    Name Type Description
    name String Data Table 이름
    revision Number(Optional) 테이블 내용을 받을 때, response 내용중 revision 값을 받게 된다. 이 값을 파라미터로 추가하면 테이블이 변경됐을 경우에만 내용을 받아온다. 테이블 내용을 클라이언트에 caching할 경우 사용할 수 있다. 테이틀 내용을 수정할 때 마다 revision 값이 증가된다.

  • Response:

Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
up_to_date Boolean request때 넘긴 revision과 가져올 Data Table의 revision이 동일한 경우에 true가 되며, 이 때에는 아래의 data와 revision은 따로 리턴되지 않는다.
data JSON Array(Optional) Data Table에 정의된 내용. revision이 일치한 경우에는 null로 리턴된다.
revision Number(Optional) 가져온 table 내용에 대한 revision(request 파라미터 참조)

Forum 글 가져오기

Forum에 등록된 글들을 가져온다.

  • Path: /:version/forums/:forum_key/threads

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

  • Method: GET

  • Request Parameter:

    Name Type Description
    forum_key String 글을 쓸 forum의 key
    order String(Optional) 가져올 글의 순서를 지정한다. "asc"는 오래된 것부터, "dec"는 새로운 것 부터 가져온다. 지정하지 않으면 "dec"이다.
    offset Number(Optional) 가져올 글의 offset을 지정한다. 지정하지 않으면 0이다.
    limit Number(Optional) 가져올 개수를 지정. 지정하지 않으면 20이다.

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
threads JSON Array
Name Type Description
id String thread id
title String 제목
content String 내용
extras JSON 추가 데이터
created_at String 등록일

Forum 글 개수

Forum에 등록된 글의 총 개수를 가져온다.

  • Path: /:version/forums/:forum_key/threads/count

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

  • Method: GET

  • Request Parameter:

    Name Type Description
    forum_key String 글을 쓸 forum의 key

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
count Number 글의 개수

Forum 글 쓰기

Forum에 글을 쓴다.

  • Path: /:version/forums/:forum_key/threads

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

  • Method: POST

  • Request Parameter:

    Name Type Description
    forum_key String 글을 쓸 forum의 key

  • Request Body:

Name Type Description
title String 제목
content String 내용
extras JSON(Optional) 추가 데이터. 자유로운 형식으로 추가할 수 있다.

*Request Body Example:

{
	"title": "글 제목",
    "content": "글 내용입니다.",
    "extras": {
    	"data": 123,
        "attr": [1, 2, 100]
    }
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
id String 글(thread) id

Forum 글 수정

Forum에 쓴 글을 수정한다.

  • Path: /:version/forums/:forum_key/threads/:id

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

  • Method: PUT (PUT으로 전송하기가 어려운 경우에는 POST로 전송하되 쿼리스트링에 _method=PUT을 추가하면 동일한 동작을 수행한다)

  • Request Parameter:

    Name Type Description
    forum_key String forum key
    id String 수정할 글(thread) id

  • Request Body:

Name Type Description
title String 제목
content String 내용
extras JSON(Optional) 추가 데이터. 자유로운 형식으로 추가할 수 있다.
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
affected_count Number 적용된 게시글 수

Forum 글 삭제

Forum에 쓴 글을 삭제한다.

  • Path: /:version/forums/:forum_key/threads/:id

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

  • Method: DELETE (DELETE로 전송하기가 어려운 경우에는 POST로 전송하되 쿼리스트링에 _method=DELETE를 추가하면 동일한 동작을 수행한다)

  • Request Parameter:

    Name Type Description
    forum_key String forum key
    id String 삭제할 글(thread) id

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message String(Optional) 실패한 경우에 메시지 있을 수 있음
affected_count Number 적용된 게시글 수

Error Code

Value Description
0 Success
1001 Invalid parameter
1002 Data dose not exist
2101 Invalid reward
2102 The reward was already accepted
2103 Invalid tag pattern: tag에 comma(,)는 사용불가능하며, 최대 64글자가 허용된다
2201 Invalid purchase status
2202 Invalid payment sequence
2203 Invalid apple receipt
2204 Invalid google purchase data
2205 Invalid google signature
2207 Invalid google iap public key
2303 No iap conversion
2504 Expired coupon
2505 The player has already consumed the coupon
2506 The coupon is no more applicable
2701 Not friend
2705 Too many friends
2801 Already existing nickname
2802 Forbidden nickname
3001 Javascript Exception: Script(javascript) 실행 때 예외 발생. 내용은 result_message를 참조
3101 Undefined Script: 정의되지 않은 스크립트
3102 Protected Script: REST로 외부에서 직접 실행시킬 수 없는 스크립트
3103 Undefined Library: 정의되지 않은 라이브러리
3201 Object Not Found: load/save/destroy의 대상 객체를 찾을 수 없다
3205 Invalid object
3206 Already Existing Object: 이미 존재하는 Object임
3207 Invalid Object Key: object의 key 명명 규칙에 위배
3301 Data Table Not Found: 정의된 Data Table이 없다
3501 Undefined AppData Key: 정의되지 않은 HAppCounter, HAppDictionary, HAppQueue Key
3901 Execution Timeout: 수행 시간 타임아웃
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
4100 Unsupported platform. 해당 platform의 연동정보가 없으므로, 콘솔에서 추가해야 한다.
4101 Authentication failed.
4200 No external platform info. 외부 연동된 플랫폼 정보가 등록되지 않았음.
5001 Invalid push payload
5101 Invalid campaign status
5301 Invalid batch push status
6001 Readonly forum: 읽기 전용 포럼에 쓰기, 수정, 삭제는 불가능
6002 Suspended forum: 사용 중단된 포럼
7001 App Object가 다른 이유로 이미 수정되어 저장이 불가능
8001 The user has been disabled
8002 The session key is invalid
9001 Internal Error: invalid app configuration
9999 Unknown error
Add a custom footer
Add a custom sidebar

Clone this wiki locally