--- url: /api-sdk/data/samples.md description: 액션데이터 API와 사용 중지 예정인 메타데이터 API 요청 본문 샘플 모음 --- # 데이터 샘플 카탈로그 [액션데이터 API](/api-sdk/data/action-data)와 사용 중지 예정인 [메타데이터 API](/api-sdk/data/metadata)의 요청 본문 샘플입니다. 각 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} } ] ``` ## 메타데이터 샘플 (사용 중지 예정) ::: warning 게임플레이 파트너센터 오픈과 함께 사용 중지 메타데이터 API는 파트너센터가 오픈하는 시점에 오류로 응답되므로, 신규 파트너사는 연동하지 않고 파트너센터에서 게임 정보를 등록·수정합니다. 아래 샘플은 오픈 전까지 기존 연동을 유지하기 위한 참고 자료입니다. 중지 시점과 전환 방법은 [메타데이터 API](/api-sdk/data/metadata)에서 확인하세요. ::: `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-sdk/data/metadata): 사용 중지 예정 API 의 필드 정의·에러 코드 * 게임플레이 파트너센터: 신규 게임 정보 등록·수정 및 심사 요청 * [액션데이터 API](/api-sdk/data/action-data): 이벤트 스키마·label 매트릭스·Batch API * [게임 로그 설정](/api-sdk/sdk/tiara-game-logs#게임-로그-정의): 필수 게임 로그 11종 정의 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)