---
url: /api-sdk/data/action-data.md
description: 사용자별 게임 액션데이터 단건·일괄 전송 API
---

# 액션데이터 API

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

> **관련 가이드**: [심사 가이드](/docs/checklist/review-guide), [심사 체크리스트](/docs/checklist/review-checklist)

## API 목록

| 이름 | Method | Path |
| --- | --- | --- |
| 단건 전달 | `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_id` | `string` | 필수파트너사 앱 ID |
| `log_id` | `string` | 필수액션데이터 고유 ID. UUID 형식 |
| `action_type` | `string` | 필수`enter` / `play` / `load` / `receive` |
| `app_user_id` | `long` | 필수사용자 `appUserId` |
| `category` | `string` | 필수고정값 `h5` |
| `client_ip` | `string` | 필수사용자 접속 IP |
| `code` | `string` | 필수액션데이터 구분 코드. 고정값 `action` |
| `game_id` | `string` | 필수게임플레이 파트너센터에 등록한 게임 코드와 동일한 게임 고유 ID |
| `label` | `string` | 필수아래 label 매트릭스 참고 |
| `os` | `string` | 필수OS 환경. 허용값 `js` |
| `platform` | `string` | 필수플랫폼 환경. 허용값 `web` |
| `player_id` | `string` | 필수게임 내 사용자 고유 ID |
| `session_id` | `string` | 필수세션 ID. UUID 형식 |
| `timestamp` | `long` | 필수액션 발생 시각 (Unix ms) |
| `play_time` | `long` | 게임 체류시간 (ms). **`Exit_Play`에서 필수**. `Loading` ~ `Exit_Play`까지 누적 체류시간을 파트너사가 직접 계산해 전달합니다 |
| `action_data` | `object` | 종료 시점 결과값. 키는 `metrics.type` 사용. 랭킹을 사용하는 경우 `Complete_Play`·`Exit_Play`에서 전달하고, 랭킹을 사용하지 않거나 부득이하게 결과값 전송이 어려운 경우 없이 전달할 수 있습니다 |

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

## label 매트릭스

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

`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 매트릭스](#label-매트릭스)를 참고하세요.

## 단건 전달

```http
POST /v1/api/gameplay/events
```

### Response

```json
{"success": true}
```

실패 시:

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

**응답 필드**

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `success` | `boolean` | 필수이벤트 처리 성공 여부 |
| `error_code` | `int` | 실패 시 에러 코드 |
| `error_message` | `string` | 실패 시 에러 메시지 |

### 이벤트 처리 에러 코드

| 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 객체**

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `index` | `int` | 필수요청 배열 내 인덱스 (0-based) |
| `success` | `boolean` | 필수해당 이벤트 처리 성공 여부 |
| `error_code` | `int` | 실패 시 에러 코드 |
| `error_message` | `string` | 실패 시 에러 메시지 |

### 이벤트 처리 에러 코드

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

### 요청 자체 에러

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

## 참고 문서

* 게임플레이 파트너센터: 게임 코드와 랭킹 설정 확인
* [메타데이터 API](/api-sdk/data/metadata): 사용 중지 예정 API 의 게임 정보·랭킹 스펙 · 랭킹 데이터 스펙
* [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 시나리오별 요청 본문·Batch 예시
* [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 동의 철회·연결 해제 이벤트 수신 처리
* [Tiara Web SDK](/api-sdk/sdk/tiara-web): 게임 로그 수집·전송
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)