데이터 샘플 카탈로그

액션데이터 API와 사용 중지 예정인 메타데이터 API의 요청 본문 샘플입니다.
각 API의 필드 정의·에러 코드 같은 스펙 자체는 각 페이지를, 여기서는 어떤 값을 어떤 형태로 채워 전달해야 하는지에 대한 예시만 다룹니다.

액션데이터 샘플

세 가지 대표 시나리오에서 로그가 어떤 순서로 발생하고 어떤 필드가 채워지는지 정리했습니다.
action_data가 필요한 이벤트와 그렇지 않은 이벤트의 차이를 확인하는 용도로 사용하세요.

시나리오 1: 정상 플레이 완료 (SCORE)

GAME_001(퍼즐, 점수 랭킹)에서 사용자가 한 판을 정상 완료한 경우입니다.

순번	`label`	`action_type`	`action_data`
1	`Loading`	`enter`	—
2	`Complete_Loading`	`enter`	—
3	`Start_Play`	`play`	—
4	`Complete_Play`	`play`	`{"SCORE": 4800}`
5	`Exit_Play`	`play`	`{"SCORE": 4800}` (+ `play_time`)

시나리오 2: 보상형 광고 시청 후 이어하기 (SCORE)

GAME_002(액션, 점수 랭킹)에서 사용자가 광고 보상을 수령한 뒤 플레이를 이어 정상 완료한 경우입니다.

순번	`label`	`action_type`	`action_data`
1	`Loading`	`enter`	—
2	`Complete_Loading`	`enter`	—
3	`Start_Play`	`play`	—
4	`Ad_Reward_Loaded`	`load`	—
5	`Ad_Reward_Start`	`enter`	—
6	`Ad_Reward_Received`	`receive`	—
7	`Complete_Play`	`play`	`{"SCORE": 8200}`
8	`Exit_Play`	`play`	`{"SCORE": 8200}` (+ `play_time`)

시나리오 3: 비보상 광고 노출 후 세션 종료 (DISTANCE)

GAME_005(거리 기록형)에서 사용자가 비보상 광고를 본 뒤 게임을 떠난 경우입니다.
세션이 종료되는 시점에 Exit_Play가 발생합니다.

순번	`label`	`action_type`	`action_data`
1	`Loading`	`enter`	—
2	`Complete_Loading`	`enter`	—
3	`Start_Play`	`play`	—
4	`Ad_Normal_Loaded`	`load`	—
5	`Ad_Normal_Start`	`enter`	—
6	`Exit_Play`	`play`	`{"DISTANCE": 781}` (+ `play_time`)

Exit_Play는 게임 세션 종료 시점에 1회 발생하며 play_time 필드를 함께 전달합니다.
한 판 완료 후 세션을 종료한 경우 Exit_Play의 action_data는 마지막 Complete_Play와 같은 기록값을 전달합니다.

단건 전달 요청 본문

각 이벤트 유형별로 실제 전송되는 JSON 형태입니다.

Loading: 진입 (action_data 없음)

json

{
  "app_id": "1000001",
  "log_id": "77300f50-f66a-1001-8302-000000000001",
  "action_type": "enter",
  "app_user_id": 5000000001,
  "category": "h5",
  "client_ip": "203.0.113.10",
  "code": "action",
  "game_id": "GAME_001",
  "label": "Loading",
  "os": "js",
  "platform": "web",
  "player_id": "p100000000001",
  "session_id": "10000715-ab7c-4d07-9c99-71e615bece8e",
  "timestamp": 1743300000000
}

Start_Play: 한 판 시작 (action_data 없음)

json

{
  "app_id": "1000001",
  "log_id": "77300f50-f66a-1001-8302-000000000003",
  "action_type": "play",
  "app_user_id": 5000000001,
  "category": "h5",
  "client_ip": "203.0.113.10",
  "code": "action",
  "game_id": "GAME_001",
  "label": "Start_Play",
  "os": "js",
  "platform": "web",
  "player_id": "p100000000001",
  "session_id": "10000715-ab7c-4d07-9c99-71e615bece8e",
  "timestamp": 1743300003800
}

Complete_Play: 한 판 정상 종료 (action_data 필수)

json

{
  "app_id": "1000001",
  "log_id": "77300f50-f66a-1001-8302-000000000004",
  "action_type": "play",
  "app_user_id": 5000000001,
  "category": "h5",
  "client_ip": "203.0.113.10",
  "code": "action",
  "game_id": "GAME_001",
  "label": "Complete_Play",
  "os": "js",
  "platform": "web",
  "player_id": "p100000000001",
  "session_id": "10000715-ab7c-4d07-9c99-71e615bece8e",
  "timestamp": 1743300165000,
  "action_data": {"SCORE": 4800}
}

Exit_Play: 세션 종료 (play_time · action_data 필수)

json

