API & SDK 개요

게임플레이 연동에 필요한 SDK와 API를 한자리에 정리했습니다.
어떤 것을 언제 쓰는지 파악한 뒤 각 상세 페이지로 이동하세요.

연동 순서와 준비 항목은 입점 안내에서 먼저 확인하는 것을 권장합니다.

SDK

게임에서 직접 로드해 사용합니다.

연동 방식은 게임플레이 JS SDK 하나로 다루는 쪽과 개별 SDK 를 직접 다루는 쪽 둘 중 하나입니다.
동시에 구성하는 것은 권장하지 않습니다. 동시 구성 시 같은 객체가 두 번 올라가 초기화 순서에 따라 설정이 덮이거나 콜백이 중복 호출될 수 있습니다.
선택 기준과 마이그레이션 순서는 SDK 연동 방식 선택을 확인하세요.

게임플레이 JS SDK를 사용하지 않는 게임은 Tiara Web SDK를 직접 연동해 게임 로그를 수집·전송합니다.

SDK	용도
게임플레이 JS SDK	게임웹뷰·카카오 로그인·공유·광고를 하나의 `Gameplay` 객체로 다루는 통합 SDK. UI 컴포넌트를 함께 제공합니다. 베타 버전이라 스펙이 변경될 수 있습니다
게임웹뷰 SDK	카카오톡 게임웹뷰 환경의 공통 스펙과 `window.kakaotalkGamePlay` 인터페이스. 안전영역·제스처 제어·공유·종료 등
애드핏 광고 SDK	전면 광고·보상형 전면 광고의 설치·노출 제어·이벤트
카카오 JS SDK	카카오톡 공유 호출을 위한 설치와 초기화
Tiara Web SDK	게임플레이 JS SDK 미사용 게임의 게임 로그(Pageview, Event) 수집·전송

광고 매출 조회는 SDK 가 아니라 REST API 입니다.
아래 광고 항목을 참고하세요.

호출 방향

API는 호출 주체에 따라 두 갈래입니다.
콜백은 파트너사가 엔드포인트를 구현해 카카오에 등록해야 합니다.

방향	대상
파트너사 → 카카오	카카오싱크, 친구 목록 조회, 액션데이터, 사용자 닉네임 조회, 단축 URL 생성, CP별 리포트
카카오 → 파트너사 (콜백)	공유 보상 결과 통지, 동의 철회·연결 해제 웹훅

카카오싱크

게임 URL 진입 즉시 카카오싱크 인가 코드를 요청해 간편가입과 자동 로그인을 처리합니다.
앱 미동의 사용자는 동의 화면을 완료하고, 동의 완료 사용자는 로그인 버튼 없이 파트너사 서비스 세션을 발급받습니다.

API	주요 Endpoint	용도
카카오싱크 API	`GET https://kauth.kakao.com/oauth/authorize`	인가 코드 요청과 카카오싱크 동의 화면 진입
	`POST https://kauth.kakao.com/oauth/token`	토큰 발급과 갱신
	`GET https://kapi.kakao.com/v2/user/me`	카카오 회원번호와 사용자 정보 조회
	`GET https://kapi.kakao.com/v2/user/service_terms`	서비스 약관 동의 내역 확인

서비스 탈퇴와 앱 연결 해제는 카카오가 수행합니다.
파트너사는 계정 상태 변경 웹훅 연동을 구현해 연결 해제 이벤트를 수신하고 사용자 정보와 게임 이용 데이터를 정리합니다.

카카오톡 소셜

친구 랭킹처럼 파트너사가 친구 목록 UI와 데이터를 직접 구성하는 기능은 친구 목록 API를 사용합니다.
사용자가 특정 친구를 직접 선택하는 기능은 카카오가 제공하는 친구 피커를 사용할 수 있습니다.
친구 피커는 카카오가 제공하는 친구 선택 화면으로, 파트너사가 목록 UI를 만들지 않아도 됩니다. 자세한 내용은 카카오톡 친구 피커를 참고하세요.

