게임플레이 파트너 가이드

테마 전환

액션데이터 API ​

파트너사가 카카오(게임플레이) 서버로 사용자별 게임 액션데이터를 전송하는 API입니다.
단건과 일괄(Batch) 두 방식을 제공합니다.
본 스펙은 대표 가이드이며, 실제 적용 시 파트너사별 협의를 통해 세부 사항이 조정될 수 있습니다.

관련 가이드: 심사 가이드, 심사 체크리스트

API 목록 ​

이름MethodPath
단건 전달POST/v1/api/gameplay/events
일괄 전달 (Batch)POST/v1/api/gameplay/events/batch

공통 ​

Base URL ​

http
https://pf-external-api.kakao.com

헤더 ​

Header설명
Authorization필수KakaoAK {APP_KEY}: 파트너사 디벨로퍼스 앱의 REST API 키
Content-Type필수application/json

인증 ​

  • Authorization 헤더의 APP_KEY 검증
  • IP ACL 기반(사전 등록된 IP만 허용) 이중 인증

Rate Limit ​

항목값
제한 기준요청 IP 단위
허용량최대 1,000 RPS
Burst순간 최대 2,000 requests

제한 초과 시 503 Service Temporarily Unavailable이 반환됩니다.
대량 데이터를 전송할 때는 일괄 전달 API를 활용하거나 요청 간격을 조절합니다.

이벤트 스키마 ​

두 API 모두 아래 스키마의 이벤트 객체를 사용합니다.

필드타입설명
app_idstring필수파트너사 앱 ID
log_idstring필수액션데이터 고유 ID. UUID 형식
action_typestring필수enter / play / load / receive
app_user_idlong필수사용자 appUserId
categorystring필수고정값 h5
client_ipstring필수사용자 접속 IP
codestring필수액션데이터 구분 코드.
고정값 action
game_idstring필수게임플레이 파트너센터오픈 예정에 등록한 게임 코드와 동일한 게임 고유 ID
labelstring필수아래 label 매트릭스 참고
osstring필수OS 환경.
허용값 js
platformstring필수플랫폼 환경.
허용값 web
player_idstring필수게임 내 사용자 고유 ID
session_idstring필수세션 ID. UUID 형식
timestamplong필수액션 발생 시각 (Unix ms)
play_timelong게임 체류시간 (ms).
Exit_Play에서 필수.
Loading ~ Exit_Play까지 누적 체류시간을 파트너사가 직접 계산해 전달합니다
action_dataobject종료 시점 결과값.
키는 metrics.type 사용.
랭킹을 사용하는 경우 Complete_Play·Exit_Play에서 전달하고, 랭킹을 사용하지 않거나 부득이하게 결과값 전송이 어려운 경우 없이 전달할 수 있습니다

action_data의 키는 파트너센터오픈 예정에 설정한 랭킹 지표와 정확히 일치해야 랭킹이 집계됩니다.
파트너센터 오픈 전까지 메타데이터 API로 연동한 파트너사는 ranking.metrics.type과 같은 값을 사용합니다.
랭킹 기록은 게임에서 대표로 삼을 메인 모드 한 가지에 대해서만 전달합니다.
여러 모드·기록값이 있어도 랭킹에 표시할 대표 요소 하나를 정해 그 결과값만 action_data로 보냅니다.
랭킹 노출은 기록값 전달만으로 확정되지 않으며, 카카오가 데이터를 심사하고 파트너사와 사전 조율을 거쳐 확정합니다.
랭킹 설정 항목과 기록값 허용치는 랭킹 데이터 스펙을 참고하세요.

label 매트릭스 ​

