---
url: /api-sdk.md
description: 게임플레이 연동에 사용하는 SDK와 API 전체 목록
---

# API & SDK 개요

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

연동 순서와 준비 항목은 [입점 안내](/docs/checklist/start-guide)에서 먼저 확인하는 것을 권장합니다.

## SDK

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

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

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

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

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

## 호출 방향

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

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

## 카카오싱크

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

| API | 주요 Endpoint | 용도 |
| --- | --- | --- |
| [카카오싱크 API](/api-sdk/kakaosync/rest-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` | 서비스 약관 동의 내역 확인 |

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

## 카카오톡 소셜

친구 랭킹처럼 파트너사가 친구 목록 UI와 데이터를 직접 구성하는 기능은 친구 목록 API를 사용합니다.
사용자가 특정 친구를 직접 선택하는 기능은 카카오가 제공하는 친구 피커를 사용할 수 있습니다.
친구 피커는 카카오가 제공하는 친구 선택 화면으로, 파트너사가 목록 UI를 만들지 않아도 됩니다. 자세한 내용은 [카카오톡 친구 피커](https://developers.kakao.com/docs/ko/kakaotalk-social/common#picker-friends)를 참고하세요.

| API | 주요 Endpoint | 용도 |
| --- | --- | --- |
| [친구 목록 조회 API](/api-sdk/kakaotalk-social/friends) | `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](/api-sdk/data/action-data) | `POST /v1/api/gameplay/events` | 게임 액션 이벤트 단건 전달 |
| | `POST /v1/api/gameplay/events/batch` | 게임 액션 이벤트 일괄 전달 (최대 100건) |
| [사용자 닉네임 목록 조회](/api-sdk/data/user-nicknames) | `GET /v1/gameplay/profiles` | 회원번호 목록으로 게임플레이 프로필 닉네임 일괄 조회 |

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

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

액션데이터 요청 본문 예시는 [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플)에 시나리오별로 정리돼 있습니다.

## 공유

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

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

## 광고

광고 노출 자체는 REST API가 아니라 [애드핏 광고 SDK](/api-sdk/sdk/adfit) 로 처리합니다. 광고단위 발급과 옵션 설정은 [애드핏 설정](/docs/ads/iaa-options)을 먼저 진행해야 합니다.

여기서 다루는 것은 매출 조회 API 하나입니다. Base URL은 `https://adfit-external-api.kakao.com` 이며, 데이터 API와 달리 Query Parameter 방식의 API Key로 인증합니다.

| 항목 | 형태 | 용도 |
| --- | --- | --- |
| [CP별 리포트 API](/api-sdk/ads/cp-report) | `GET /publisher/v3/report/channel/{channel}` | 게임별 광고 매출 조회. CPID 기준 |

노출 정책과 UX 원칙은 [광고 UX 가이드](/docs/ads/ux-guideline)를 따릅니다.

## 콜백

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

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

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

## 참고 문서

* [입점 안내](/docs/checklist/start-guide): 입점부터 오픈까지의 전체 단계
* [심사 체크리스트](/docs/checklist/review-checklist): 연동 완료 후 자체 점검 항목
* 게임플레이 파트너센터: 게임 정보 등록·수정 및 심사 요청
* [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 액션데이터 요청 본문 샘플
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)