API	주요 Endpoint	용도
친구 목록 조회 API	`GET https://kapi.kakao.com/v1/api/talk/friends`	친구 정보 제공 조건을 만족하는 친구 목록 조회

데이터

게임 정보와 랭킹 설정은 게임플레이 파트너센터오픈 예정에서 등록·수정합니다.
플레이·랭킹 기록 등 게임 실행 중 발생하는 데이터는 아래 API로 전달합니다.

Base URL https://pf-external-api.kakao.com · 인증은 REST API 키(Authorization: KakaoAK {APP_KEY}) + IP ACL 이중 인증입니다.
상세는 각 페이지의 공통 섹션을 참고하세요.

API	Method · Path	용도
액션데이터 API	`POST /v1/api/gameplay/events`	게임 액션 이벤트 단건 전달
	`POST /v1/api/gameplay/events/batch`	게임 액션 이벤트 일괄 전달 (최대 100건)
사용자 닉네임 목록 조회	`GET /v1/gameplay/profiles`	회원번호 목록으로 게임플레이 프로필 닉네임 일괄 조회

파트너센터 오픈과 함께 사용 중지

메타데이터 API는 파트너센터가 오픈하는 시점에 오류로 응답됩니다.
오픈 시점부터 게임 정보 변경에 업데이트 심사가 포함되므로 API로는 등록·수정할 수 없습니다.
신규 파트너사는 연동하지 않고, 기존 연동 파트너사는 오픈 전까지 기존 API를 사용한 뒤 파트너센터로 전환합니다.

사용자 닉네임 목록 조회만 Base URL과 인증 방식이 다릅니다.
https://kapi.kakao.com으로 호출하며 REST API 키가 아니라 어드민 키를 사용합니다.

액션데이터 요청 본문 예시는 데이터 샘플 카탈로그에 시나리오별로 정리돼 있습니다.

Base URL https://pf-external-api.kakao.com · 인증은 REST API 키(Authorization: KakaoAK {APP_KEY}) + IP ACL 이중 인증입니다.

API	Method · Path	용도
단축 URL 생성	`GET /v1/api/gameplay/games/{gameCode}/short-url`	공유 SDK 호출 전 공유용 단축 URL 발급

항목	형태	용도
CP별 리포트 API	`GET /publisher/v3/report/channel/{channel}`	게임별 광고 매출 조회. CPID 기준

콜백

파트너사가 엔드포인트를 구현하고 카카오디벨로퍼스에 URL을 등록합니다.
공유 웹훅은 [앱] > [웹훅] > [카카오톡 공유 웹훅] 에 등록하며 HTTPS와 443 포트만 사용할 수 있습니다.
아래 경로는 예시이며 파트너사 사양에 맞춰 정할 수 있습니다.

콜백	Method · Path (예시)	트리거
공유 웹훅 연동	`POST https://{partner-domain}/api/v1/games/share/result`	카카오톡 공유 보상 판정 완료 시
계정 상태 변경 웹훅 연동	디벨로퍼스 [카카오 로그인] > [계정 상태 변경 웹훅]에 URL 등록	사용자의 약관 동의 철회·앱 연결 해제 시

두 콜백 모두 재시도가 발생하므로 멱등 처리가 필요합니다.
요구사항은 각 페이지의 파트너사 처리 요구사항 섹션을 확인하세요.

참고 문서

입점 안내: 입점부터 오픈까지의 전체 단계
심사 체크리스트: 연동 완료 후 자체 점검 항목
게임플레이 파트너센터오픈 예정: 게임 정보 등록·수정 및 심사 요청
데이터 샘플 카탈로그: 액션데이터 요청 본문 샘플
기술 문의: 카카오디벨로퍼스 데브톡

API & SDK 개요 ​

SDK ​

호출 방향 ​

카카오싱크 ​

카카오톡 소셜 ​

데이터 ​

공유 ​

광고 ​

콜백 ​

참고 문서 ​

API & SDK 개요

SDK

호출 방향

카카오싱크

카카오톡 소셜

데이터

공유

광고

콜백

참고 문서