labelaction_type설명
Loadingenter세션 최초 진입 (1회)
Complete_Loadingenter게임 로딩 완료.
세션마다 1회 필수 전달합니다
Start_Playplay플레이 1판 시작
Complete_Playplay랭킹에 기록할 한 판(라운드/스테이지)의 정상 완료 시점.
랭킹을 사용하는 경우 랭킹에 표시할 메인 모드에 한해 action_data와 함께 전달합니다.
스테이지 실패 등 랭킹에 기록하지 않아야 하는 경우에는 Complete_Play를 전달하지 않습니다.
라운드·스테이지·판 단위가 없는 무한형 게임(방치형·끝없는 진척형 등)은 파트너사가 자체 정의한 의미 있는 진척 시점(예: 시설 건설, 보스 처치, 일정 점수 도달)에 전달합니다
Exit_Playplay게임 세션 종료.
사용자가 웹뷰를 닫거나 뒤로가기·X 버튼 등으로 게임을 떠난 시점.
한 세션에 1회 발생하며 play_time은 필수입니다.
랭킹을 사용하는 경우 action_data도 함께 전달하며, 랭킹을 사용하지 않거나 비정상 종료로 결과값 확보가 불가한 경우 생략할 수 있습니다
Ad_Reward_Loadedload보상형 광고 로드 완료
Ad_Reward_Startenter보상형 광고 시청 시작
Ad_Reward_Receivedreceive보상형 광고 리워드 수령
Ad_Normal_Loadedload비보상형 광고 로드 완료
Ad_Normal_Startenter비보상형 광고 시청 시작

Complete_Play와 Exit_Play는 단위가 다른 별개 이벤트입니다.
한 세션 안에서 여러 판을 플레이한 경우 Complete_Play는 정상 완료한 판 수만큼, Exit_Play는 1회 발생합니다.

작성 시 주의사항 ​

  • Complete_Loading은 게임 로딩 완료 시점에 세션마다 1회 필수로 전달합니다.
  • play_time은 파트너사가 Loading ~ Exit_Play까지 누적 체류시간(ms)을 직접 계산합니다.
  • 랭킹 기록은 대표 메인 모드 하나의 결과값만 action_data로 전달합니다.
    Complete_Play · Exit_Play의 전달 조건은 label 매트릭스를 참고하세요.

단건 전달 ​

http
POST /v1/api/gameplay/events

Response ​

json
{"success": true}

실패 시:

json
{
  "success": false,
  "error_code": -852,
  "error_message": "game not exist"
}

응답 필드

필드타입설명
successboolean필수이벤트 처리 성공 여부
error_codeint실패 시 에러 코드
error_messagestring실패 시 에러 메시지

이벤트 처리 에러 코드 ​

code설명
-2유효하지 않은 파라미터
-543사용자 미존재
-852게임 미존재
-1내부 서버 오류

요청 자체 에러 ​

요청 자체가 유효하지 않으면 응답 본문이 아닌 예외로 반환됩니다.

code설명
-2요청 파라미터 오류 (null body 등)
-900허용되지 않은 IP

일괄 전달 (Batch) ​

http
POST /v1/api/gameplay/events/batch

Request Body ​

이벤트 객체의 JSON Array로 전달합니다.

항목값
형식이벤트 객체 배열
최대 건수100건 (1 ≤ size ≤ 100)

100건을 초과하면 요청 자체가 에러 처리됩니다.

Response ​

json
{
  "results": [
    {"index": 0, "success": true},
    {
      "index": 1,
      "success": false,
      "error_code": -852,
      "error_message": "game not exist"
    },
    {"index": 2, "success": true}
  ]
}

results는 요청 배열과 동일한 순서로 반환됩니다.

EventResult 객체

필드타입설명
indexint필수요청 배열 내 인덱스 (0-based)
successboolean필수해당 이벤트 처리 성공 여부
error_codeint실패 시 에러 코드
error_messagestring실패 시 에러 메시지

이벤트 처리 에러 코드 ​

단건 전달과 동일합니다 (-2, -543, -852, -1).

요청 자체 에러 ​

code설명
-2요청 파라미터 오류 (빈 배열, 100건 초과 등)
-1내부 서버 오류
-900허용되지 않은 IP

참고 문서 ​