Skip to content

Version 1 item, mission

Jump to bottom Edit New page
Justin edited this page Oct 1, 2013 · 6 revisions

특징

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

서버 정보

종류 Host
상용 api.plattr.com

Authentication

다음 parameter를 HTTP Header에 실어서 보낸다.

Name Value
X-APP-KEY 게임에 발급된 app key. 모든 API 호출에 필요.
X-AUTH-UUID 디바이스 고유의 UUID. 모든 API 호출에 필요.
안드로이드의 경우에는 설치 직후 UUID를 생성하여 넘겨준다.(권고사항)
X-AUTH-TOKEN 서버에서 발급한 인증 token. 사용자 식별이 필요한 API호출에 필요
로그인 API를 호출하면 응답결과로 받음

API List

Anonymous 로그인

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

  • Path: /v1/auth/anonymous
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
user_data_key Array of String 로그인 후 가져와야할 사용자 user data의 key
item_key Array of String 로그인 후 가져와야할 사용자 item의 key
config_key Array of String 로그인 후 가져와야할 사용자 configuration의 key
  • Request URI Example:

http://[server-url]/v1/auth/anonymous?user_data_key=level&user_data_key=score&item_key=character.&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
user_data JSON data user_data_key에 명시된 사용자 데이터들을 json 형태로 반환
items JSON data item_key에 명시된 사용자 데이터들을 json 형태로 반환
configs JSON data config_key에 명시된 configuration 데이터들을 json 형태로 반환
  • Response Body Example:
{
    "result_code": 0,
    "access_token": "iuojsdof-SDFSDF-sdf24-123",
    "user_data":  {
        "key1": "value1",
        "key2": "value2"
    },
    "items":  {
        "key1": number1,
        "key2": number2
    },
    "configs":  {
        "config1": "value1",
        "config2": "value2"
    }
}

Naver 로그인

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

  • Path: /v1/auth/naver
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
user_id String 네이버 로그인 후 얻게되는 네이버 유저의 고유값
user_data_key Array of String 로그인 후 가져와야할 사용자 user data의 key 목록
item_key Array of String 로그인 후 가져와야할 사용자 item의 key 목록
config_key Array of String 로그인 후 가져와야할 사용자 configuration의 key
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
user_data JSON data key에 명시된 사용자 데이터들을 json 형태로 반환
items JSON data key에 명시된 item을 json 형태로 반환
configs JSON data config_key에 명시된 configuration 데이터들을 json 형태로 반환

Kakao 로그인

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

  • Path: /v1/auth/kakao
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
user_id String 카카오 user id
access_token String 카카오 로그인 후 발급 받은 access token
sdk_version String 클라이언트에서 사용하고 있는 카카오 sdk의 버전
user_data_key Array of String 로그인 후 가져와야할 사용자 user data의 key 목록
item_key Array of String 로그인 후 가져와야할 사용자 item의 key 목록
config_key Array of String 로그인 후 가져와야할 사용자 configuration의 key
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
user_data JSON data key에 명시된 사용자 데이터들을 json 형태로 반환
items JSON data key에 명시된 item들을 json 형태로 반환
configs JSON data config_key에 명시된 configuration 데이터들을 json 형태로 반환

회원 탈퇴

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

  • Path: /v1/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] 실패한 경우에 메시지 있을 수 있음

User 데이터 저장

user별로 data를 저장한다.

기본적으로 key/value store라고 보면 된다. key에 관한 제약사항은 아래 링크 참고.