{
  "app_id": "1000001",
  "log_id": "77300f50-f66a-5001-8302-000000000005",
  "action_type": "play",
  "app_user_id": 5000000003,
  "category": "h5",
  "client_ip": "203.0.113.30",
  "code": "action",
  "game_id": "GAME_005",
  "label": "Exit_Play",
  "os": "js",
  "platform": "web",
  "player_id": "p100000000003",
  "session_id": "50000715-ab7c-4d07-9c99-71e615bece8e",
  "timestamp": 1743307410000,
  "play_time": 210000,
  "action_data": {"DISTANCE": 781}
}

일괄 전달(Batch) 요청 본문

POST /v1/api/gameplay/events/batch 호출 시 이벤트 객체를 JSON Array로 전달합니다.
개별 객체 규격은 단건 전달과 동일하며, 한 요청당 최대 100건입니다.

json

[
  {
    "app_id": "1000001",
    "log_id": "77300f50-f66a-1001-8302-000000000004",
    "action_type": "play",
    "app_user_id": 5000000001,
    "category": "h5",
    "client_ip": "203.0.113.10",
    "code": "action",
    "game_id": "GAME_001",
    "label": "Complete_Play",
    "os": "js",
    "platform": "web",
    "player_id": "p100000000001",
    "session_id": "10000715-ab7c-4d07-9c99-71e615bece8e",
    "timestamp": 1743300165000,
    "action_data": {"SCORE": 4800}
  },
  {
    "app_id": "1000001",
    "log_id": "77300f50-f66a-2001-8302-000000000006",
    "action_type": "play",
    "app_user_id": 5000000002,
    "category": "h5",
    "client_ip": "203.0.113.20",
    "code": "action",
    "game_id": "GAME_002",
    "label": "Complete_Play",
    "os": "js",
    "platform": "web",
    "player_id": "p100000000002",
    "session_id": "20000715-ab7c-4d07-9c99-71e615bece8e",
    "timestamp": 1743303960000,
    "action_data": {"SCORE": 8200}
  },
  {
    "app_id": "1000001",
    "log_id": "77300f50-f66a-5001-8302-000000000005",
    "action_type": "play",
    "app_user_id": 5000000003,
    "category": "h5",
    "client_ip": "203.0.113.30",
    "code": "action",
    "game_id": "GAME_005",
    "label": "Exit_Play",
    "os": "js",
    "platform": "web",
    "player_id": "p100000000003",
    "session_id": "50000715-ab7c-4d07-9c99-71e615bece8e",
    "timestamp": 1743307410000,
    "play_time": 210000,
    "action_data": {"DISTANCE": 781}
  }
]

메타데이터 샘플 (사용 중지 예정)

게임플레이 파트너센터 오픈과 함께 사용 중지

메타데이터 API는 파트너센터오픈 예정가 오픈하는 시점에 오류로 응답되므로, 신규 파트너사는 연동하지 않고 파트너센터에서 게임 정보를 등록·수정합니다.
아래 샘플은 오픈 전까지 기존 연동을 유지하기 위한 참고 자료입니다.
중지 시점과 전환 방법은 메타데이터 API에서 확인하세요.

play_mode와 ranking.metrics.type은 게임 구조에 따라 달라집니다.
대표 유형별로 5종을 정리했습니다.

게임 유형별 요약

`code`	설명	`genre.main`	`genre.subs`	`play_mode`	`ranking.metrics`	`ranking.period_types`
`GAME_001`	스테이지형 · 점수 랭킹	`PUZZLE`	`[]`	`STAGE`	`[{type: SCORE, order: DESC}]`	`[WEEKLY, MONTHLY]`
`GAME_002`	라운드형 · 점수 랭킹	`ACTION`	`[ARCADE]`	`ROUND`	`[{type: SCORE, order: DESC}]`	`[WEEKLY]`
`GAME_003`	스테이지 진척 랭킹	`PUZZLE`	`[]`	`STAGE`	`[{type: PROGRESS, order: DESC}]`	`[WEEKLY, MONTHLY]`
`GAME_004`	타임어택 · 최단 시간	`BOARD`	`[]`	`ROUND`	`[{type: TIME, order: ASC}]`	`[WEEKLY]`
`GAME_005`	거리 기록형	`ACTION`	`[ARCADE]`	`ROUND`	`[{type: DISTANCE, order: DESC}]`	`[WEEKLY]`

TIME 기록값의 order는 "짧을수록 상위"인 게임이라면 ASC입니다.
subs에는 main과 동일한 코드를 넣을 수 없습니다.
랭킹을 사용하지 않는 게임도 ranking.enabled: false로 필드를 반드시 포함합니다.

등록 요청 본문 (풀세트)

GAME_001을 기준으로 한 신규 등록 요청 본문입니다.
이후 수정 요청 시에도 동일하게 모든 필드를 함께 전달합니다.

json

