게임플레이 파트너 가이드

테마 전환

랭킹 데이터 스펙 ​

게임플레이 서비스 내 랭킹 영역에 게임별 랭킹을 노출할 때 사용하는 설정 값과 기록값 스펙입니다.
랭킹 설정은 게임플레이 파트너센터에 입력합니다.
아래 ranking 필드 스펙은 설정 항목과 액션데이터 기록값의 매칭 기준을 설명합니다.

랭킹 노출은 사전 조율 후 확정됩니다

ranking.enabled: true로 설정해도 모든 게임이 게임플레이 랭킹 영역(리더보드)에 노출되는 것은 아닙니다.
카카오가 전송된 기록값 데이터를 확인하고 파트너사와 사전 조율을 거쳐 노출 대상과 시점을 확정합니다.
랭킹 설정과 기록값 전송은 노출을 위한 데이터 준비 단계이며, 노출 스펙은 추후 변경될 수 있습니다.
게임 내 자체 랭킹은 이와 무관하게 자유롭게 구현할 수 있습니다.

랭킹 설정과 기록값 매칭 ​

랭킹을 노출하려면 다음 두 데이터가 매칭되어야 합니다.

구분설명전달 시점
파트너센터 랭킹 설정플레이 방식, 랭킹 사용 여부, 산정 기준게임 등록·수정 시
사용자 액션데이터 API사용자 플레이 실제 기록값플레이 시작·완료·종료 시

파트너센터에 설정한 랭킹 기준과 액션데이터의 기록값이 일치해야 랭킹 집계가 가능합니다.

play_mode ​

게임 구조를 설명하는 값이며, 실제 랭킹 산정 기준은 ranking.metrics에서 별도 정의합니다.

값설명
STAGE단계별 진행형 게임
ROUND단판형 게임
TIME_ATTACK타임어택형 게임
LEVEL레벨형 게임
ENDLESS무한형 게임
IDLE방치형 게임
FREE자유형 게임

ranking ​

필드타입설명
enabledboolean필수랭킹 사용 여부
metricsobject[]랭킹 산정 기록값 목록.
1개만 지원.
enabled: true일 때 필수
period_typesstring[]제공할 랭킹 기간.
enabled: true일 때 필수
default_period_typestring기본 랭킹 기간.
허용값은 period_types와 동일.
enabled: true일 때 필수

랭킹 미사용 게임은 ranking.enabled: false만 전달하고 나머지 하위 필드는 생략할 수 있습니다.

metrics ​

필드타입설명
typestring필수기록값 유형
orderstring필수정렬 방향

type 허용값

값설명예시
SCORE점수123450
TIME시간 (ms)58300 (58.3초)
PROGRESS단계·레벨·웨이브10, Lv.12
DISTANCE거리·높이·깊이78.1 (m)
COUNT횟수·콤보·수집량24, 120
RATE비율·정확도·성공률98.5 (%)

order

값설명
ASC값이 작을수록 상위 (예: 클리어 시간)
DESC값이 클수록 상위 (예: 점수, 거리)

복수 metrics는 미지원이며 랭킹 기준은 1개 타입만 지원합니다.

period_types ​

값설명
WEEKLY주간 랭킹
MONTHLY월간 랭킹

사전 문의 필요 케이스 ​

임의 값을 추가하지 않고 카카오 담당자와 사전 협의합니다.

  • play_mode로 표현하기 어려운 게임
  • metrics.type으로 표현하기 어려운 기록값
  • 2개 이상의 기록값 조합이 필요한 경우
  • WEEKLY·MONTHLY 외 기간 랭킹이 필요한 경우
  • 실시간·시즌·보상 지급용 등 별도 랭킹 정책이 필요한 경우

사전 협의 없이 정의되지 않은 값을 전달하면 랭킹 노출이 제한되거나 데이터가 정상 집계되지 않을 수 있습니다.

참고 문서 ​