User Data Items 의 key에 대해서

  • Path: /v1/data
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON array로 다음과 같은 JSON object들 포함
Name Type Description
condition Option[JSON Array] set하기 위한 조건들.
Array내의 조건이 모두 만족할 때만 data에 세팅된 값들로 변경된다.
Name Type Description
key String 조건으로 쓰일 data의 key
operator String 다음 값중 하나. '<', '>', '<=', '>=', '==', '!='
value String 조건으로 data의 value
with_return_values Boolean true이면 변경된 데이터를 결과에 포함한다.
Default는 false
data JSON Array
Name Type Description
key String data의 key
value String data의 value
command Option[String] 'set', 'inc', 'dec' 중 하나.
Default는 set
'inc'나 'dec'인 경우에 value의 string은 number로 전환 가능하여야 함
  • Request Body Example
{
    "condition": [
        {
            "key": "money",
            "operator": ">",
            "value": "100"
        },
        {
            "key": "level",
            "operator": "==",
            "value": "20"
        }
    ],
    "data": [
        {
            "key": "money",
            "value": "100",
            "command": "dec"
        },
        {
            "key": "level",
            "value": "21"
        }
    ]
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
data Option[JSON Object] 변경된 user data.
with_return_values가 true인경우에만 있음.
key String data의 key
value String data의 value

User 데이터 얻어오기

  • Path: /v1/data

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

  • Method: GET

  • Parameters:

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

  • Request URI Example:

http://[server-url]/v1/data?key=level&key=score&key=friends_count

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

Item 목록 얻어오기

User Data Items 의 key에 대해서

  • Path: /v1/items

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

  • Method: GET

  • Parameters:

    Name Type Description
    key Array of String 얻어오고자 아는 item의 key 목록

  • Request URI Example:

http://[server-url]/v1/item?key=hearts&key=character.

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
items JSON Object
key String item의 key
value Number item의 count
  • Response Body Example:
{
    "result_code": 0,
    "items": {
        "stone": 100,
        "candy": 200,
        "character.angel": 1
    }
}

Item 사용

  • Path: /v1/items
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
items JSON Array 다음을 포함하는 JSON Array
Name Type Description
key String 사용할 아이템의 key
count Number 사용할 아이템의 값. count 만큼 차감됨
to_key Option[String] 다른 아이템으로 전환하고자 할 때, 전환하고자 하는 아이템의 key.
전환 비율은 partner에서 미리 정의해 두어야 함
이 값이 없으면 단순히 'key'의 아이템의 값이 차감됨
with_return_values Boolean true이면 변경된 데이터를 결과에 포함한다.
Default는 false
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
items Option[JSON Array] 변경된 item의 값들
with_return_values가 true이면 포함됨
json의 key는 item의 key, json의 value는 item의 count

Mail 생성

  • Path: /v1/mails
  • 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] 실패한 경우에 메시지 있을 수 있음
id Number 추가된 mail의 id

Mail 내용 얻어오기

  • Path: /v1/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
after_mail_id Option[Number] after_id 다음 것부터 얻어옴
이 id부터 descending임
limit Number 가져올 최대 개수. default는 10개
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
mails JSON Object
Name Type Description
id Number mail의 id
content String json 형식을 따르는 임의의 데이터.
reward_id Option[Number] 이 mail 아이템과 관련된 보상(reward) 아이템이 있는 경우 그것의 id
  • 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 아이템 1개 내용 업데이트

  • Path: /v1/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: /v1/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: /v1/mails/delete_all

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

Mission 수행 완료

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

  • Path: /v1/missions/:id

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

  • Method: POST

  • Request Parameter:

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

  • Request Body: 없음

  • Response Body:

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

Reward 아이템 조회

  • Path: /v1/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] 실패한 경우에 메시지 있을 수 있음
changes JSON Array 보상의 결과로 변경될 item 목록
Name Type Description
key String 보상으로 변경될 item의 key
value String 보상으로 변경될 item의 value
command String 'set', 'inc', 'dec' 중 하나. default는 'set'
valid Boolean 이미 사용된 경우 false

Reward 아이템 사용

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

  • Path: /v1/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] 실패한 경우에 메시지 있을 수 있음
    items JSON Object 변경된 user data들

Reward 아이템 무효화

  • Path: /v1/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: /v1/leaderboards/:leaderboard_id/scores/:score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: 없음
  • Request Parameter:
Name Type Description
leaderboard_id String 리더보드 id
score Number 새로 득점한 값
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Leaderboard에서 순위 목록 얻어오기

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

  • Path: /v1/leaderboards/:leaderboard_id/scores
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_id String 조회하고자 하는 leaderboard id
user_data_key Array of String score 정보에 포함될 사용자별 user data
item_key Array of String score 정보에 포함될 사용자별 item
rank_min Number 조회하고자 하는 순위 목록의 시작 순위
rank_max Number 조회하고자 하는 순위 목록의 끝 순위
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내의 스코어 목록의 전체 개수
scores JSON Array Score의 JSON Array 객체.
Score에 대해서는 'Score' 참고

Score

Score JSON Object는 다음과 같다.

Name Type Description
user_id Number 사용자 id
value Number score 값
rank Number 순위
user_data JSON data user_data_key에 명시된 사용자 데이터들을 json 형태로 반환
items JSON data item_key에 명시된 사용자 데이터들을 json 형태로 반환

  • Response Example:

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

    http://[server_url]/v1/leaderboard/3312/scores?user_data_key=level&user_data_key=character&range_min=0&range_max=100000

     {
     "result_code": 0,
     "scores_count":3421,
     "scores": [
         {
             "user_id": 234331,
             "value": 10002,
             "rank": 31,
             "user_data": {
                 "level": "23"
             },
             "items": {
                 "character.level": 3
             }
         },
         {
             "user_id": 114331,
             "value": 9900,
             "rank": 32,
             "user_data": {
                 "level": "22"
             },
             "items": {
                 "character.level": 2
             }
         },
         {
             "user_id": 44332,
             "value": 10002,
             "rank": 33,
             "user_data": {
                 "level": "12"
             },
             "items": {
                 "character.level": 10
             }
         }
     ]
 }

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

  • Path: /v1/leaderboards/:leaderboard_id/my_score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_id String 조회하고자 하는 leaderboard id
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] 내 점수. 단, 기존에 점수가 없는 경우 이 field도 없음
rank Option[Number] 내 순위. 단, 기존에 점수가 없는 경우 이 field도 없음

Kakao 친구들의 점수 정보 가져오기

카카오 친구들의 점수 정보를 가져온다.

  • Path: /v1/leaderboards/:leaderboard_id/kakao_friends
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameter:
Name Type Description
leaderboard_id Number leaderboard의 id
user_data_key Array of String score 정보에 포함될 사용자별 user data
item_key Array of String score 정보에 포함될 사용자별 item
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores JSON Array
Name Type Description
score Number 점수
rank Number 등수. 1부터 시작
platform_user_id String 카카오 user_id
user_data JSON object parameter로 요청한 user data
scores_count Number scores의 개수

네이버 빌링 처리 process

네이버 빌링 처리 process

네이버 상품 구매 등록

상품을 구매하기 전에, 구매를 위한 id를 발급 받는다.

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

네이버 상품 구매 완료 처리

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

  • Path: /v1/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
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
purchased_item JSON Object 완료후 변경된 유료 아이템.
json의 key에는 purchased_item의 key가, json의 value에는 purchased_item의 value가 세팅됨

Kakao 친구 목록 업데이트

카카오 서버로부터 받은 정보를 이용해서 친구 목록을 업데이트 한다.

  • Path: /v1/kakao_friends
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
app_friends_info JSON array 카카오 친구 목록 조회 api를 호출해서 얻은 결과에서 'app_friends_info'.
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Configuration 데이터 얻어오기

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

  • Path: /v1/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:

http://[server-url]/v1/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,
    "data": {
        "key1": "value1",
        "key2": "value2"
    }
}

Error Code

Value Description
0 Success
1001 Invalid parameter
1002 Data dose not exist
2001 Conditions are not met
2002 Too many conditions
Max 5개
2003 Too many 'get data' request
Max 10개
2004 Too many 'set data' request
Max 10개
2101 Invalid reward
2201 Invalid purchase status
2202 Invalid payment sequence
2301 No item conversion is defined
2302 Not enough item
2401 Mission already completed
9999 Unknown error
Add a custom footer
Add a custom sidebar

Clone this wiki locally