{
  "code": "GAME_001",
  "name": "퍼즐 게임 샘플",
  "description": "같은 이미지를 합쳐 더 큰 단계를 만드는 게임.",
  "thumbnail": {
    "square": "https://cdn.partner.com/games/GAME_001/thumb_square.png",
    "wide": "https://cdn.partner.com/games/GAME_001/thumb_wide.png"
  },
  "link": "https://gameplay.kakao.com/h5/GAME_001/index.html?partner={partner}&h5id=GAME_001",
  "genre": {
    "main": "PUZZLE",
    "subs": []
  },
  "play_mode": "STAGE",
  "ranking": {
    "enabled": true,
    "metrics": [{"type": "SCORE", "order": "DESC"}],
    "period_types": ["WEEKLY", "MONTHLY"],
    "default_period_type": "WEEKLY"
  },
  "display_info": {
    "age_rating": "ALL",
    "rating_classification_number": "CC-OM-260204-001",
    "rating_classification_date": "2026-01-15",
    "corporate_name": "(주)카카오게임플레이파트너",
    "business_registration_number": "2025-서울강남-00001",
    "content_descriptors": [],
    "has_probability_item": false
  }
}

등록 요청 본문 (자체등급분류·내용정보 표시 게임)

구글플레이스토어 자체등급분류 번호를 사용하고 게임물 내용정보 표시가 있는 게임의 예시입니다.

json

{
  "code": "GAME_005",
  "name": "거리 기록형 게임 샘플",
  "description": "달려간 거리를 기록으로 남기는 게임.",
  "thumbnail": {
    "square": "https://cdn.partner.com/games/GAME_005/thumb_square.png",
    "wide": "https://cdn.partner.com/games/GAME_005/thumb_wide.png"
  },
  "link": "https://gameplay.kakao.com/h5/GAME_005/index.html?partner={partner}&h5id=GAME_005",
  "genre": {"main": "ACTION", "subs": ["ARCADE"]},
  "play_mode": "ROUND",
  "ranking": {
    "enabled": true,
    "metrics": [{"type": "DISTANCE", "order": "DESC"}],
    "period_types": ["WEEKLY"],
    "default_period_type": "WEEKLY"
  },
  "display_info": {
    "age_rating": "AGE_12",
    "rating_classification_number": "GOOG-SG-260120-0002",
    "rating_classification_date": "2026-01-20",
    "corporate_name": "(주)예시게임즈",
    "business_registration_number": "2025-서울강남-00002",
    "content_descriptors": ["VIOLENT"],
    "has_probability_item": false
  }
}

등록 요청 본문 (랭킹 미사용)

랭킹을 노출하지 않는 게임은 ranking.enabled만 false로 전달하고 metrics · period_types 등은 생략할 수 있습니다.

json

{
  "code": "GAME_999",
  "name": "캐주얼 게임 샘플",
  "description": "랭킹 미사용 케이스",
  "thumbnail": {
    "square": "https://cdn.partner.com/games/GAME_999/thumb_square.png",
    "wide": "https://cdn.partner.com/games/GAME_999/thumb_wide.png"
  },
  "link": "https://gameplay.kakao.com/h5/GAME_999/index.html?partner={partner}&h5id=GAME_999",
  "genre": {"main": "ACTION", "subs": []},
  "play_mode": "ROUND",
  "ranking": {"enabled": false},
  "display_info": {
    "age_rating": "ALL",
    "rating_classification_number": "CC-OM-260204-999",
    "rating_classification_date": "2026-01-15",
    "corporate_name": "(주)카카오게임플레이파트너",
    "business_registration_number": "2025-서울강남-00001",
    "content_descriptors": [],
    "has_probability_item": false
  }
}

참고 문서

메타데이터 API: 사용 중지 예정 API 의 필드 정의·에러 코드
게임플레이 파트너센터오픈 예정: 신규 게임 정보 등록·수정 및 심사 요청
액션데이터 API: 이벤트 스키마·label 매트릭스·Batch API
게임 로그 설정: 필수 게임 로그 11종 정의
기술 문의: 카카오디벨로퍼스 데브톡

데이터 샘플 카탈로그 ​

액션데이터 샘플 ​

시나리오 1: 정상 플레이 완료 (SCORE) ​

시나리오 2: 보상형 광고 시청 후 이어하기 (SCORE) ​

시나리오 3: 비보상 광고 노출 후 세션 종료 (DISTANCE) ​

단건 전달 요청 본문 ​

일괄 전달(Batch) 요청 본문 ​

메타데이터 샘플 (사용 중지 예정) ​

게임 유형별 요약 ​

등록 요청 본문 (풀세트) ​

등록 요청 본문 (자체등급분류·내용정보 표시 게임) ​

등록 요청 본문 (랭킹 미사용) ​

참고 문서 ​

데이터 샘플 카탈로그

액션데이터 샘플

시나리오 1: 정상 플레이 완료 (SCORE)

시나리오 2: 보상형 광고 시청 후 이어하기 (SCORE)

시나리오 3: 비보상 광고 노출 후 세션 종료 (DISTANCE)

단건 전달 요청 본문

일괄 전달(Batch) 요청 본문

메타데이터 샘플 (사용 중지 예정)

게임 유형별 요약

등록 요청 본문 (풀세트)

등록 요청 본문 (자체등급분류·내용정보 표시 게임)

등록 요청 본문 (랭킹 미사용)

참고 문서