--- url: /docs/checklist/start-guide.md description: 게임플레이 입점 구조와 파트너사가 준비해야 하는 연동 작업 안내 --- # 입점 안내 카카오톡 게임플레이는 파트너사의 H5 게임을 카카오톡 안에서 사용자에게 제공하는 서비스입니다. 파트너사는 회사 단위의 제휴 입점을 마친 뒤 입점할 게임을 카카오와 협의합니다. 협의가 완료되면 필요한 게임 정보와 개발 연동을 준비하고, **게임플레이 파트너센터**에서 게임 등록 및 출시 심사를 거쳐 게임을 출시합니다. 이 페이지에서는 파트너사 제휴 입점부터 게임 입점 협의, 개발 연동, 심사, 출시와 운영까지 필요한 작업을 순서대로 안내합니다. ## 1단계: 입점 협의 게임플레이 입점은 회사 단위의 **파트너사 제휴 협의**와 게임 단위의 **게임 입점 협의** 단계로 나뉩니다. ### 파트너사 제휴 게임플레이와 처음 제휴하는 회사는 회사 단위로 제휴 입점을 신청합니다. 아래 링크를 통해 게임플레이 파트너사가 되기 위한 제휴 신청을 합니다. * [제휴 문의](https://with.kakao.com/proposition?type=service\&page=gameplay) ### 게임 입점 협의 게임플레이와 제휴 계약을 마친 파트너사는 카카오 담당자와 입점 게임을 협의합니다. 첫 게임뿐만 아니라 이후 추가하는 게임도 게임별 입점 협의를 진행해야 합니다. 기본적으로 **전체이용가·12세이용가 등급** 및 **풀스크린 게임** 입점을 원칙으로 합니다. * [입점 정책](/docs/policy/onboarding) ## 2단계: 연동 준비 제휴 계약과 게임 입점 협의가 완료되면 게임 실행 흐름을 먼저 확인하고, 연계 서비스와 개발 환경을 준비합니다. ### 게임 실행 흐름 확인 개발 환경을 준비하기 전에 [게임 실행 흐름](/docs/webview/launch-flow)을 확인합니다. 카카오가 사용자와 게임의 진입 조건을 확인해 게임 URL을 불러온 뒤, 파트너사가 카카오싱크로 사용자 인증과 약관 동의를 처리하고 게임을 실행하는 순서를 안내합니다. ### 연계 서비스·실행 환경 안내 게임플레이에 게임을 연동하려면 여러 카카오 서비스와 실행 환경을 사용해야 합니다. 각 이름이 무엇을 뜻하는지 먼저 확인하면 이후 안내를 더 쉽게 이해할 수 있습니다. 카카오디벨로퍼스, 카카오톡 채널, 파트너센터, 카카오 애드핏은 서로 다른 플랫폼입니다. 같은 카카오계정으로 로그인하더라도 각 서비스를 사용할 권한이 있는지 따로 확인해야 합니다. ### 사전 준비 아래 순서대로 계정과 회사·게임 정보를 준비합니다. 회사에서 이미 사용 중이라면 새로 만들지 않고 담당자의 설정 권한부터 확인하세요. 사전 준비가 끝나면 아래 [3단계: 개발 연동](#_3단계-개발-연동)에서 구현할 기능과 적용 여부를 확인합니다. API와 SDK의 전체 목록과 용도는 [API & SDK 개요](/api-sdk/)를 참고하세요. ## 3단계: 개발 연동 파트너사가 게임에 아래 항목을 구현합니다. 표에서 항목별 적용 여부를 확인하고, 세부 방식은 게임 특성에 따라 카카오 담당자와 협의합니다. 전체 API와 SDK의 용도와 호출 방향은 [API & SDK 개요](/api-sdk/)에서 확인할 수 있습니다. ## 4단계: 심사 요청 게임 정보 입력과 개발 연동을 마친 뒤 [심사 체크리스트](/docs/checklist/review-checklist)에 따라 파트너사 자체 점검을 완료합니다. 출시 심사는 게임 정보와 개발 연동을 함께 확인합니다. 파트너센터에서 아래 두 범위를 모두 준비한 뒤 하나의 출시 심사로 요청합니다. 모든 준비를 마치면 게임플레이 파트너센터에서 **출시 심사**를 요청하고, 심사 현황에서 승인·반려 결과와 항목별 반려 사유를 확인합니다. 신규 게임은 출시 심사를 승인받아야 출시할 수 있습니다. 상세 절차와 일정은 [심사 가이드](/docs/checklist/review-guide)를 참고하세요. ## 5단계: 출시 및 서비스 운영 출시 심사를 승인받은 게임은 **매주 화요일 오전 11시**에 출시합니다. 오픈 이후에도 게임플레이 운영 정책 및 가이드를 지속적으로 준수해야 합니다. 게임 내 중요 기능 또는 콘텐츠 업데이트가 있는 경우 배포 전에 카카오에 사전 공유해야 합니다. * [운영 원칙](/docs/policy/overview): 게임플레이 운영의 공통 기준 * [출시 및 업데이트 정책](/docs/policy/launch): 출시·업데이트 심사 기준 * [서비스 운영](/docs/policy/operations): 게임 노출, CS, 장애·점검, 서비스 종료 기준 * [데이터 보호 정책](/docs/policy/implementation): 개인정보와 이용자 데이터 관리 기준 * [정산](/docs/policy/settlement): 매출 정산 절차와 이의 제기 기준 * [PR 및 대외 커뮤니케이션](/docs/policy/pr): 서비스명과 지표의 대외 표기 기준 ## 문의 채널 --- --- url: /docs/webview/launch-flow.md description: 게임웹뷰 진입부터 게임 실행까지의 동선 안내 --- # 게임 실행 흐름 게임웹뷰에서 파트너사의 게임이 실행되기 전, 카카오가 확인하는 진입 조건과 화면 분기 흐름을 설명합니다. 정상 진입 시에는 카카오가 공통으로 제공하는 게임 스플래시 화면을 거쳐 게임으로 이동하며, 조건에 따라 약관 동의나 안내 화면으로 이동할 수 있습니다. 카카오가 제공하는 영역이나 인증·공유·데이터 연동 설계 시 반드시 참고해 주세요. ## 실행 주체 파트너사는 게임 URL이 로드된 이후를 담당합니다. 그 이전은 카카오가 제공합니다. | 구간 | 담당 | | --- | --- | | 웹뷰 실행 및 진입 조건 판단 | 카카오 | | 스플래시·조건별 분기/안내 화면 | 카카오 | | 게임 초기화·화면 실행 (URL 호출 이후) | 파트너사 | ## 전체 흐름 ## 조건별 화면 분기 카카오는 게임 URL을 호출하기 전에 사용자 상태와 게임 운영 상태, 등록된 실행 도메인을 확인합니다. 조건을 충족하지 않으면 아래와 같이 안내 화면을 노출하거나 게임 실행을 차단합니다. | 조건 | 분기 화면 | 화면 예시 | | --- | --- | --- | | 서비스 약관 미동의 | 약관 동의 화면 | | | 만 14세 미만 사용자 | 법정대리인 동의 안내 | | | 미성년자 보호조치 대상 | 청소년 보호 안내 화면 | | | 카카오톡 버전이 최소 지원 미만 | 구버전 안내 화면 | | | 게임 서비스 종료 상태 | 종료된 게임 안내 화면 | | | 등록되지 않은 게임 실행 도메인 | 게임 실행 차단 | 화면 없음 | | 카카오싱크 미동의 (파트너사 앱) | 싱크 동의창 | | | 모든 조건 충족 | 스플래시 → 게임 실행 | | 게임 실행 도메인 등록 기준은 [게임웹뷰 SDK: 실행 조건](/api-sdk/sdk/kakaotalk-gameplay#실행-조건)을 참고하세요. ## 게임 URL 접근 분기 사용자가 게임웹뷰가 아닌 PC 또는 모바일 브라우저에서 게임 URL에 직접 접근하면 파트너사는 카카오가 안내한 주소로 리다이렉트해야 합니다. 리다이렉트 이후의 환경별 안내 화면과 카카오톡 실행 분기는 카카오가 제공합니다. ### PC 접근 PC 웹에서 게임 URL에 직접 접근하면 게임 진입을 제한하고 `gameplay.kakao.com`으로 리다이렉트합니다. 리다이렉트가 완료되면 카카오가 PC용 안내 화면을 노출합니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 확인 상황 | PC 웹에서 게임 URL에 직접 접근 | | 리다이렉트 URL | `gameplay.kakao.com` | | 분기 화면 제공 | 카카오 | ### 모바일 접근 모바일 브라우저에서 게임 URL에 직접 접근하면 카카오가 안내한 주소로 리다이렉트합니다. 카카오는 카카오톡 설치 여부와 지원 버전을 확인해 게임 실행 또는 안내 화면으로 분기합니다. | 사용자 환경 | 카카오 분기 | | --- | --- | | 카카오톡 설치 및 지원 버전 충족 | 카카오톡 게임웹뷰로 연결 | | 카카오톡 미설치 | 카카오톡 설치 안내 화면 | | 카카오톡 지원 버전 미만 | 카카오톡 업데이트 안내 화면 | ## 파트너사 연동 핵심 포인트 * 게임 URL이 로드되는 시점에는 이미 카카오톡 계정 세션이 준비되어 있습니다. 설정은 [카카오싱크 설정](/docs/authentication/kakao-login-sync), 구현 스펙은 [카카오싱크 API](/api-sdk/kakaosync/rest-api)를 참고하세요. * 카카오톡 게임웹뷰에서만 실행되어야 합니다. UserAgent 검증 등 개발 기준은 [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay)를 참고하세요. * 게임 종료 후 웹뷰가 닫히는 조건은 파트너사 게임 로직에서 처리합니다. ## 참고 문서 * [게임웹뷰](/docs/webview/overview): 게임웹뷰의 역할과 전체 개발 순서 * [카카오싱크 설정](/docs/authentication/kakao-login-sync) * [카카오싱크 API](/api-sdk/kakaosync/rest-api) * [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay) * [상태바 오버레이 설정 방법](/docs/webview/status-bar-overlay) --- --- url: /docs/checklist/review-guide.md description: 신규 게임의 출시 심사와 출시 게임의 업데이트 심사 요청·진행·배포 일정 --- # 심사 가이드 신규 게임의 **출시 심사**와 출시된 게임의 **업데이트 심사** 절차를 안내합니다. 심사를 요청하기 전에 [심사 체크리스트](/docs/checklist/review-checklist)에 따라 게임 정보와 개발 연동에 대한 **파트너사 자체 점검**을 완료하세요. 모든 심사는 게임플레이 파트너센터에서 요청하고 결과를 확인합니다. 심사 유형은 변경 대상과 시점에 따라 구분합니다. 신규 게임은 출시 심사를 승인받아야 출시할 수 있습니다. 심사 소요 일정은 심사 대기 목록에 따라 달라질 수 있습니다. ## 심사 구분 ## 출시 심사 출시 이력이 있는 파트너사의 신규 게임은 매주 화요일 오전 11시에 출시합니다. 매주 화요일까지 접수된 출시 심사와 재심사 요청을 수·목요일에 요청 순서대로 심사합니다. 신규 게임은 파트너센터에 게임 정보를 모두 입력하고 개발 연동과 자체 점검을 완료한 뒤 **출시 심사**를 요청합니다. 게임 정보와 개발 연동을 함께 확인하며, 승인·반려 결과와 반려 사유도 파트너센터에서 확인합니다. 출시 요일과 시간은 고정이며, 실제 출시 주차는 게임별로 카카오와 협의합니다. 단, 파트너사의 첫 게임 출시 심사는 카카오와 사전 협의하여 별도로 진행합니다. 최초 연동 심사가 포함되므로 심사 범위가 넓고 더 오래 걸릴 수 있습니다. ## 업데이트 심사 출시한 게임의 게임 정보 또는 개발 연동을 변경할 때 요청합니다. 변경 대상에 맞는 정보를 게임플레이 파트너센터에 입력하고 업데이트 심사를 요청하세요. ### 게임 정보 변경 게임 설명문구, 게임 앱 아이콘, 프로모션 이미지, 게임 링크, 장르, 등급, 랭킹 설정 등 파트너센터에서 관리하는 게임 정보를 변경하는 경우입니다. 파트너센터에서 정보를 수정한 뒤 **업데이트 심사**를 요청합니다. 출시된 게임의 변경 내용은 심사 승인 전까지 서비스에 반영되지 않습니다. ### 개발 연동 변경 카카오싱크·게임웹뷰·공유·광고 SDK·액션데이터·Tiara Web SDK를 통한 게임 로그 수집·전송 등 메타데이터 외 개발 연동을 변경하는 경우입니다. 매주 화요일까지 업데이트 심사를 요청한 게임을 대상으로 주 1회 심사하며, 승인된 게임만 배포할 수 있습니다. 파트너센터에서 변경한 연동 항목을 선택하고 항목별 수정 사항과 자체 점검 결과를 입력하세요. 수정 사항이 반영된 테스트 게임 URL이 있다면 함께 입력합니다. 게임 정보와 개발 연동을 함께 변경한다면 하나의 업데이트 심사에 변경 내용을 모두 입력합니다. 게임 실행 환경과 테스트 링크 사용 방법은 [게임웹뷰 테스트 방법](/docs/webview/test-guide)을 참고하세요. ## 심사 없이 진행하는 변경 카카오 연동 범위와 게임 정보 외의 게임 자체 콘텐츠 업데이트 및 수정은 심사가 필요하지 않습니다. 업데이트 내용과 배포 시점을 업데이트 노트에 작성하여 카카오에 공유한 뒤, 별도 심사 일정 없이 진행할 수 있습니다. ## 참고 문서 * [입점 안내](/docs/checklist/start-guide): 입점부터 출시까지의 전체 단계 * [심사 체크리스트](/docs/checklist/review-checklist): 심사 요청 전 파트너사 자체 점검 항목 * [게임웹뷰 테스트 방법](/docs/webview/test-guide): 카카오톡과 테스트 앱에서 게임을 확인하는 방법 * [출시 및 업데이트 정책](/docs/policy/launch): 출시·업데이트 심사 기준 --- --- url: /docs/checklist/review-checklist.md description: 출시·업데이트 심사를 요청하기 전에 파트너사가 확인해야 하는 자체 점검 항목 --- # 심사 체크리스트 출시 심사와 업데이트 심사를 요청하기 전에 파트너사가 확인해야 하는 항목을 정리한 체크리스트입니다. 해당 범위의 항목을 확인하고 **파트너사 자체 점검**을 완료하세요. * **게임 정보**: 게임플레이 파트너센터에 입력한 내용을 확인합니다. 신규 게임은 출시 심사를, 출시된 게임의 정보 변경은 업데이트 심사를 파트너센터에서 요청합니다. * **개발 연동**: 카카오싱크·게임웹뷰·공유·광고·액션데이터·Tiara Web SDK를 통한 게임 로그 수집·전송 등을 확인합니다. 출시된 게임의 연동을 변경한다면 파트너센터에서 변경 항목과 수정 사항·자체 점검 결과를 입력하고 업데이트 심사를 요청합니다. `적용 여부`가 **조건부**인 항목은 해당 OS·기능·운영 방식에 해당하는 경우 반드시 확인합니다. **권장**은 반드시 적용해야 하는 항목은 아니지만 적용을 권장합니다. **옵션**은 적용하지 않을 수 있으며, **옵션·권장**은 선택 기능이지만 적용을 권장하는 항목입니다. | 구분 | 적용 대상 | 확인 시점 | | --- | --- | --- | | 파트너사 단위 연동 체크리스트 | 게임플레이에 처음 연동하는 파트너사 | 최초 연동 시 파트너사 단위로 1회 확인. 공통 설정이나 연동 구조가 변경되면 다시 확인 | | 게임 단위 연동 체크리스트 | 최초 연동 게임을 포함해 출시하는 모든 게임 | 게임을 출시하거나 기존 게임의 연동 사양을 변경할 때마다 확인 | ## 파트너사 단위 연동 체크리스트 게임플레이 최초 연동 시 파트너사 단위로 1회 확인하는 항목입니다. 파트너사 공통으로 설정해 여러 게임이 함께 사용하며, 공통 설정이나 연동 구조가 변경되면 다시 확인합니다. ### 디벨로퍼스 설정 관련: [카카오싱크 설정](/docs/authentication/kakao-login-sync), [카카오싱크 API](/api-sdk/kakaosync/rest-api), [친구 목록 조회 API](/api-sdk/kakaotalk-social/friends) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 디벨로퍼스 앱 | 게임플레이 연동에 사용할 파트너사 공통 앱을 생성하고 카카오 로그인을 활성화했는지 확인하세요. | 필수 | | 앱 기본 정보 | 앱 이름·아이콘·회사명·대표 도메인이 실제 서비스 및 입점 정보와 일치하는지 확인하세요. | 필수 | | 비즈 앱 전환 | 사업자 정보를 등록해 디벨로퍼스 앱을 비즈 앱으로 전환했는지 확인하세요. | 필수 | | 비즈니스 채널 연결 | 비즈니스 채널을 생성하고 비즈 앱과 연결했는지 확인하세요. | 필수 | | 비즈니스 정보 심사 | 비즈니스 정보 심사를 완료했는지 확인하세요. | 필수 | | 디벨로퍼스 앱 ID | 앱 생성 후 앱 ID를 카카오 담당자에게 전달했는지 확인하세요. | 필수 | | Redirect URI | 카카오 로그인에 운영 Redirect URI를 등록하고 인가 코드 요청의 `redirect_uri`와 정확히 일치하는지 확인하세요. | 필수 | | 자동 로그인 | 게임 URL 진입 즉시 `prompt` 없이 인가 코드를 요청하는지 확인하세요. 로그인 버튼이나 별도 로그인 화면을 노출하지 않는지 확인하세요. | 필수 | | 사용자 식별 | 카카오 회원번호를 파트너사 서비스의 사용자 식별자로 연동했는지 확인하세요. | 필수 | | 로그인 동의 항목 | `닉네임, 프로필 사진`을 설정했는지 확인하세요. 그 외 항목은 카카오와 협의했는지 확인하세요. | 필수 | | 서비스 약관 | 파트너사 서비스 약관·개인정보 수집 및 이용·제3자 개인정보 제공 동의를 필수 동의로 등록했는지 확인하세요. | 필수 | | 서비스 약관 | 동의 항목명을 카카오싱크 가이드에 맞춰 설정했는지 확인하세요. | 필수 | | 간편가입 | 등록한 서비스 약관과 카카오싱크 간편가입의 사용 설정을 `ON`으로 변경했는지 확인하세요. | 필수 | | 연령 동의 | 만 14세 이상 연령 동의 기능을 설정했는지 확인하세요. | 필수 | | 제3자 제공 동의문 | 전문 링크에 게임플레이가 제공한 링크를 입력했는지 확인하세요. | 필수 | | 제3자 제공 동의문 | 동의문 페이지에 파트너사명이 정상적으로 노출되는지 확인하세요. | 필수 | | 친구 목록 조회 | 친구 정보 기능을 제공하는 경우 `friends` 동의항목 사용 권한과 선택 동의 설정을 완료했는지 확인하세요. 가입 시 미동의 사용자의 추가 동의 흐름과 쌍방 동의 조건을 확인하세요. | 옵션 | | 계정 상태 변경 웹훅 | 디벨로퍼스의 카카오 로그인 > 계정 상태 변경 웹훅에 수신 URL을 등록했는지 확인하세요. | 필수 | ### 파트너센터 사전 등록 관련: 게임플레이 파트너센터 | 항목 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 사전 등록 정보 전달 | 회사 이름·사업자등록번호·사업자등록증·디벨로퍼스 앱 ID·화이트리스트 도메인·IP를 카카오 담당자에게 전달했는지 확인하세요. | 필수 | | 등록 결과 확인 | 카카오가 등록한 회사·개발 정보가 파트너센터에 올바르게 표시되는지 확인하세요. | 필수 | | 직접 입력 정보 | 파트너센터에서 게임 배급업 신고번호와 법인등록번호를 입력했는지 확인하세요. | 필수 | ### 공통 API 및 웹훅 최초 연동 관련: [액션데이터 API](/api-sdk/data/action-data), [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal), [공유 설정](/docs/share/settings) | 연동 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 카카오싱크 API | 인가 코드 요청·토큰 발급·사용자 정보 조회·서비스 약관 동의 내역 조회·토큰 갱신을 모두 구현하고 테스트했는지 확인하세요. | 필수 | | 요청 상태 검증 | 인가 코드 요청마다 예측하기 어려운 `state` 값을 생성하고 콜백의 값과 비교해 일치하지 않는 요청을 중단하는지 확인하세요. | 필수 | | 인증 정보 보안 | REST API 키·클라이언트 시크릿·액세스 토큰·리프레시 토큰을 파트너사 서버에서만 사용하고 안전하게 보관하는지 확인하세요. | 필수 | | 액션데이터 API | 액션데이터 전송 경로와 응답 처리를 구현하고 연동 테스트를 완료했는지 확인하세요. | 필수 | | 단축 URL 생성 API | 호출 서버 또는 테스트 환경 IP를 카카오와 협의하고 `short_url` 응답을 확인하세요. | 필수 | | 공유 결과 웹훅 | 공유 결과 매칭이 필요한 경우 웹훅 수신과 결과 처리를 테스트했는지 확인하세요. | 옵션 | | 계정 상태 변경 웹훅 | SET 검증에 성공한 이벤트만 처리하고 `reason`에 따라 약관 철회와 앱 연결 해제를 구분하는지 확인하세요. | 필수 | | 데이터 파기 | 철회·연결 해제 수신 시 사용자 데이터 파기와 카카오 대상 데이터 전송 중지를 처리하는지 확인하세요. | 필수 | | 웹훅 수신 테스트 | 약관 철회·앱 연결 해제 이벤트의 수신부터 데이터 처리까지 통합 테스트를 완료했는지 확인하세요. | 필수 | ### 게임 URL 접근 분기 최초 연동 관련: [게임 실행 흐름: 게임 URL 접근 분기](/docs/webview/launch-flow#게임-url-접근-분기) | 접근 환경 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 도메인 화이트리스트 | 샌드박스·운영·테스트용 게임웹뷰 실행 도메인을 카카오 담당자에게 전달하고 등록 완료를 확인했는지 확인하세요. | 필수 | | PC 웹 | 게임 URL에 직접 접근하면 게임을 실행하지 않고 `gameplay.kakao.com`으로 리다이렉트하는지 확인하세요. 카카오가 제공하는 PC 안내 화면이 노출되는지 확인하세요. | 필수 | | 모바일 웹 | 게임 URL에 직접 접근하면 카카오가 안내한 주소로 리다이렉트하는지 확인하세요. 카카오톡 설치 여부와 지원 버전에 따라 게임 실행·설치 안내·업데이트 안내 화면으로 분기되는지 확인하세요. | 필수 | | 게임웹뷰 | 카카오톡 게임웹뷰에서 정상 진입한 사용자는 외부 접근 분기로 리다이렉트되지 않고 게임이 실행되는지 확인하세요. | 필수 | | 게임웹뷰 구분 | User-Agent에 `PFCUSTOM`과 `KAKAOTALK`이 함께 있는지 확인해 일반 카카오톡 인앱 웹뷰와 게임웹뷰를 구분하는지 확인하세요. | 필수 | ## 게임 단위 연동 체크리스트 최초 연동 게임을 포함해 파트너사가 출시하는 모든 게임에서 확인하는 항목입니다. 동일한 디벨로퍼스 앱과 공통 API를 사용하더라도 게임별 설정값·화면·데이터가 올바르게 연결되는지 확인하세요. ### 게임 정보 관련: 게임플레이 파트너센터 | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 게임 등급 정보 | 파트너센터에 등급분류증명서를 등록했는지 확인하세요. | 필수 | | 게임 정보 | 파트너센터의 게임 관리에서 해당 게임의 정보를 등록했는지 확인하세요. | 필수 | | 게임 콘텐츠 정보 | 게임 이름·설명문구·앱 아이콘·프로모션 이미지를 가이드 규격에 맞춰 등록했는지 확인하세요. | 필수 | | 공유 이미지 | 프로모션 이미지와 같은 `1200 × 630` 규격의 공유 이미지를 등록했는지 확인하세요. | 필수 | | 게임 등급 정보 | 이용 등급·등급 분류 번호·등급 분류 일자·상호·제작·배급업 등록 번호·게임물 내용 정보·확률형 아이템 여부를 모두 등록했는지 확인하세요. | 필수 | | 최초 로드 용량 | 100 MB 이하인지 확인하세요. | 필수 | | 풀스크린 | 상태바 영역까지 확장하는 풀스크린 게임인지 확인하세요. 적용할 수 없다면 카카오와 사전 협의했는지 확인하세요. | 필수 | | 게임 모드 | 가로 모드 게임이라면 카카오와 협의가 필요해요. | 조건부 | ### 인증 및 연결 해제 관련: [카카오싱크 설정](/docs/authentication/kakao-login-sync), [카카오싱크 API](/api-sdk/kakaosync/rest-api), [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 디벨로퍼스 앱 | 기존 게임에 적용한 파트너사 공통 디벨로퍼스 앱을 동일하게 적용했는지 확인하세요. | 필수 | | 자동 로그인 | 별도의 로그인 화면 없이 자동 로그인이 처리되는지 확인하세요. | 필수 | | 미동의 사용자 | 카카오싱크 간편가입창이 노출되는지 확인하세요. | 필수 | | 동의 사용자 | 간편가입창을 다시 노출하지 않고 게임이 실행되는지 확인하세요. | 필수 | | 사용자 식별 | 게임 실행 시 사용자의 `AppUserId`가 정상적으로 연동되는지 확인하세요. | 필수 | | 실행 전환 | 동의 완료 후 별도의 브릿지 페이지 없이 게임이 실행되는지 확인하세요. | 필수 | | 앱 연결 해제 | 해당 게임이 앱 연결 해제 처리 대상에 포함되는지 확인하세요. | 필수 | | 데이터 파기 | 앱 연결 해제 시 해당 게임의 사용자 데이터가 즉시 파기되는지 확인하세요. | 필수 | | 동의 철회 | 카카오의 동의 철회 수신 시 해당 게임 데이터도 연동 해제·파기되는지 확인하세요. | 필수 | | 수신 테스트 | 해당 게임을 포함해 동의 철회 웹훅 수신 테스트를 완료했는지 확인하세요. | 필수 | ### 웹뷰 디자인 관련: [게임 공통 제작 가이드](/docs/design/common-guide), [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 해상도 | 모바일 360px 기준의 플렉서블 레이아웃을 적용했는지 확인하세요. | 필수 | | 글자 | 가이드에 맞는 폰트와 글자 크기를 적용했는지 확인하세요. | 필수 | | 태블릿 | 태블릿과 Android 폴드 기종에서 가이드대로 노출되는지 확인하세요. | 필수 | | 내비게이션 바 | 가이드대로 적용하고 게임 기능과 겹치지 않도록 구성했는지 확인하세요. | 필수 | | 게임 접기 기능 (iOS) | iOS 내비게이션 바에 게임 접기 버튼을 적용했는지 확인하세요. | 필수 | | 로딩 | 가이드에 맞는 로딩 아이콘을 적용했는지 확인하세요. | 필수 | | 토스트 | 가이드에 맞는 토스트를 적용하고 적용 상황을 정리했는지 확인하세요. | 옵션 | | 유료 데이터 안내 | Wi-Fi 연결 여부에 따라 유료 데이터 환경 고지 문구를 노출하는지 확인하세요. | 필수 | | 100 MB 초과 안내 | 카카오와 사전 협의해 100 MB를 초과하는 게임이라면 토스트 대신 팝업으로 유료 데이터 사용을 안내하는지 확인하세요. | 조건부 | | 바텀시트 | 사용하는 경우 가이드에 맞게 적용했는지 확인하세요. | 옵션 | ### 내비게이션 바 메뉴 | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 메뉴 순서 | 더보기 메뉴에 공유하기·문의하기를 순서대로 적용했는지 확인하세요. | 필수 | | 메뉴 개수 | 전체 메뉴는 최대 3개까지, 선택 메뉴는 최대 1개까지 적용 가능한지 확인하세요. | 필수 | | 공유하기 | 카카오가 제공한 공유 설정을 적용했는지 확인하세요. | 필수 | | 문의하기 | 사용자 문의를 받을 수 있는 기능을 제공하는지 확인하세요. | 필수 | | 고객센터 URL | 사용자 문의를 받을 고객센터 URL을 적용했는지 확인하세요. | 권장 | | 별도 URL | 별도 고객센터 URL을 적용했다면 클릭 시 웹뷰 위의 인앱브라우저로 실행되는지 확인하세요. | 조건부 | | 고객센터 도메인 | 고객센터 URL을 적용했다면 게임 실행 도메인과 분리된 도메인을 사용하는지 확인하세요. | 조건부 | | 대체 문의 방식 | 별도 고객센터 페이지가 없다면 적용한 문의 방식을 정리했는지 확인하세요. | 조건부 | | 추가 메뉴 | 공유하기·문의하기 외에 추가한 메뉴가 있다면 메뉴명과 동작을 정리했는지 확인하세요. | 옵션 | ### 종료 팝업 및 게임웹뷰 기능 관련: [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay), [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 종료 팝업 | 게임 종료 버튼을 누르면 가이드에 맞는 종료 안내 팝업이 노출되는지 확인하세요. | 필수 | | Android 뒤로가기 | 종료 팝업이 열린 상태에서 뒤로가기를 누르면 팝업만 닫히는지 확인하세요. | 필수 | | 테스트 환경 | 신규 메서드를 확인할 수 있도록 카카오톡 최신 버전에서 테스트했는지 확인하세요. | 필수 | | 안전영역 | `safeArea` 메서드를 적용하고 게임 기능이 내비게이션 바·상태바와 겹치지 않는지 확인하세요. | 필수 | | 게임 접기 기능 (iOS) | iOS에서 게임 접기와 복귀가 정상적으로 동작하는지 확인하세요. | 필수 | | 사운드 | 사운드를 제공하는 경우 무음 상태에서 재생되지 않도록 처리했는지 확인하세요. | 조건부 | | 햅틱 | 햅틱 기능을 사용하는 경우 지원 여부와 동작을 확인하세요. | 옵션 | | 에러 안내 | 자동 복구 가능한 오류는 토스트, 복구할 수 없는 오류는 재시도·종료 버튼이 있는 팝업으로 처리했는지 확인하세요. | 필수 | ### 공유 설정 관련: [공유 설정](/docs/share/settings), [공유 웹훅 연동](/api-sdk/share/reward-result) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | SDK 및 앱 키 | 카카오 JS SDK 2.8.0 이상과 파트너사 앱의 JavaScript 키를 사용했는지 확인하세요. | 필수 | | 도메인 | 제품 링크와 JavaScript SDK 도메인에 게임플레이·테스트·운영 도메인을 등록했는지 확인하세요. | 필수 | | 공유 템플릿 | 카카오가 제공한 템플릿 ID를 적용했는지 확인하세요. CBT `126532`, PROD `126533` | 필수 | | 기본 공유 | 기본 공유를 적용했는지 확인하세요. | 필수 | | 자랑하기 공유 | 게임에 자랑하기 공유를 적용했는지 확인하세요. | 옵션·권장 | | 보상형 공유 | 게임에 보상형 공유를 적용했는지 확인하세요. | 옵션·권장 | | `templateArgs` | `THU`, `TITLE`, `DESCRIPTION`, `BUTTON_TEXT`, `BUTTON_URL`을 적용하고 글자수·이미지 접근성을 확인하세요. | 필수 | | `pickerSettings` | `limit: 1`, `type: default`, 환경별 `groupId`, `logs.section`, `customProps`를 적용했는지 확인하세요. | 필수 | | `serverCallbackArgs` | `APP_USER_ID`, `APP_ID`, `GAME_TYPE`, `MESSAGE_TYPE`, `HAS_REWARD`를 적용했는지 확인하세요. | 필수 | | `SHARE_ID` | 보상 결과 매칭이 필요한 경우 적용했는지 확인하세요. | 옵션 | | 단축 URL | `short_url`을 `templateArgs.BUTTON_URL`과 `pickerSettings.args.copy_url`에 동일하게 적용했는지 확인하세요. | 필수 | | 공유 로그 | 공유 유형에 맞춰 `gameplay_message_type` 등 로그 값을 설정했는지 확인하세요. | 필수 | | 공유 웹훅 | 공유 웹훅을 사용하는 경우 수신과 결과 처리를 확인하세요. | 옵션 | | 공유 테스트 | 적용한 공유 유형별 메시지 발송과 랜딩을 확인하세요. CBT 완료 후 PROD용 메시지 ID로 전환했는지 확인하세요. | 필수 | ### 광고 관련: [광고 상품 소개](/docs/ads/product-overview), [광고 UX 가이드](/docs/ads/ux-guideline), [애드핏 설정](/docs/ads/iaa-options), [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test), [민감 카테고리 차단 설정](/docs/ads/adfit-sensitive-categories), [애드핏 광고 SDK](/api-sdk/sdk/adfit) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 매체 등록 | 카카오톡 Android·iOS 매체를 각각 등록하고 파트너사 계정 화이트리스트 처리를 완료했는지 확인하세요. | 필수 | | 민감 카테고리 | Android·iOS 매체에서 가이드의 민감 카테고리 14종을 모두 차단했는지 확인하세요. | 필수 | | 채널 ID | 카카오가 제공한 채널 ID를 적용했는지 확인하세요. | 필수 | | CPID | 파트너센터에 등록한 게임 코드와 동일하게 적용했는지 확인하세요. | 필수 | | Safe Area 설정 | 리워드·전면형 광고를 운영할 때 게임웹뷰에서 받은 Safe Area 값을 가공하지 않고 애드핏 광고 SDK에 전달했는지 확인하세요.값이 `0`인 경우에도 `0`으로 전달하세요. | 필수 | | 광고 상품 | 적용할 광고 상품을 선택하고 상품별 노출 시점을 정리했는지 확인하세요. | 필수 | | 광고단위 | 파트너사가 선택한 발급 기준에 따라 OS별 공통 광고단위 또는 게임별 광고단위를 적용했는지 확인하세요. | 필수 | | 광고단위 유형 | 리워드는 게임 화면 방향에 맞는 동영상·동영상/이미지 유형 2개를 함께 선택하고, 전면형은 `전면형_이미지`를 선택했는지 확인하세요. | 필수 | | 적용 정보 | 적용한 광고단위 ID를 정리했는지 확인하세요. | 필수 | | 광고 노출 방식 | 사용자가 광고 노출을 인지하고 버튼 선택 등 명확한 행동을 한 뒤에만 광고를 노출하는지 확인하세요.자동·반복·강제 노출이 없는지 확인하세요. | 필수 | | 광고 UI 구분 | 서비스 화면과 광고를 명확히 구분하고 광고를 게임 기능처럼 보이게 구성하지 않았는지 확인하세요. | 필수 | | 광고 배치 | 오클릭을 유발하는 위치, 콘텐츠를 가리는 영역, 핵심 행동 중이거나 백그라운드인 상태에 광고를 노출하지 않는지 확인하세요. | 필수 | | 노출 테스트 | 광고 테스트 기능으로 상품별 소재 노출과 닫기 동작을 확인하세요. | 필수 | | 대체 광고 | 리워드 대체 광고를 사용하는 경우 MP4·랜딩 URL·소재 설명과 Safe Zone 기준을 확인하세요. | 옵션 | | 테스트 설정 해제 | 테스트 종료 후 `실 소재 노출 중단`을 `미설정`으로 변경했는지 확인하세요. | 필수 | ### 게임 로그 관련: [게임 로그 설정](/api-sdk/sdk/tiara-game-logs), [Tiara Web SDK](/api-sdk/sdk/tiara-web) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 필수 게임 로그 | [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의)의 11종 로그를 모두 적용했는지 확인하세요. | 필수 | | 게임 코드 | `Section`의 `{게임ID}`에 파트너센터 게임 코드를 적용했는지 확인하세요. 게임 이름·공백은 사용할 수 없어요. | 필수 | | 서비스 도메인 | `svcDomain`에 `gameplay.kakao.com`을 입력했는지 확인하세요. | 필수 | | 제3자 동의 | `thirdProvideAgree`를 `true`로 설정했는지 확인하세요. | 필수 | | 사용자 식별 | 카카오 사용자 식별값인 `AccessToken` 또는 `AppUserId`를 설정했는지 확인하세요. | 필수 | ### 액션데이터 관련: [액션데이터 API](/api-sdk/data/action-data) | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | `game_id` | 전송하는 `game_id`가 파트너센터에 등록한 게임 코드와 일치하는지 확인하세요. | 필수 | | 라벨 | `Loading`부터 `Exit_Play`까지 상황에 맞는 필수 라벨을 적용했는지 확인하세요. | 필수 | | `Complete_Loading` | 게임 로딩 완료 시점에 세션마다 1회 전달하는지 확인하세요. | 필수 | | `Complete_Play` | 랭킹을 사용하는 경우 랭킹에 기록할 정상 완료 시점에 `action_data`를 함께 전달하는지 확인하세요. | 조건부 | | `Exit_Play` | 전송 시 `Loading`부터 누적한 `play_time`을 전달하는지 확인하세요. | 필수 | | 광고 라벨 | 광고 노출 시점에 `Ad_Reward_`·`Ad_Normal_` 라벨을 전송하는지 확인하세요. | 필수 | ### 랭킹 관련: 게임플레이 파트너센터, [액션데이터 API](/api-sdk/data/action-data), 랭킹 데이터 스펙 | 상세 | 체크 항목 | 적용 여부 | | --- | --- | --- | | 제공 여부 | 게임의 랭킹 제공 여부를 확인하세요. | 필수 | | 랭킹 제공 | 파트너센터에서 랭킹 사용 여부·집계 기간·랭킹 지표를 설정했는지 확인하세요. | 조건부 | | 기록값 | 액션데이터 `action_data`의 키가 파트너센터에 설정한 랭킹 지표와 일치하는지 확인하세요. | 조건부 | | 랭킹 미제공 | 파트너센터에서 랭킹 사용 여부를 `미사용`으로 설정했는지 확인하세요. | 조건부 | ### 최종 확인 | 체크 항목 | 적용 여부 | | --- | --- | | 해당 게임에 적용한 연동 사양을 모두 테스트하고 결과를 확인하세요. | 필수 | | 게임 정보의 필수 입력값을 모두 채우고 파트너센터에서 해당하는 출시 심사 또는 업데이트 심사를 요청했는지 확인하세요. | 필수 | | 개발 연동 체크 결과와 예외·미적용 사유를 파트너센터의 심사 항목에 입력했는지 확인하세요. | 필수 | | 출시된 게임의 개발 연동을 변경한다면 항목별 수정 사항과 자체 점검 결과를 입력하고 업데이트 심사를 요청했는지 확인하세요. | 필수 | ## 참고 문서 * [심사 가이드](/docs/checklist/review-guide) * [입점 안내](/docs/checklist/start-guide) --- --- url: /docs/authentication/kakao-login-sync.md description: 게임플레이 입점 파트너사가 카카오싱크 간편가입을 사용하기 위한 앱·채널·동의항목·서비스 약관 설정 방법 --- # 카카오싱크 설정 게임플레이에 입점하는 파트너사는 카카오 로그인과 카카오싱크 간편가입을 사용해 사용자 인증과 동의를 처리해야 합니다. 이 문서는 카카오싱크 연동 전 카카오디벨로퍼스에서 완료해야 하는 앱, 채널, 동의항목, 서비스 약관 설정을 안내합니다. 실제 인가 코드 요청부터 토큰 발급, 회원 등록, 서비스 세션 생성까지의 구현 방법은 [카카오싱크 API](/api-sdk/kakaosync/rest-api)를 참고하세요. | 담당 | 준비 항목 | 확인할 내용 | | --- | --- | --- | | 사업·법무 | 비즈니스 정보, 서비스 약관, 개인정보 동의문 | 서비스에 적용할 약관과 개인정보 제공 항목 검토 | | 기획·운영 | 간편가입 동의 화면, 만 14세 이상 연령 동의 | 가입 과정과 사용자 안내 문구 검토 | | 개발 | 디벨로퍼스 앱, 카카오 로그인, Redirect URI, API | 앱 설정 완료 후 카카오싱크 API 연동 | ## 사전 준비 카카오싱크 연동 전 아래 항목을 순서대로 완료합니다. | 순서 | 설정 항목 | 적용 여부 | | --- | --- | --- | | 1 | 디벨로퍼스 앱 생성과 비즈 앱 전환 | 필수 | | 2 | 비즈니스 채널 생성과 비즈 앱 연결 | 필수 | | 3 | 비즈니스 정보 심사 | 필수 | | 4 | 카카오 로그인 활성화와 Redirect URI 등록 | 필수 | | 5 | 카카오 로그인 동의항목 설정 | 필수 | | 6 | 서비스 약관 등록과 간편가입 활성화 | 필수 | | 7 | 추가 개인정보 동의항목 심사 | 필요한 경우 | | 8 | 테스트 앱과 운영 앱 설정 확인 | 권장 | 설정 순서는 **앱 생성 → 비즈 앱 전환 → 비즈니스 채널 연결 → 동의항목 설정 → 필요한 항목 심사 요청**입니다. 비즈니스 채널이 없다면 먼저 채널을 생성하고 비즈니스 채널 심사를 완료하세요. ## 디벨로퍼스 앱과 비즈 앱 파트너사 단위로 카카오디벨로퍼스 앱을 생성하고 사업자 정보를 등록해 비즈 앱으로 전환합니다. 앱 이름, 아이콘, 회사명은 카카오싱크 동의 화면에 표시되므로 실제 서비스 정보와 일치해야 합니다. 이미 같은 서비스에서 카카오 로그인이나 카카오 API를 사용 중이라면 기존 앱을 사용하세요. 새 앱을 생성하면 기존 앱의 설정과 회원번호가 이어지지 않아 사용자가 다시 가입해야 할 수 있습니다. ::: info 게임플레이 입점 앱 생성 기준 디벨로퍼스 앱은 게임별이 아닌 파트너사 단위로 1개를 생성합니다. 게임플레이 입점 파트너사는 사전 협의에 따른 예외 심사 대상으로 처리됩니다. ::: ### 앱 생성 입력값 새 앱을 생성할 때 파트너사와 운영 게임을 식별할 수 있도록 아래 기준으로 입력합니다. | 입력 항목 | 설정 기준 | | --- | --- | | 앱 이름 | 파트너사명을 입력합니다. | | 회사명 | 게임플레이 제휴 계약과 카카오 담당자에게 전달한 법인·사업자명과 동일하게 입력합니다. | | 카테고리 | `엔터테인먼트`를 선택합니다. | | 앱 대표 도메인 | 동의 화면 등에 표시되는 앱 기본 정보입니다. 파트너사 서비스의 대표 도메인을 입력합니다. | 앱을 생성한 뒤 카카오디벨로퍼스의 앱 설정에서 **앱 ID**를 확인해 카카오 담당자에게 전달하세요. 카카오가 앱 ID와 회사 정보를 등록하면 게임플레이 파트너센터에서 등록된 값을 확인할 수 있습니다. 아래 화면과 같이 앱 정보를 입력합니다. 앱 대표 도메인은 동의 화면 등에 표시되는 앱 기본 정보이며 호출을 허용할 도메인 목록이 아닙니다. 게임 실행 도메인은 아래 두 곳에 각각 등록합니다. | 등록 위치 | 용도 | | --- | --- | | **\[앱] > \[플랫폼 키] > \[JavaScript 키] > \[JavaScript SDK 도메인]** | 카카오 JS SDK 호출을 허용할 도메인입니다. | | **\[앱] > \[제품 링크 관리] > \[웹 도메인]** | 카카오 제품 링크에서 사용할 웹 도메인입니다. | ## 비즈니스 채널 연결 파트너사의 카카오톡 채널이 없다면 [카카오톡 채널 관리자센터](https://center-pf.kakao.com)에서 채널을 먼저 생성합니다. 생성한 채널을 비즈니스 채널로 전환한 뒤 비즈 앱과 연결합니다. 앱과 채널의 사업자 정보가 일치해야 연결 심사를 통과할 수 있습니다. 채널 생성부터 연결까지의 전체 절차는 [카카오싱크 비즈니스 채널 연결](https://developers.kakao.com/docs/ko/kakaosync/prerequisite#business-channel)을 참고하세요. 채널 추가 동의항목을 카카오싱크 동의 화면에 표시하려면 연결한 채널을 대표 채널로 설정합니다. 대표 채널을 설정하지 않으면 동의 화면에 채널 추가 항목이 표시되지 않습니다. ## 비즈니스 정보 심사 카카오디벨로퍼스의 **\[앱] > \[추가 기능 신청] > \[비즈니스 정보]** 에서 심사를 신청합니다. 비즈 앱과 비즈니스 채널이 정상적으로 연결되어 있으면 비즈니스 정보 심사가 자동 승인될 수 있습니다. 추가 개인정보 동의항목 심사가 필요한 경우 심사 사유에 아래 문구를 입력합니다. > 카카오톡 게임플레이 입점 관련 사항으로 사전에 협의 완료 심사 과정에서 문제가 발생하면 카카오 담당자에게 앱 ID와 반려 사유를 전달하세요. ## 카카오 로그인 설정 카카오싱크는 카카오 로그인을 기반으로 동작하므로 다음 설정을 완료해야 합니다. | 설정 | 기준 | | --- | --- | | 카카오 로그인 사용 설정 | **\[카카오 로그인] > \[일반] > \[사용 설정]** 에서 상태를 `ON`으로 설정합니다. | | Redirect URI | 인가 코드를 전달받을 파트너사 서버 URI를 등록합니다. | | 클라이언트 시크릿 | REST API 키는 클라이언트 시크릿이 활성화된 상태로 발급됩니다. 토큰 요청에 `client_secret`을 포함하세요. | | 로그인 시 앱 자동 연결 | 별도 협의가 없다면 기본값인 자동 연결을 사용합니다. | Redirect URI는 게임플레이 서버 도메인 등록과 별개의 설정입니다. 인가 코드 요청에 전달하는 값과 디벨로퍼스에 등록한 값이 정확히 일치해야 합니다. ## 동의항목 설정 카카오로부터 제공받을 사용자 정보와 기능만 동의항목으로 설정합니다. 서비스에 필요하지 않은 정보는 동의받지 않고, 서비스 이용 중 필요한 시점에 추가 동의를 요청하는 것을 권장합니다. 동의항목은 카카오디벨로퍼스의 **\[카카오 로그인] > \[동의항목]** 에서 설정합니다. 설정 방법과 동의 단계의 의미는 [카카오 로그인 동의항목 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#scope-setting)을 참고하세요. 아래의 동의항목은 **카카오가 파트너사에 제공하는 정보**에 대한 설정입니다. 뒤에서 안내하는 **파트너사가 카카오에 제공하는 개인정보 제3자 제공 동의**와 구분하세요. | 항목 | 설정 기준 | 설명 | | --- | --- | --- | | 회원번호 | 자동 제공 | 사용자 정보 조회 응답의 `id`로 제공됩니다. | | 닉네임·프로필 사진 | 필수 | 게임플레이 게임 프로필 정보 연동에 사용합니다. | | 카카오 서비스 내 친구목록 | 선택 동의 | 친구 목록 조회 또는 친구 피커를 사용할 때 신청합니다. [개인정보 동의항목 추가 기능](https://developers.kakao.com/docs/ko/kakaosync/prerequisite#additional-feature-request) 신청이 필요하며, 위의 비즈니스 정보 심사와는 다른 절차입니다. | | 카카오톡 채널 추가 상태 및 내역 | 선택 | 대표 채널을 설정하고 채널 관계 확인이 필요할 때 사용합니다. | | 그 외 개인정보 | 협의 후 신청 | 제공 목적과 활용 화면을 준비해 개인정보 동의항목 추가 기능 심사를 신청합니다. | | CI·배송지 정보·카카오계정 상태 변경 내역 | 불가 | 게임플레이 입점 계약 범위에서 제공하지 않습니다. | 닉네임·프로필 사진 항목을 동의받아야 추후 게임 프로필 정보를 연동하여 사용할 수 있습니다. 연령대, 생일, 출생 연도는 게임 이용 등급 가능 대상을 판단하는 수단으로 사용할 수 없습니다. 연령 확인이 반드시 필요하면 파트너사가 별도 본인확인 절차를 구현합니다. 카카오 담당자와 협의하세요. ### 친구 목록 조회 친구 랭킹 등 친구 정보를 사용하는 기능을 제공하려면 `카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)` 동의항목의 사용 권한을 신청합니다. 사용 권한을 받은 뒤 카카오디벨로퍼스의 \*\*\[카카오 로그인] > \[동의항목]\*\*에서 동의 단계를 `선택 동의`로 설정하세요. | 항목 | 기준 | | --- | --- | | 동의항목 ID | `friends` | | 지원 동의 단계 | 선택 동의 | | 제공 정보 | 회원번호, 메시지 전송용 사용자 고유 ID, 닉네임, 프로필 썸네일, 즐겨찾기 여부 | 이 항목은 사용자가 가입할 때 동의하지 않아도 가입을 완료할 수 있습니다. 가입할 때 동의하지 않았거나 최초 게임 출시 시점에 항목을 설정하지 않았다면, 친구 기능을 처음 사용하는 시점에 `scope=friends`로 추가 동의를 요청하세요. 추가 동의를 완료한 뒤 친구 목록을 조회할 수 있으며, 사용자가 동의를 취소하면 친구 기능 없이 서비스를 계속 이용할 수 있도록 처리해야 합니다. 친구 목록과 친구 피커에는 아래 조건을 모두 만족하는 친구만 표시됩니다. | 제공 조건 | 설명 | | --- | --- | | 친구 관계 | 조회 사용자와 카카오톡 친구 관계여야 합니다. | | 파트너사 앱 가입 | 조회 사용자와 친구 모두 같은 파트너사 앱에 연결된 사용자여야 합니다. | | 쌍방 동의 | 조회 사용자와 친구 모두 `friends` 동의항목에 동의한 상태여야 합니다. | | 공개 상태 | 친구가 숨김 또는 차단 상태가 아니고, 프로필 공개 설정이 공개 상태여야 합니다. | 따라서 파트너사 앱 가입자라도 어느 한쪽이 동의하지 않았다면 친구 정보로 제공되지 않습니다. 제공되는 친구 수는 사용자의 실제 카카오톡 친구 수와 다를 수 있습니다. 파트너사는 기능에 따라 친구 목록 API와 친구 피커 중 하나를 선택할 수 있습니다. | 제공 방식 | 적합한 기능 | 특징 | | --- | --- | --- | | 친구 목록 API | 게임 결과와 연계한 친구 랭킹처럼 파트너사가 친구 목록 UI와 데이터를 직접 구성하는 기능 | 제공 조건을 만족하는 친구 목록을 API 응답으로 받습니다. | | 친구 피커 | 사용자가 특정 친구를 직접 선택하는 기능 | 파트너사 앱을 이용 중이며 친구 목록 제공에 동의한 친구만 카카오가 제공하는 피커에 표시됩니다. | 구현 방법은 [친구 목록 조회 API](/api-sdk/kakaotalk-social/friends)를 참고하세요. 동의항목과 제공 조건의 전체 정책은 [카카오 로그인 개인정보 동의항목](https://developers.kakao.com/docs/ko/kakaologin/utilize#scope-user)과 [카카오톡 친구 정보 제공 조건](https://developers.kakao.com/docs/ko/kakaotalk-social/common#policy-friend)에서 확인할 수 있습니다. ## 파트너사 약관 동의 설정 파트너사가 서비스 가입 과정에서 사용자에게 동의받아야 하는 약관 항목을 구성합니다. 카카오디벨로퍼스의 서비스 약관 기능을 활용해 \*\*\[카카오 로그인] > \[간편가입]\*\*에서 설정할 수 있습니다. 각 약관에는 제목, 약관 URL, 동의 단계, 서비스 서버에서 식별할 태그를 설정합니다. 자세한 설정 방법은 [카카오 로그인 서비스 약관 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#service-terms)을 참고하세요. ### 서비스 약관 구성 아래 네 개 약관을 모두 등록하고 약관명도 표와 동일하게 입력합니다. 서비스 이용약관, 개인정보 제3자 제공 동의, 개인정보 수집 및 이용 세 건은 `[서비스 약관 추가]`로 등록하고, 만 14세 이상 연령 동의는 같은 **\[카카오 로그인] > \[간편가입]** 화면의 `[만 14세 이상 연령 동의 추가]`로 등록합니다. | 약관명 | 동의 단계 | 설명 | | --- | --- | --- | | 서비스 이용약관 | 필수 | 파트너사 서비스 이용 조건입니다. | | 개인정보 제3자 제공 동의 | 필수 | 카카오에서 파트너사로 개인정보를 제공하기 위한 동의입니다. 카카오에서 동의문을 제공합니다. | | 개인정보 수집 및 이용 | 필수 | 서비스 가입에 필요한 개인정보의 수집·이용 동의입니다. | | 만 14세 이상 연령 동의 | 필수 | 게임플레이 가입 가능 연령 확인을 위한 약관입니다. | 등록한 약관의 사용 설정을 `ON`으로 변경한 뒤 간편가입 사용 설정도 `ON`으로 변경합니다. 간편가입을 활성화하려면 사용 중인 서비스 약관이 하나 이상 있어야 합니다. 선택적으로 수집하는 개인정보가 있다면 `개인정보 수집 및 이용` 약관을 별도로 추가합니다. 필요한 정보만 동의 항목으로 구성하고 서비스 제공에 필요하지 않은 정보는 수집하지 않습니다. `만 14세 이상 연령 동의`의 동의 단계를 필수로 설정하면 만 14세 미만 사용자는 동의할 수 없어 간편가입이 중단됩니다. ### 개인정보 제3자 제공 동의문 파트너사에서 카카오로 개인정보를 제공하기 위한 동의문은 카카오가 제공하는 페이지를 사용합니다. `id` 파라미터의 `{APP_ID}`를 파트너사 디벨로퍼스 앱 ID로 바꾸세요. ```text https://gameplay.kakao.com/html/partner-terms/index.html?id={APP_ID} ``` 이 동의문은 카카오톡 게임플레이가 사용자의 게임별 이용 데이터를 제공받아 분석과 서비스 제공에 이용하기 위한 약관입니다. 파트너사는 별도 동의문을 제작하지 않고 위 URL을 서비스 약관의 약관 URL로 등록해야 합니다. 동의문은 아래 항목으로 구성됩니다. `제공하는 자`에는 실제 파트너사명을 표시하고 나머지 항목은 제공 페이지의 문구를 사용합니다. | 구성 항목 | 표시 내용 | | --- | --- | | 제공하는 자 | 해당 파트너사명 | | 제공받는 자 | 카카오 | | 필수 제공 항목 | 참여 내역, 점수 등 게임 서비스 이용 기록 | | 제공 목적 | 카카오톡 게임플레이 내 게임 진행 현황·랭킹 등 서비스 제공, 맞춤형 콘텐츠 제공과 서비스 기능 개선 | | 보유·이용 기간 | 동의 철회 또는 서비스 탈퇴 시까지 보관 후 파기. 관련 법령에 따른 보관 의무가 있으면 해당 기간까지 보관 후 파기 | 아래는 사용자가 확인하는 개인정보 제3자 제공 동의문 예시입니다. 실제 화면의 제공 항목과 문구는 계약 및 운영 정책에 따라 달라질 수 있습니다. ## 추가 개인정보 동의항목 기본적으로 설정할 수 없는 개인정보 또는 `필수 동의` 단계를 사용하려면 개인정보 동의항목 추가 기능을 신청합니다. 각 항목의 제공 목적, 서비스 내 활용 화면, 개인정보 처리방침을 준비하고 승인된 범위만 설정하세요. 테스트 앱에서는 운영 앱 심사 전에 일부 동의항목을 확인할 수 있습니다. 테스트 앱의 앱 키와 설정은 운영 앱에 자동 반영되지 않으므로 운영 적용 전에 앱 키, Redirect URI, 동의항목, 서비스 약관을 다시 확인해야 합니다. ## 운영 적용 전 확인 * \[ ] 운영 앱에서 카카오 로그인과 간편가입 사용 설정이 `ON`인지 확인합니다. * \[ ] 앱 이름·회사명·대표 도메인이 입점 정보와 일치하는지 확인합니다. * \[ ] 비즈 앱과 비즈니스 채널 연결 및 필요한 심사가 완료됐는지 확인합니다. * \[ ] 운영 Redirect URI와 [인가 코드 요청](https://developers.kakao.com/docs/ko/kakaologin/rest-api#request-code)에 전달하는 `redirect_uri` 값이 정확히 일치하는지 확인합니다. * \[ ] 가입에 필요한 사용자 정보가 없는 경우의 대체 입력 또는 가입 중단 정책을 확인합니다. * \[ ] 선택 동의 거부 사용자가 서비스 정책에 맞게 가입 또는 로그인되는지 확인합니다. * \[ ] 테스트 앱에서 개발했다면 운영 앱에 설정과 앱 키를 다시 반영했는지 확인합니다. ## 카카오에 전달할 앱 정보 설정을 완료한 뒤 아래 정보를 카카오 담당자에게 전달합니다. | 항목 | 설명 | | --- | --- | | 앱 ID | 카카오디벨로퍼스에서 발급된 앱 ID입니다. | | 앱 이름 | 카카오싱크 동의 화면에 표시되는 앱 이름입니다. | | 회사명 | 사업자 등록증과 비즈 앱에 등록한 회사명입니다. | ## 참고 문서 * [카카오싱크 API](/api-sdk/kakaosync/rest-api): 게임웹뷰 자동 진입과 카카오싱크 가입·로그인 구현 스펙 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 사용자가 앱 연결을 해제했을 때의 콜백 처리 * [심사 체크리스트](/docs/checklist/review-checklist): 인증·동의 자체 점검 항목 * [카카오싱크 설정하기](https://developers.kakao.com/docs/ko/kakaosync/prerequisite): 카카오 공식 사전 준비 문서 * [카카오싱크 개발 가이드](https://developers.kakao.com/docs/ko/kakaosync/dev-guide): 카카오 공식 연동 개발 문서 --- --- url: /docs/webview/overview.md description: 카카오톡 게임웹뷰의 역할과 파트너사 개발 순서 안내 --- # 게임웹뷰 게임웹뷰는 카카오톡 안에서 게임플레이 게임을 실행하는 전용 웹뷰 환경입니다. 파트너사는 카카오가 게임 URL을 불러온 이후의 게임 화면과 동작을 구현하고, 게임웹뷰 SDK를 연동해 카카오톡 네이티브 기능을 사용할 수 있습니다. 이 페이지에서 전체 개발 순서를 확인한 뒤 필요한 세부 가이드로 이동하세요. ## 카카오와 파트너사의 역할 | 구분 | 담당 영역 | | --- | --- | | 카카오 | 게임 진입 조건 확인, 카카오싱크 동의 분기, 공통 스플래시와 게임웹뷰 제공 | | 파트너사 | 게임 화면과 로딩·오류 처리, 게임웹뷰 SDK 연동, 디바이스별 UI 대응과 테스트 | 파트너사의 게임 URL이 로드되기 전 흐름은 카카오가 제공합니다. 진입 조건과 화면 분기는 [게임 실행 흐름](/docs/webview/launch-flow)에서 확인하세요. ## 개발 전 준비 ### 게임 URL과 도메인 등록 파트너사는 게임플레이 파트너센터의 게임 정보에 게임 URL을 입력합니다. 이 작업과 별도로 샌드박스·운영·테스트 환경에서 사용할 게임웹뷰 실행 허용 도메인(화이트리스트)을 카카오 담당자에게 전달해 등록을 요청합니다. 화이트리스트에 등록된 도메인만 카카오톡 안에서 게임웹뷰로 실행할 수 있습니다. 출시된 게임의 운영 URL은 테스트에 사용할 수 없으므로 별도의 테스트 URL도 함께 준비합니다. 카카오 담당자가 지정한 뒤에는 파트너사별 오픈채팅방에서 도메인 등록 상태와 테스트 일정을 확인하세요. 도메인 등록 후 카카오톡에서 확인하는 방법과 등록 없이 테스트앱을 사용하는 방법은 [게임웹뷰 테스트 방법](/docs/webview/test-guide)을 참고하세요. ### 파트너사가 준비할 항목 * 샌드박스·운영 환경의 게임 URL과 도메인 목록 * 출시 후에도 사용할 별도의 테스트 URL * iOS·Android, 폰·태블릿에서 확인할 테스트 시나리오 * 게임 화면 방향, Safe Area, 상태바 등 게임웹뷰 UI 기준 ## 개발 순서 1. **게임 진입 흐름을 확인합니다.** 카카오싱크 동의부터 게임 URL 로드까지의 조건과 분기를 확인합니다. 2. **게임 화면을 제작합니다.** 화면 크기·내비게이션·로딩·팝업 등 게임웹뷰 환경에 맞는 디자인 기준을 적용합니다. 3. **게임웹뷰 SDK를 연동합니다.** 웹뷰 닫기, 화면 방향, Safe Area, 상태바 등 게임에 필요한 네이티브 기능을 연결합니다. 4. **디바이스별 동작을 확인합니다.** iOS·Android와 폰·태블릿 환경을 구분하고 필요한 UI와 기능을 적용합니다. 5. **카카오톡과 테스트앱에서 검증합니다.** 실제 진입 조건과 SDK 동작을 확인한 뒤 심사를 준비합니다. ## 주제별 가이드 | 확인할 내용 | 가이드 | | --- | --- | | 게임 진입 조건과 화면 분기 | [게임 실행 흐름](/docs/webview/launch-flow) | | 게임 URL 등록과 테스트 | [게임웹뷰 테스트 방법](/docs/webview/test-guide) | | 화면·콘텐츠 제작 기준 | [게임 공통 제작 가이드](/docs/design/common-guide) | | 내비게이션·로딩·팝업 UI | [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide) | | 게임웹뷰 기능과 메서드 | [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay) | | iOS·Android·태블릿 구분 | [디바이스 구분 방법](/docs/webview/device-detection) | | 상태바와 Safe Area 처리 | [상태바 오버레이 설정 방법](/docs/webview/status-bar-overlay) | | 카카오톡·테스트앱 검증 | [게임웹뷰 테스트 방법](/docs/webview/test-guide) | ## 참고 문서 * [입점 안내](/docs/checklist/start-guide): 제휴부터 출시까지의 전체 과정 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 디벨로퍼스 앱과 동의 항목 설정 * [심사 가이드](/docs/checklist/review-guide): 출시 심사 과정과 준비 사항 --- --- url: /docs/webview/test-guide.md description: 화이트리스트 도메인이 카카오톡 게임웹뷰로 정상 실행되는지 확인하는 방법 --- # 게임웹뷰 테스트 방법 게임웹뷰 테스트는 카카오톡 또는 `Gameplay 테스트앱`에서 진행할 수 있습니다. 카카오톡에서는 실제 실행 조건에 가까운 진입을 확인하고, `Gameplay 테스트앱`에서는 정식 카카오톡 빌드와 별개로 게임웹뷰 기능과 디버깅을 사전에 확인합니다. 웹뷰 자체의 개발 스펙은 [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay)를 참고하세요. ## 카카오톡에서 테스트하기 화이트리스트가 적용된 도메인을 카카오톡 안에서 실행해 **게임웹뷰로 정상 진입**하는지 확인합니다. ### 사전 준비 1. 카카오 담당자에게 화이트리스트 적용이 필요한 도메인 목록을 전달합니다. 리얼·샌드박스 등 복수 도메인을 동시에 등록할 수 있습니다. 2. 카카오톡을 **v26.5.0 이상**으로 업데이트합니다. ### 실행 방법 1. 카카오톡을 실행합니다. 2. 테스트하려는 게임 링크를 아래 테스트 공용 링크 뒤에 붙여 채팅방에 전송합니다. ```text https://gameplay.kakao.com/entry/test/games?url={게임URL} ``` 3. 링크를 선택해 게임웹뷰가 실행되는지 확인합니다. 이미 출시된 게임은 라이브 URL로 테스트할 수 없습니다. 별도의 테스트용 URL로 화이트리스트를 등록해 테스트합니다. ### 정상 동작 기준 도메인을 선택했을 때 **카카오톡 인앱브라우저가 아니라 게임웹뷰로 실행**되어야 합니다. 일반 웹 링크처럼 인앱브라우저 상단 바가 노출되면 화이트리스트가 정상 적용되지 않은 상태입니다. <예시 - 인앱브라우저 화면> ### 확인 체크리스트 * \[ ] 카카오톡 버전이 v26.5.0 이상인지 확인 * \[ ] 게임 URL이 카카오에 요청한 화이트리스트 도메인과 일치하는지 확인 * \[ ] 도메인 선택 시 게임웹뷰(주소창 없는 형태)로 실행되는지 확인 ### 테스트 가능 스펙 게임웹뷰의 전체 스펙은 카카오톡 `v26.3.0` 이상에서 확인할 수 있습니다. 아래는 특정 버전 이상에서만 테스트 가능한 기능입니다. | 항목 | 지원 버전 | | --- | --- | | Wi-Fi 연결 여부 조회 | v26.5.0 이상 (2026-06-15 이후 배포) | | Safe Area 초기값 조회 | v26.5.0 이상 (2026-06-15 이후 배포) | | 가속도 센서 | v26.5.0 이상 (2026-06-15 이후 배포) | | 상태바 영역까지 뷰포트 확장 | v26.5.0 이상 (2026-06-15 이후 배포) | 각 API의 상세 사용법은 [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay)를 참고하세요. ## 테스트앱에서 테스트하기 **Gameplay 테스트앱**은 카카오톡 정식 빌드와 별개로 게임웹뷰 환경에서 게임 실행과 디버깅을 사전에 확인하기 위한 앱입니다. 화이트리스트 등록 없이 테스트 URL을 입력해 게임웹뷰를 열 수 있습니다. ### 사용 목적 * 카카오톡 정식 빌드 배포 전 게임웹뷰 동작 확인 * 게임 URL 로딩 및 게임 실행 확인 * `window.kakaotalkGamePlay` 객체 기반 기능 확인 * 인스펙터를 이용한 웹뷰 디버깅 ### 지원 범위 Gameplay 테스트앱은 실제 카카오톡의 웹뷰 환경과 100% 동일하지 않습니다. 카카오톡 내부 상속 구조 전체를 포함하지 않으며, 인증 기반 Server to Server 연동 테스트는 지원하지 않습니다. * 로그인·인증 없는 테스트앱 제공 * URL 입력 후 게임웹뷰 실행 * `window.kakaotalkGamePlay` 객체와 주요 메서드 테스트 * 인스펙터 디버깅 * 단일 게임웹뷰 기준 테스트 ### 사용 방법 1. Gameplay 테스트앱을 설치합니다. 2. 앱을 실행합니다. 3. 테스트할 게임 URL을 입력합니다. 4. 게임웹뷰가 열리면 게임 실행과 필요한 `kakaotalkGamePlay` 기능을 확인합니다. 5. 필요한 경우 인스펙터로 웹뷰를 디버깅합니다. ### 설치 방법 | OS | 설치 방법 | | --- | --- | | Android | APK 설치 | | iOS | 카카오 담당자에게 TestFlight 권한을 별도로 요청 | ## 참고 문서 * [게임웹뷰](/docs/webview/overview): 게임웹뷰의 역할과 전체 개발 순서 * [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay): `kakaotalkGamePlay` API 스펙 * [게임 실행 흐름](/docs/webview/launch-flow): 웹뷰 진입 조건과 화면 전환 구조 * [심사 체크리스트](/docs/checklist/review-checklist): 심사 전 자체 점검 항목 --- --- url: /docs/webview/device-detection.md description: 게임웹뷰에서 iOS · Android · 태블릿을 구분하는 방법과 판정 규칙 --- # 디바이스 구분 방법 게임웹뷰는 iOS · Android 두 플랫폼과 폰 · 태블릿 두 폼팩터에서 동작합니다. 플랫폼별 처리나 태블릿 레이아웃이 필요할 때 아래 코드로 기기를 구분할 수 있습니다. * **의존성이 없습니다.** 파일 하나를 복사해 그대로 사용하세요. * 구분 기준은 **User-Agent 문자열**이며, iPadOS 예외 한 건만 `navigator.maxTouchPoints` 를 함께 사용합니다. * 카카오톡 인앱 웹뷰 여부(`isKakaoTalk`)도 함께 구분합니다. ## 구분이 필요한 대표적인 경우 | 상황 | 이유 | | --- | --- | | 웹뷰 접기(`keepBrowser`) UI 노출 | 접기는 **카카오톡 안의 iPhone 에서만** 제공합니다. 태블릿에서는 웹뷰가 접히지 않고 그대로 종료됩니다. [게임웹뷰 SDK: keepBrowser](/api-sdk/sdk/kakaotalk-gameplay#keepbrowser) 참고 | | 태블릿 레이아웃 | 큰 화면에 맞춘 배치가 필요한 경우. [게임 공통 제작 가이드](/docs/design/common-guide#태블릿-대응) 참고 | | 플랫폼별 처리 | Android 하드웨어 백 버튼 처리 등 | ## 코드 ```ts export type DeviceInfo = { /** 'unknown' 은 iOS·Android 가 아닌 환경 (데스크톱 브라우저 등). */ platform: 'ios' | 'android' | 'unknown'; isIOS: boolean; isAndroid: boolean; /** iPad 및 Android 태블릿. 폴더블 폰의 펼침 상태는 태블릿이 아닙니다. */ isTablet: boolean; /** 카카오톡 인앱 웹뷰 여부. 게임웹뷰를 포함합니다. */ isKakaoTalk: boolean; }; const UNKNOWN_DEVICE: DeviceInfo = { platform: 'unknown', isIOS: false, isAndroid: false, isTablet: false, isKakaoTalk: false, }; /** * 터치 스크린 보유 여부. * * iPadOS 13+ 는 Safari '데스크톱용 사이트' 모드에서 User-Agent 를 `Macintosh` 로 보고합니다. * 이 경우 User-Agent 만으로는 데스크톱 macOS 와 구분되지 않으므로 터치 지원 여부로 구분합니다. * (데스크톱 macOS 는 두 값 모두 거짓, iPadOS 는 참) */ function hasTouchScreen(win: Window): boolean { const maxTouchPoints = win.navigator?.maxTouchPoints ?? 0; if (maxTouchPoints > 1) { return true; } return win.document !== undefined && 'ontouchend' in win.document; } function readUserAgent(win: Window): string { return win.navigator?.userAgent ?? ''; } export function getDeviceInfo(win: Window = window): DeviceInfo { const userAgent = readUserAgent(win); if (!userAgent) { return UNKNOWN_DEVICE; } // 카카오톡 인앱 웹뷰는 iPad 토큰을 유지하므로 이 분기를 타지 않습니다. // 카카오톡 외부(일반 Safari)에서 페이지가 열리는 경우를 위한 안전망입니다. const isDesktopModeIPad = /Macintosh/i.test(userAgent) && hasTouchScreen(win); const isIOS = /iPhone|iPad|iPod/i.test(userAgent) || isDesktopModeIPad; // 레거시 Windows Phone User-Agent 가 'Android 4.0' 을 포함해 오탐됩니다. const isAndroid = /Android/i.test(userAgent) && !/Windows Phone/i.test(userAgent); // Android 태블릿은 User-Agent 에서 'Mobile' 토큰이 빠집니다. // iOS 는 iPad 토큰으로 구분합니다 — iPad 에도 'Mobile' 토큰이 있어 위 규칙을 쓸 수 없습니다. const isTablet = /^(?=.*android)(?!.*mobile).*/i.test(userAgent) || /iPad/i.test(userAgent) || isDesktopModeIPad; // 카카오톡 인앱 웹뷰는 iOS·Android 모두 User-Agent 에 KAKAOTALK 토큰을 넣습니다. const isKakaoTalk = /KAKAOTALK/i.test(userAgent); const platform = isIOS ? 'ios' : isAndroid ? 'android' : 'unknown'; return {platform, isIOS, isAndroid, isTablet, isKakaoTalk}; } ``` ## 사용 방법 ```ts declare function applyTabletLayout(): void; declare function registerAndroidBackHandler(): void; declare function showCollapseButton(): void; const {isIOS, isAndroid, isTablet, isKakaoTalk} = getDeviceInfo(); if (isTablet) { applyTabletLayout(); } if (isAndroid) { registerAndroidBackHandler(); } // 접기는 카카오톡 안의 iPhone 에서만 제공합니다. Android 와 태블릿은 대상이 아닙니다. if (isKakaoTalk && isIOS && !isTablet) { showCollapseButton(); } ``` User-Agent 는 페이지 수명 동안 바뀌지 않습니다. 모듈 로드 시 한 번 호출해 결과를 재사용해도 됩니다. `platform` 값은 `isIOS` · `isAndroid` 와 항상 일치합니다. 편의를 위한 중복이므로 어느 쪽을 써도 됩니다. ## 판정 규칙 | 항목 | 규칙 | 근거 | | --- | --- | --- | | `isIOS` | User-Agent 에 `iPhone` · `iPad` · `iPod` 중 하나. 또는 `Macintosh` + 터치 보유 | 카카오톡 인앱 웹뷰는 기기 토큰을 유지합니다. `Macintosh` 조건은 카카오톡 외부 iPadOS 대응용입니다 | | `isAndroid` | User-Agent 에 `Android`, 단 `Windows Phone` 제외 | 레거시 Windows Phone User-Agent 가 `Android 4.0` 을 포함해 오탐됩니다 | | `isTablet` | 셋 중 하나: ① `android` 가 있고 `mobile` 이 **없음** ② User-Agent 에 `iPad` ③ `Macintosh` + 터치 보유 | ① Android 는 폰에만 `Mobile` 토큰을 넣어 태블릿에서는 생략됩니다. ② iPad **에도 `Mobile` 토큰이 있어** ①번 규칙을 iOS 에 쓸 수 없습니다. ③ User-Agent 에 `iPad` 토큰이 없는 유일한 iPad 케이스입니다 | | `isKakaoTalk` | User-Agent 에 `KAKAOTALK` | 카카오톡 인앱 웹뷰는 iOS · Android 모두 이 토큰을 넣습니다. 게임웹뷰도 인앱 웹뷰이므로 `true` 입니다 | ### User-Agent 예시 카카오톡 26.7.0 기준입니다. 끝부분에는 카카오톡 버전과 웹뷰 구분값이 붙습니다. ```text iPhone Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148 KAKAOTALK/26.7.0 ... iPad Mozilla/5.0 (iPad; CPU OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 KAKAOTALK/26.7.0 ... Android Mozilla/5.0 (Linux; Android 14; SM-S928N; wv) AppleWebKit/537.36 Mobile Safari/537.36; ... KAKAOTALK 2426700 ``` iPad 예시의 `Mobile/15E148` 을 주의해서 보세요. **iPad 에도 `Mobile` 토큰이 있습니다.** 이 때문에 Android 의 `Mobile` 토큰 규칙을 iOS 에 적용할 수 없습니다. ## 환경별 판정 결과 구현을 검증할 때 참고하세요. `O` = true, `-` = false 입니다. | 환경 | `isIOS` | `isAndroid` | `isTablet` | `isKakaoTalk` | | --- | --- | --- | --- | --- | | iPhone: 게임웹뷰 | O | - | - | O | | iPad: 게임웹뷰 | O | - | O | O | | Android 폰: 게임웹뷰 | - | O | - | O | | Android 태블릿: 게임웹뷰 | - | O | O | O | | iPhone: Safari | O | - | - | - | | iPad: Safari | O | - | O | - | | iPad: Safari 데스크톱용 사이트 모드 | O | - | O | - | | iPod touch: Safari | O | - | - | - | | Android 폰: Chrome | - | O | - | - | | Android 태블릿: Chrome | - | O | O | - | | 폴더블 폰 펼침: Chrome | - | O | - | - | | 데스크톱: macOS Safari · Chrome | - | - | - | - | | 데스크톱: Windows Chrome (터치 포함) | - | - | - | - | 데스크톱 환경에서는 `platform` 이 `'unknown'` 이 됩니다. User-Agent 를 읽을 수 없는 경우에도 예외를 던지지 않고 `'unknown'` 을 반환합니다. 주목할 두 가지가 있습니다. * **iPad 데스크톱용 사이트 모드와 데스크톱 macOS Safari 는 User-Agent 문자열이 완전히 같습니다.** `maxTouchPoints` 없이는 구분할 수 없습니다. * **폴더블 폰 펼침 상태는 화면이 태블릿만큼 넓지만 태블릿이 아닙니다.** 화면 크기 기반 판정이 실패하는 대표적인 경우입니다. ## 사용하면 안 되는 방식 아래 방식은 위 표의 환경 중 일부에서 오판을 일으킵니다. | 방식 | 문제 | | --- | --- | | `screen.width` · `window.innerWidth` 로 태블릿 판정 | **폴더블 폰 펼침 상태(짧은 변 약 674px)를 태블릿으로 오판합니다.** iPad 에서 카카오톡이 split view 로 표시되면 `innerWidth` 가 기기 크기와 무관해지는 문제도 있습니다 | | iOS 에 "`Mobile` 토큰이 없으면 태블릿" 규칙 적용 | iPad 에도 `Mobile` 토큰이 있어 **iPad 를 폰으로 오판합니다.** Android 전용 규칙입니다 | | `navigator.platform` 사용 | Deprecated 된 API 이며, iPadOS 는 `MacIntel` 을 반환해 데스크톱과 구분되지 않습니다 | | `navigator.userAgentData` 단독 사용 | Chromium 계열 전용입니다. **iOS 에는 존재하지 않아** iPhone · iPad 판정이 전부 실패합니다 | | 카카오톡 버전으로 기능 지원 여부 분기 | 패치 · 백포트 빌드에서 버전 비교가 어긋납니다. 기능 지원 여부는 해당 메서드의 실제 존재를 확인하는 방식으로 판단하세요 | 기기 구분과 레이아웃 판단은 분리하세요. **기기 종류는 User-Agent, 레이아웃은 viewport 또는 media query** 를 사용합니다. iPad split view 처럼 기기 크기와 표시 영역이 일치하지 않는 상황이 있습니다. ## 적용 범위 이 코드는 **기기 종류(플랫폼 · 폼팩터)와 카카오톡 인앱 웹뷰 여부**를 구분합니다. `isKakaoTalk` 은 카카오톡 안에서 열렸는지만 알려줍니다. 게임웹뷰인지 일반 인앱브라우저인지까지 구분하지는 않습니다. 게임은 언제나 게임웹뷰에서 실행되므로 이 구분이 필요한 경우는 드뭅니다. 동작이 예상과 다른 기기를 발견하면 해당 기기의 User-Agent 문자열과 함께 [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)으로 알려주세요. 판정 규칙에 반영하겠습니다. ## 참고 문서 * [게임웹뷰](/docs/webview/overview): 게임웹뷰의 역할과 전체 개발 순서 * [게임웹뷰 SDK: keepBrowser](/api-sdk/sdk/kakaotalk-gameplay#keepbrowser): 접기를 iPhone 에서만 노출해야 하는 이유 * [게임 공통 제작 가이드](/docs/design/common-guide#태블릿-대응): 태블릿 레이아웃 기준 * [심사 체크리스트](/docs/checklist/review-checklist): 단말기 확인 항목 --- --- url: /docs/webview/status-bar-overlay.md description: 게임웹뷰 오버레이 상태가 페이지 이동 후에도 유지되는 문제와 대응 방법 --- # 상태바 오버레이 설정 방법 `setStatusBarOverlay` 로 게임웹뷰를 상태바 영역까지 확장한 뒤 게임이 외부 URL 로 이동하면, 이동한 페이지도 상태바 밑으로 밀려 상단이 잘립니다. 카카오싱크 약관 동의창처럼 파트너사가 화면을 수정할 수 없는 페이지에서 특히 문제가 됩니다. 이 페이지는 파트너사 게임 코드만으로 이 문제를 막는 방법을 정리합니다. ## 오버레이 상태 상태바 오버레이는 웹 페이지가 아니라 **네이티브 웹뷰 컨테이너가 소유하는 레이아웃 속성**입니다. | 대상 | 소유자 | 페이지 이동 시 | | --- | --- | --- | | 게임 화면 DOM · CSS | 웹 페이지 | 새 페이지로 교체됩니다 | | 상태바 오버레이 | 네이티브 웹뷰 | **그대로 유지됩니다** | 두 생명주기가 어긋나는 것이 문제의 원인입니다. 게임이 한 번 오버레이를 켜면 이후 웹뷰에 로드되는 모든 페이지가 확장된 레이아웃을 물려받습니다. 새로 로드된 페이지는 자신이 오버레이 상태인지 알 수 없으므로 스스로 안전영역을 보정할 수도 없습니다. ## 문제가 되는 흐름 사용자가 게임에 처음 접근해 카카오싱크 약관에 동의하는 흐름입니다. | 단계 | 동작 | 오버레이 | 결과 | | --- | --- | --- | --- | | 1 | 카카오가 진입 조건을 확인한 뒤 게임 URL 로드 | 꺼짐 | 정상 | | 2 | 게임이 `setStatusBarOverlay(true)` 호출 | **켜짐** | 게임 화면이 상태바까지 확장 | | 3 | 게임이 `prompt` 없는 kauth 인가 코드 요청 | 켜짐 (유지) | — | | 4 | 약관 미동의 사용자 → 카카오싱크 동의창으로 리디렉션 | 켜짐 (유지) | — | | 5 | 동의창 렌더 | 켜짐 (유지) | **상단이 상태바에 가려져 잘림** | | 6 | 동의 완료 후 게임으로 복귀 | 켜짐 | 정상 | 5단계가 문제입니다. 동의창은 카카오싱크가 제공하는 화면이라 파트너사가 안전영역 대응을 넣을 수 없습니다. 설정은 [카카오싱크 설정](/docs/authentication/kakao-login-sync), 인증 흐름은 [카카오싱크 API](/api-sdk/kakaosync/rest-api)를 참고하세요. ::: warning 주의사항 게임 플레이 도중의 추가 권한 동의는 인앱브라우저 창을 따로 띄워 게임웹뷰를 이탈하지 않는 방식으로 처리할 수 있습니다([게임 중 추가 동의](/api-sdk/kakaosync/rest-api#게임-중-추가-동의)). 하지만 **최초 가입 시의 약관 동의는 게임웹뷰 자체 리디렉션이 유일한 경로**이므로 이 방식을 쓸 수 없습니다. ::: 같은 문제는 약관 동의에만 국한되지 않습니다. 결제 페이지, 고객센터, 외부 이벤트 페이지 등 게임웹뷰가 외부 URL 로 이동하는 모든 흐름에서 동일하게 재발합니다. ## 기본 규칙 > 오버레이는 **게임이 화면을 온전히 소유하는 구간**에서만 켭니다. 인증, 약관 동의, 외부 페이지처럼 게임이 화면을 소유하지 않는 구간에서는 오버레이를 꺼 둡니다. 적용 지점은 두 곳입니다. | 구간 | 오버레이 | 대응 | | --- | --- | --- | | 진입: 인증 · 약관 동의 왕복 | 끈 상태로 둡니다 | [복귀 후 활성화](#복귀-후-활성화) | | 플레이 중: 외부 페이지로 이탈 | 이탈 직전에 끄고 복귀 시 켭니다 | [이탈 직전 롤백](#이탈-직전-롤백) | 오버레이를 토글하면 안전영역 인셋이 바뀝니다. 새 값은 `SAFE_AREA` UPDATE 이벤트로 자동 전송되므로, 토글 직후 안전영역을 다시 조회하는 대신 이 이벤트를 구독해 레이아웃에 반영하세요. 지원 버전은 `setStatusBarOverlay` 가 카카오톡 26.5.0 이상, `getStatusBarOverlay` 가 26.6.0 이상입니다. 그 미만에서는 호출이 실패하므로 게임 진행이 막히지 않도록 처리해야 합니다. 게임웹뷰 SDK 는 이때 에러 문자열을 반환합니다. ## 복귀 후 활성화 기본 대응입니다. 인증·약관 동의 왕복이 있는 모든 게임에 적용합니다. ### 적용 지점 게임 진입 시점에는 오버레이를 켜지 않습니다. 인증과 약관 동의 왕복이 모두 끝나고 게임 본 화면에 완전히 진입한 뒤에 켭니다. 켜는 지점이 한 곳뿐이라 그 앞에서 리디렉션이 몇 번 일어나든 안전합니다. 대신 인증·로딩 구간이 상태바까지 확장되지 않고, 게임 본 화면에 진입할 때 레이아웃이 한 번 바뀝니다. ### 구현 인증과 약관 동의 왕복이 모두 끝난 뒤에 켭니다. ```ts declare function authenticate(): Promise; async function enterGame(): Promise { await authenticate(); await window.kakaotalkGamePlay.setStatusBarOverlay({enable: true}); } ``` ## 이탈 직전 롤백 보완 대응입니다. 플레이 중에도 외부 페이지로 나가는 게임에만 추가로 적용합니다. ### 적용 지점 게임 플레이 도중 외부 페이지로 이동해야 할 때 사용합니다. 이동 직전에 오버레이를 끄고, 게임으로 돌아온 뒤 다시 켭니다. 진입 구간은 [복귀 후 활성화](#복귀-후-활성화) 로 처리하고, 이 방법은 그 위에 얹습니다. ### 구현 이동 직전에 오버레이를 끕니다. **Promise 가 resolve 된 뒤에 이동해야 합니다.** `await` 없이 곧바로 `location.href` 를 바꾸면 브리지 호출이 유실될 수 있습니다. ```ts async function leaveGame(url: string): Promise { await window.kakaotalkGamePlay.setStatusBarOverlay({enable: false}); window.location.href = url; } ``` 게임 밖으로 나가는 경로는 이 헬퍼 하나를 거치게 만드세요. 이탈 지점마다 개별로 처리하면 한 곳만 빠뜨려도 그 경로에서 문제가 다시 나타납니다. 특히 게임 코드가 직접 트리거하지 않는 이동: 사용자가 탭하는 `` 링크, 서드파티 모듈이 수행하는 이동: 은 가로채기 어려우므로 이탈 경로를 설계 단계에서 함께 정리해야 합니다. ### 복귀 시 재활성화 돌아온 게임 페이지는 새로 로드되므로 현재 오버레이 상태를 알지 못합니다. 게임이 직접 다시 켜야 합니다. 게임웹뷰 SDK 는 현재 상태를 조회할 수 있습니다. ```ts const {enabled} = await window.kakaotalkGamePlay.getStatusBarOverlay(); if (!enabled) { await window.kakaotalkGamePlay.setStatusBarOverlay({enable: true}); } ``` ## 적용 기준 | 게임의 이탈 패턴 | 적용할 것 | | --- | --- | | 진입 구간(인증 · 약관 동의)에서만 이탈 | 복귀 후 활성화 | | 플레이 중에도 외부 페이지로 이탈 | 복귀 후 활성화 + 이탈 직전 롤백 | 이탈 직전 롤백만 단독으로 쓰는 구성은 권장하지 않습니다. 이탈 직전에 오버레이를 껐다면 복귀 후 다시 켜야 하고, 그 재활성화 로직은 결국 복귀 후 활성화와 같기 때문입니다. 켜는 지점을 한 곳으로 모으는 편이 누락 위험이 적습니다. ## 확인 사항 * \[ ] 인증 · 약관 동의 왕복 중 오버레이가 꺼져 있는지 확인 * \[ ] 게임 밖으로 나가는 모든 경로가 한 헬퍼를 거치는지 확인 (플레이 중 이탈이 있는 경우) * \[ ] 오버레이 토글 후 `SAFE_AREA` UPDATE 이벤트로 레이아웃을 다시 계산하는지 확인 * \[ ] 카카오톡 26.5.0 미만에서 호출이 실패해도 게임이 정상 진행되는지 확인 * \[ ] 약관 미동의 신규 사용자로 최초 진입을 재현해 동의창 상단이 잘리지 않는지 확인 ## 참고 문서 * [게임웹뷰](/docs/webview/overview): 게임웹뷰의 역할과 전체 개발 순서 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·동의항목·서비스 약관 설정 * [카카오싱크 API](/api-sdk/kakaosync/rest-api): 인증과 약관 동의 왕복 흐름 * [게임 실행 흐름](/docs/webview/launch-flow): 게임 URL 로드 이전의 카카오 구간 * [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide#내비게이션): 투명 내비게이션과 상태바 처리 기준 * [게임웹뷰 SDK: setStatusBarOverlay](/api-sdk/sdk/kakaotalk-gameplay#setstatusbaroverlay-options): 네이티브 브리지 스펙 --- --- url: /docs/design/common-guide.md description: 게임플레이 디자인에 공통으로 적용하는 해상도·타이포그래피·컬러·태블릿 대응 기준 --- # 게임 공통 제작 가이드 게임플레이 화면을 제작할 때 공통으로 적용하는 해상도·타이포그래피·컬러 기준을 안내합니다. 태블릿과 폴더블 기기에서도 안정적으로 노출되도록 반응형 레이아웃 기준을 함께 확인하세요. :::: warning 주의사항 SDK 적용 전 게임은 기존 디자인 가이드 기준으로 제작해야 합니다. 자세한 수치와 예시는 피그마 파일을 참고해 주세요. [게임플레이\_디자인가이드\_웹뷰 컴포넌트.fig](https://drive.google.com/drive/folders/1O2aKBC3_jWCLoHevwG45Nadrpu17o4nw) :::: ## 해상도 * 작업 해상도는 `393 × 852` 기준입니다. * 심사 기준 해상도는 최소 `320 × 800`, 최대 `720 × 800`입니다. * 수치는 `1x` 기준으로 표기합니다. * 모바일 화면은 단말별 `100%` 비율 대응을 전제로 플렉서블하게 제작합니다. * 모바일 화면은 상태바를 확장한 풀스크린뷰로 제작합니다. * 태블릿 기종 대응은 별도 태블릿 프레임을 함께 참고합니다. ## 타이포그래피 ### 폰트 `Pretendard` 웹폰트 사용을 권장합니다. 필요 시 `NotoSans` 또는 시스템 웹폰트를 사용할 수 있습니다. ```css font-family: system-ui, -apple-system, 'Helvetica Neue', 'Apple SD Gothic Neo', 'Segoe UI', Roboto, Arial, 'NotoSans', 'Open Sans', 'Malgun Gothic', '맑은 고딕', sans-serif; ``` ### 글자 크기 글자 크기와 위치값의 소수점 사용은 지양합니다. | 역할 | 기준 | 사이즈 | Line height | | --- | --- | --- | --- | | Title 1 | 주요 화면 타이틀 | 19 | Auto | | Body 1 | 본문 또는 강조 본문 | 17 | Auto | | Body 2 | 일반 본문 | 16 | Auto | | Body 3 | 보조 본문 | 15 | Auto | | Caption 1 | 보조 정보 | 14 | Auto | | Caption 2 | 작은 보조 정보 | 13 | Auto | ## 컬러 서비스 내 액션 완결성을 가진 과업 및 주요 액션에 사용하는 컬러입니다. | 구분 | 이름 | 값 | 용도 | | --- | --- | --- | --- | | Brand | KakaoTalk Yellow | `#FEE502` | 카카오 브랜드 컬러 | | Base | White | `#FFFFFF` | 기본 배경, 텍스트 등 | | Text | Primary | `#191919` | 본문, 버튼 텍스트 | | Text | Secondary | `#595959` | 서브 텍스트 | | Overlay | Gray Scale 40% | `#000000 40%` | 스피너 아이콘 배경 | | Overlay | Gray Scale 6% | `#000000 6%` | 버튼 | | Overlay | Gray 67% | `#2E2E2E 67%` | 아이콘 배경 | | Overlay | Dark 67% | `#1B1C25 67%` | 토스트 팝업 배경 | ## 태블릿 대응 태블릿 디바이스에 대응할 수 있도록 제작합니다. 코드에서 태블릿 여부를 구분해야 한다면 [디바이스 구분 방법](/docs/webview/device-detection)을 참고하세요. **화면 크기로 태블릿을 판정하면 폴더블 폰 펼침 상태를 태블릿으로 잘못 판단합니다.** * 가로 모드는 높이에 맞춰 제작합니다. * 세로 모드도 높이에 맞춰 제작합니다. * 모바일 사이즈 그대로 작게 나오는 뷰는 지양합니다. * 게임 일부가 보이지 않는 뷰는 지양합니다. | 게임 유형 | 대응 기준 | | --- | --- | | 플렉서블 게임 | 디바이스 너비에 맞춰 화면을 채웁니다 | | 모바일 전용 게임 | 디바이스 높이에 맞추고 좌우 여백(레터박스)으로 노출합니다 | ### 상태바 태블릿 디바이스에서는 상태바 비확장으로 적용합니다. (iOS, Android 동일) ### 레터박스 ### 레터박스 기본 배경 컬러 내비게이션바 아이콘은 레터박스 컬러 적용 기준에 따라 노출 영역이 달라집니다. 기본 검정 레터박스 사용 시 모바일과 동일하게 게임 영역 내에 노출되며, 게임별 커스텀 레터박스 컬러 지정 시 디바이스 우상단에 노출됩니다. * 레터박스 기본 배경 컬러는 검은색(`#000000`)입니다. * 기본 검정 레터박스 사용 시, 내비게이션바 아이콘은 모바일과 동일하게 게임 영역 내에 노출됩니다. ### 레터박스 커스텀 배경 컬러 * 상태바에 지정한 컬러를 레터박스 배경 컬러로 사용합니다. * 게임별 커스텀 레터박스 컬러 지정 시, 내비게이션바 아이콘은 디바이스 우상단 영역에 노출됩니다. **iPad 가로 모드** **iPad 세로 모드** **Android 가로 모드** **Android 세로 모드** **주의사항** **세로 모드** **가로 모드** ## 참고 문서 * [게임 콘텐츠 제작 가이드](/docs/design/content-image-guide): 앱 아이콘·가로형·세로형·공유 이미지와 동영상 제작 기준 * [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide): 내비게이션·로딩·팝업 등 게임웹뷰 UI 기준 * [게임 실행 흐름](/docs/webview/launch-flow#게임-url-접근-분기): PC·모바일 웹 직접 접근 시 환경별 분기 기준 * [심사 체크리스트](/docs/checklist/review-checklist): 디자인 자체 점검 항목 --- --- url: /docs/design/content-image-guide.md description: 게임플레이에 노출되는 앱 아이콘·가로형·세로형·공유 이미지와 동영상 제작 기준 --- # 게임 콘텐츠 제작 가이드 게임플레이 홈과 공유 화면에 노출되는 콘텐츠 이미지와 동영상의 제작 기준을 안내합니다. 심사를 요청하기 전에 각 콘텐츠의 가이드를 확인하고 제작하세요. ## 앱 아이콘 이미지 앱 아이콘 이미지는 게임을 나타내는 대표 이미지로 사용됩니다. * 앱 아이콘 형태 안에 게임 대표 이미지를 넣어 사용합니다. * 규정된 형태와 모서리 값을 비율대로 유지해야 합니다. * 게임 이미지 형태를 임의로 조정할 수 없습니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 비율 | `1 : 1` | | 제작 사이즈 | `640 × 640` | | 파일 형식 | `jpg`, `png` | | 최대 용량 | 200 KB | | 프로필 형태 | `128 × 128`, radius `32` | | 테두리 | `1px`, `#000000 12%` | ## 가로형 이미지 가로형 이미지는 게임플레이 홈에서 게임을 소개하는 이미지로 사용됩니다. * 이미지 좌상단에는 배지와 플레이유저수 정보가 노출될 수 있으므로 로고와 핵심 오브젝트를 배치하지 않습니다. * 게임 로고는 우상단 또는 중앙 정렬로 배치하는 것을 권장합니다. * 게임에 쓰이는 주요 오브젝트는 아래 표시된 Safe Area 안에 배치하는 것을 권장합니다. * 이미지 안에는 로고 외의 설명문구를 넣을 수 없습니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 비율 | `1.91 : 1` | | 제작 사이즈 | `1200 × 630` | | 파일 형식 | `jpg`, `png` | | 최대 용량 | 1 MB | | Safe Area | `1110 × 530` | ## 세로형 이미지 세로형 이미지는 게임플레이 홈에서 게임을 소개하는 이미지로 사용됩니다. * 이미지 최상단에는 배지와 플레이유저수 정보가 노출될 수 있으므로 로고와 핵심 오브젝트를 배치하지 않습니다. * 게임 로고는 중앙 정렬로 배치하는 것을 권장합니다. * 게임에 쓰이는 주요 오브젝트는 아래 표시된 Safe Area 안에 배치하는 것을 권장합니다. * 이미지 안에는 로고 외의 설명문구를 넣을 수 없습니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 비율 | `3 : 4` | | 제작 사이즈 | `1080 × 1440` | | 파일 형식 | `jpg`, `png` | | 권장 용량 | 1 MB 이하 | | 최대 용량 | 2 MB | | Safe Area | `1000 × 1024` | ## 세로형 동영상 세로형 동영상은 게임플레이 홈의 동영상 섹션에 노출됩니다. 동영상 등록은 권장 사항이며, 동영상을 등록하지 않은 게임은 홈의 동영상 섹션에 노출되지 않습니다. 홈에서는 영상의 중앙 `1080 × 1440` 영역을 `3 : 4` 비율로 재생하고, 풀뷰어에서는 `9 : 16` 원본 비율로 재생합니다. * 동영상을 등록하는 경우 영상 소재는 필수이며, 대표 썸네일 제작은 권장합니다. * 대표 썸네일을 제작하지 않으면 영상 소재에서 자동으로 추출한 썸네일이 노출됩니다. * 대표 썸네일은 동영상을 자동 재생할 수 없거나 재생에 실패한 경우에도 노출됩니다. * 썸네일을 선택하면 풀뷰어가 열립니다. * 플레이 버튼을 선택하면 게임이 시작됩니다. **영상 소재** | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 비율 | `9 : 16` | | 제작 사이즈 | `1080 × 1920` | | 파일 형식 | `mp4` | | 재생 시간 | 10~30초 | | 최대 용량 | 40 MB | | 오디오 | AAC | **대표 썸네일** | 항목 | 기준 | | --- | --- | | 적용 여부 | 권장 | | 비율 | `9 : 16` | | 제작 사이즈 | `1080 × 1920` | | 파일 형식 | `jpg`, `png` | | 권장 용량 | 1 MB 이하 | | 최대 용량 | 2 MB | ## 공유 이미지 공유 이미지는 카카오톡 공유 메시지에서 게임을 소개하는 이미지로 사용됩니다. * 게임플레이 홈과 공유 메시지의 이미지를 일관되게 보여주기 위해 가로형 이미지를 그대로 사용하는 것을 권장합니다. * 공유 이미지를 별도로 제작하는 경우에도 가로형 이미지와 동일한 규격을 적용합니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 권장 이미지 | 가로형 이미지 | | 비율 | `1.91 : 1` | | 제작 사이즈 | `1200 × 630` | | 파일 형식 | `jpg`, `png` | | 최대 용량 | 1 MB | ## 게임 이름·설명문구 게임 이름과 설명문구는 게임플레이 홈에서 게임을 소개하는 텍스트로 노출됩니다. * 모바일 `360` 해상도 기준입니다. * 게임 이름은 등급 심의를 받은 게임 이름과 동일하게 입력합니다. * 설명문구에는 욕설이나 비방 문구를 넣을 수 없습니다. * 권장 글자 수를 초과하면 일부 영역에서 말줄임될 수 있습니다. * 아래 노출 위치별 권장 글자 수를 참고하여 작성하세요. | 항목 | 권장 글자 수 | | --- | --- | | 게임 이름 | 11자 이하 권장 / 최대 19자 이내 | | 설명문구 | 12자 이하 권장 / 최대 21자 이내 | ## 참고 문서 * [게임 공통 제작 가이드](/docs/design/common-guide): 해상도·타이포그래피·컬러 기준 * [공유 설정](/docs/share/settings): 공유 기능 설정과 메시지 구성 * [심사 체크리스트](/docs/checklist/review-checklist): 콘텐츠 이미지 자체 점검 항목 --- --- url: /docs/design/webview-component-guide.md description: 게임웹뷰에 적용하는 상태바·내비게이션·킵버튼·메뉴·로딩·팝업 UI 기준 --- # 웹뷰 컴포넌트 가이드 게임웹뷰에 공통으로 적용하는 UI 컴포넌트의 동작과 디자인 기준을 안내합니다. 상태바, 내비게이션, 킵버튼과 기본 메뉴를 우선 적용하고, 게임에서 사용하는 선택 컴포넌트의 규격을 확인하세요. :::: warning 지원 종료 예정 이 가이드는 **게임플레이 JS SDK 를 사용하지 않는 환경**에만 해당합니다. [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)를 연동하면 내비게이션·드롭다운 메뉴·로딩·바텀시트·팝업을 SDK 가 직접 제공하므로, 이 문서의 컴포넌트를 게임이 만들지 않습니다. 새로 연동하는 게임은 [UI 컴포넌트](/api-sdk/sdk/gameplay-js/ui)를 먼저 확인해 주세요. SDK 를 적용하지 않은 게임은 계속 이 기준으로 제작합니다. 자세한 수치와 예시는 피그마 파일을 참고해 주세요. [게임플레이\_디자인가이드\_웹뷰 컴포넌트.fig](https://drive.google.com/drive/folders/1O2aKBC3_jWCLoHevwG45Nadrpu17o4nw) :::: ## 상태바 상태바는 모든 화면 상단에 반드시 배치합니다. 상태바 확장과 비확장 상태에 따라 게임 화면의 상단 안전영역을 다르게 적용합니다. **iOS** **Android** | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 배치 | 모든 화면 상단 | | iOS 기준 | `393 × 852` 해상도에서는 Dynamic Island를 고려 | | Android 기준 | `360 × 800` 해상도에서는 Camera Cutout을 고려 | | 관련 기능 | [`setStatusBarOverlay`](/api-sdk/sdk/kakaotalk-gameplay#setstatusbaroverlay-options), [`changeStatusBarColor`](/api-sdk/sdk/kakaotalk-gameplay#changestatusbarcolor-color) | ### 상태바 확장 게임 웹뷰를 확장할 경우 웹뷰 콘텐츠가 상태바까지 표시되므로, 주요 텍스트·버튼·재화 정보 등은 상태바 영역을 피해서 배치합니다. 참고: [`setStatusBarOverlay`](/api-sdk/sdk/kakaotalk-gameplay#setstatusbaroverlay-options) **iOS** `393 × 852` 기준의 해상도인 경우 Dynamic Island를 고려하여 적용합니다. **Android** `360 × 800` 기준의 해상도인 경우 Camera Cutout을 고려하여 적용합니다. ### 상태바 비확장 게임웹뷰를 확장하지 않는 경우, 웹뷰 콘텐츠는 기본 레이아웃 영역 내에 표시됩니다. 기본 상태바 스타일은 배경 `#FFFFFF` / 아이콘 `#000000`으로 적용됩니다. **iOS** **Android** ### 상태바 비확장 시, 배경 커스텀 컬러 기본 상태바 배경 컬러는 `#FFFFFF`, 아이콘은 `#000000`으로 적용됩니다. 상태바 배경은 커스텀 컬러로 변경할 수 있으나, 아이콘은 항상 `#000000`을 유지합니다. 상태바 배경 색상 변경이 필요할 경우, 선택적으로 커스텀 컬러 가이드에 맞춰 변경할 수 있습니다. * 해당 기능은 카카오톡 `26.6.0`부터 사용할 수 있습니다. * 참고: [`changeStatusBarColor`](/api-sdk/sdk/kakaotalk-gameplay#changestatusbarcolor-color) | 구분 | 기준점 컬러 | 기준 | | --- | --- | --- | | 커스텀 컬러 | `#4C4C4C` (어두운 컬러 예시) | HSB 기준 Brightness(B)는 30 이상 권장 | | 블랙 | `#000000` | 상태바 아이콘과 동일한 컬러로 사용 금지 | | 내비게이션바 아이콘 컬러 | `#363636` | 내비게이션바 아이콘과 동일한 컬러로 사용 금지 | | 원색, 형광색 컬러 | `#FFFF00` (형광 컬러 예시) | 눈의 피로도가 높은 원색·형광색 컬러 금지 | **iOS** `393 × 852` 기준의 해상도인 경우 Dynamic Island를 고려하여 적용합니다. **Android** `360 × 800` 기준의 해상도인 경우 Camera Cutout을 고려하여 적용합니다. **Tablet** **주의사항** ## 내비게이션 내비게이션은 모든 화면 상단에 반드시 배치되며, 게임의 상단 요소와 겹치지 않게 배치합니다. Leading Controls의 아이콘은 닫기를 사용하며 오른쪽에 위치합니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 배치 | 모든 화면 상단 | | Leading Controls | 닫기 아이콘 사용, 오른쪽 배치 | | 아이콘 컬러 | `#FFFFFF 90%` | | 아이콘 크기 | `20 × 20` | | 아이콘 배경 | `#FFFFFF 2%` + `#2E2E2E 67%` | | 아이콘 배경 테두리 | `#000000 12%`, weight `0.5` | | 아이콘 배경 크기 | `36 × 36` | ### 공통 내비게이션바 기존 게임 및 게임 제작 시 내비게이션의 메뉴와 게임 메뉴가 겹치지 않도록 배치하는 것을 권장합니다. ### 가로모드 전용 가로 모드에서도 내비게이션 기능과 게임 메뉴가 겹치지 않아야 합니다. ## 킵버튼 ### 자동 접기 기능 iOS 게임웹뷰에서 게임을 실행하는 중 접기 버튼을 선택하면 실행 중인 카카오톡 화면으로 돌아가며, 게임으로 재진입할 수 있도록 플로팅 버튼을 제공합니다. 자동 접기, 더보기, 닫기 순서로 노출됩니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 플랫폼 | iOS 전용 | | 사용 시점 | 게임 실행 중 접기 버튼 선택 시 | | 노출 방식 | 플로팅 버튼으로 노출 | | 아이콘 | 게임플레이 아이콘 자동 적용 | | 관련 기능 | [`keepBrowser`](/api-sdk/sdk/kakaotalk-gameplay#keepbrowser) | ### 플로팅 게임 웹뷰에서 접기 버튼을 선택하면 플로팅 버튼이 노출되며, 다른 화면에서도 게임으로 재진입할 수 있습니다. 플로팅 버튼은 자유롭게 위치를 옮기거나 드래그하여 삭제할 수 있습니다. 플로팅 시 사용되는 아이콘은 게임플레이 아이콘으로 자동 적용되며, 개발사에서 별도로 적용할 부분은 없습니다. 참고: [`keepBrowser`](/api-sdk/sdk/kakaotalk-gameplay#keepbrowser) (`카카오톡 v26.6.0` 이상) 플로팅 버튼을 선택하면 게임 웹뷰로 다시 진입합니다. ## 드롭다운 메뉴 더보기 메뉴를 선택하면 드롭다운으로 항목을 선택하거나 상태를 확인·변경할 수 있습니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 메뉴 개수 | 최대 3개 | | 필수 메뉴 | 공유하기, 문의하기 | | 선택 메뉴 | 최대 1개 | | 선택 메뉴 글자 수 | 최대 10자 | | 텍스트 | 14pt, `#191919` | | 컨테이너 | `#FFFFFF`, radius `8` | | 그림자 | `#000000 20%`, `1, 1, 10, 0` | ### 메뉴 상세 **공유하기** (첫 번째 메뉴) * 클릭하면 카카오톡 친구 선택 하프뷰가 노출됩니다. * 공유 스펙 상세는 [공유 설정](/docs/share/settings)을 참고하세요. | 항목 | 기준 | | --- | --- | | 진입 | 헤더 풀다운 메뉴 > 첫 번째 메뉴 | | 메뉴명 | "공유하기" | | 대상 도메인 | [공유 설정](/docs/share/settings) 참고 | **문의하기** (두 번째 메뉴) * 클릭하면 파트너사의 고객센터(CS) 페이지가 **인앱브라우저**로 노출됩니다. * **CS 도메인은 게임 실행 도메인과 반드시 분리해야 합니다.** 게임 실행 도메인 하위 경로(예: `game.partner.com/support`)로 설정하면 인앱브라우저가 아니라 게임웹뷰로 실행되어 정상 동작하지 않습니다. 게임웹뷰가 도메인당 하나만 유지되는 특성 때문이며, 경로를 나눠도 해소되지 않습니다. 자세한 내용은 [게임웹뷰 SDK: 인앱브라우저 스킴](/api-sdk/sdk/kakaotalk-gameplay#인앱브라우저-스킴)을 참고해 주세요. | 항목 | 기준 | | --- | --- | | 진입 | 헤더 풀다운 메뉴 > 두 번째 메뉴 | | 메뉴명 | "문의하기" | | 대상 도메인 | 파트너사 CS 도메인(게임 실행 도메인과 다른 도메인) | | 실행 방식 | 카카오톡 인앱브라우저 | ### 게임 내 외부 링크 실행 드롭다운 메뉴에서 고객센터 등 게임 밖의 외부 링크를 선택하면 게임웹뷰 위로 카카오톡 인앱브라우저가 열립니다. 외부 페이지를 게임웹뷰 안에서 직접 전환하지 말고 인앱브라우저로 실행해 사용자가 닫은 뒤 게임으로 돌아올 수 있도록 구성하세요. **실행 흐름** 게임 중 → 드롭다운 메뉴 선택 → 외부 링크 선택 → 카카오톡 인앱브라우저 | 링크 유형 | 실행 방식 | | --- | --- | | 게임 실행 URL | 게임웹뷰에서 실행 | | 고객센터·이벤트·정책 등 외부 URL | 카카오톡 인앱브라우저에서 실행 | ## 로딩 로딩 아이콘 리소스가 필요한 경우 카카오에 별도 요청합니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 사용 위치 | 인트로 페이지 또는 로딩 리소스가 필요한 화면 | | 애니메이션 | 1.4초 동안 360도 회전 | | 위치 | 화면 중앙 정렬 | ## 바텀시트 사용자가 현재 뷰에서 벗어나지 않고 이전 뷰나 액션에 연관된 기능·정보를 확인하는 방식입니다. 게임 구현 시 필요한 경우 사용합니다. **플랫폼 차이** Android는 바텀시트 실행 시 Empty View가 노출되면 동적 높이 처리가 불가하며 높이가 고정됩니다. iOS는 Empty View 노출 여부와 관계없이 모든 상태에서 높이 변경이 가능합니다. * 해상도 `393 × 852` 기준으로 높이를 지정합니다. * 홈 인디케이터는 바텀시트 높이에 포함하지 않습니다. * 최초 높이는 Small~Large 범위에서 여는 것을 권장합니다. 처음부터 Full로 사용하는 것은 지양합니다. * 가로 모드는 Small, Full 두 크기만 제공합니다. 세로 모드의 Medium 이상은 가로 모드에서 Full로 노출됩니다. * Close 버튼을 단독으로 두기보다 핸들러 드래그 또는 딤드 영역 탭으로 닫는 흐름을 우선 고려합니다. * 2 Depth 이후 바텀시트는 1 Depth보다 낮은 높이를 사용합니다. | 타입 | 높이 기준 | | --- | --- | | Small | `224 dp/pt` | | Medium | `408 dp/pt` | | Large | `528 dp/pt` | | Full | 상태바·내비게이션을 제외한 전체 영역 | ## 토스트 주요 콘텐츠를 가리는 위치는 피하고 간결하고 명확한 내용만 전달합니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 옵션 | | 위치 | 레이어의 최상위 뷰 (하단 권장) | | 최소 너비 | 88 px | | 최대 너비 | 464 px | | 노출 시간 | 5초 이내 | | 텍스트 | 14pt, `#FFFFFF` | | 컨테이너 | `#FFFFFF 10%` + `#1B1C25 67%`, radius `12` | | 효과 | Background Blur `50%` | | Bottom Type 위치 | Safe area 기준 default `65px`, minimum `16px` | ## 공통 팝업 화면 중앙에 위치하며 좌우 최소 여백을 유지하고 너비가 늘어납니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 옵션 | | 위치 | 화면 중앙 | | 최대 너비 | 464 px | | 폰트 | Pretendard | | 타이틀 | 17pt, `#191919`, 최대 2줄 | | 서브 텍스트 | 15pt, `#595959` | | 컨테이너 | `#FFFFFF`, radius `16` | | 그림자 | `#000000 25%`, `0, 0, 8, 0` | | 버튼 텍스트 | 15pt, `#191919` | | 버튼 컨테이너 | `#000000 6%`, radius `8` | ## 게임 종료 팝업 * 공통 팝업과 동일한 규격을 사용합니다. * 게임 이름과 `게임을 그만할까요?` 텍스트를 노출합니다. * 게임 이름은 두 줄 노출 후 말줄임 처리합니다. * 확인 버튼을 선택하면 다른 랜딩으로 이동할 수 없습니다. | 항목 | 기준 | | --- | --- | | 적용 여부 | 필수 | | 사용 시점 | 게임 종료 시 | | 랜딩 | 확인 버튼 선택 시 게임플레이 홈 진입 | ## 에러 게임 내 에러 상황에 따라 두 가지 타입을 사용합니다. | 타입 | 사용 상황 | 적용 예시 | | --- | --- | --- | | 에러 토스트 | 게임 진행 중 일시적 에러, 자동 복구 가능 | 네트워크 순단 후 자동 재연결, 부가 기능 일시 실패 | | 에러 팝업 | 자체 복구가 어려워 재시도·종료 선택지를 제공해야 하는 경우 | 리트라이 N회 이상 실패, 세션 만료, 서버 점검 등 | ## 유료 데이터 환경 * Wi-Fi 미연결 상태에서 유료 데이터 사용 안내는 Toast Popup 또는 Popup으로 노출합니다. * 게임 데이터가 100 MB 이상이면 카카오와 사전 협의가 필요합니다. | 케이스 | 기준 | | --- | --- | | Toast Popup | 일반적인 유료 데이터 사용 안내 | | Popup | 게임 데이터가 100 MB 이상인 경우 필수 | ## 참고 문서 * [게임 공통 제작 가이드](/docs/design/common-guide): 해상도·타이포그래피·컬러 기준 * [게임 콘텐츠 제작 가이드](/docs/design/content-image-guide): 앱 아이콘·배너·공유 이미지 제작 기준 * [상태바 오버레이 설정 방법](/docs/webview/status-bar-overlay): 외부 화면 전환 시 상단 잘림 대응 * [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay): 게임웹뷰 기능 구현 스펙 * [심사 체크리스트](/docs/checklist/review-checklist): 웹뷰 UI 자체 점검 항목 --- --- url: /docs/share/settings.md description: 카카오 JS SDK 기반 카카오톡 공유·URL 복사 연동 방법 --- # 공유 설정 공유 설정은 파트너사 디벨로퍼스 앱에 설정된 카카오톡 공유 기능을 사용합니다. 공유 기능은 디벨로퍼스 앱 설정을 완료한 뒤 사용할 수 있으며, 본 문서는 게임플레이 환경에서 카카오 JS SDK로 카카오톡 공유·URL 복사 기능을 연동하는 방법을 정리합니다. 메시지는 카카오가 사전 정의한 공유 템플릿 ID와 사용자 인자를 기준으로 발송됩니다. 공유 성공 후 보상 결과 통지 연동은 [**공유 웹훅 연동**](/api-sdk/share/reward-result)을 참고하세요. ## 적용 범위 * 카카오 JS SDK를 이용한 공유 SDK 호출 (디벨로퍼스 가이드 참고) * 사용자 정의 템플릿 기반 메시지 발송 * 카카오톡 공유와 URL 복사 두 타입 연동 ## 사전 셋팅 항목 공유 기능을 연동하기 전에 카카오 제공 값과 파트너사 앱 설정을 먼저 확인합니다. ### 카카오 제공 값 * 환경별 메시지 템플릿 ID * 템플릿에 전달할 사용자 인자(`templateArgs`) * 공유 피커 `groupId` * 공유 웹훅 연동 기준값 ### 파트너사 설정 항목 * 파트너사 앱의 JavaScript 키 확인과 게임 실행 도메인 등록: **\[앱] > \[플랫폼 키] > \[JavaScript 키] > \[JavaScript SDK 도메인]** * **\[앱] > \[제품 링크 관리] > \[웹 도메인]** 에 게임플레이 도메인(`https://gameplay.kakao.com`) 등록 * 카카오 JS SDK 로드 및 초기화 준비 * 공유 SDK 호출 시 카카오가 전달한 `templateId`·`groupId` 적용 * [단축 URL 생성](/api-sdk/share/short-url) 응답을 `BUTTON_URL`과 `copy_url`에 주입하도록 매핑 * 공유 웹훅용 `serverCallbackArgs` 구성 * 필요한 경우 [파트너사 앱의 카카오톡 공유 웹훅 설정](https://developers.kakao.com/docs/ko/kakaotalk-share/callback#success): **\[앱] > \[웹훅] > \[카카오톡 공유 웹훅]** ## 사전 이해 사항 | 구분 | 설명 | | --- | --- | | SDK 버전 | 최소 `2.8.0` 이상 | | 사용 앱 키 | 디벨로퍼스의 파트너사 앱의 JavaScript 키 (어드민 키 미사용) | | 도메인 제한 | **\[앱] > \[플랫폼 키] > \[JavaScript 키] > \[JavaScript SDK 도메인]** 에 등록한 도메인에서만 정상 동작 | | 메시지 템플릿 | 카카오가 사전 생성한 사용자 정의 템플릿 사용 | | 사용자 인자 | 템플릿의 `${KEY}` 값을 `templateArgs`에 동일 키로 전달 | SDK 설치와 초기화 방법은 [카카오 JS SDK](/api-sdk/sdk/kakao-js)를 참고하세요. ## 공유 흐름 1. 사용자가 게임 안에서 공유 버튼을 누릅니다. 2. 파트너사는 카카오의 [**단축 URL 생성**](/api-sdk/share/short-url)을 호출해 공유용 단축 URL을 발급받습니다. 3. 응답받은 URL을 `templateArgs.BUTTON_URL`과 `pickerSettings.args.copy_url`에 주입합니다. 4. `Kakao.Share.sendCustom()`을 호출합니다. 게임 공유·보상 공유·자랑하기 모두 `pickerSettings`를 포함합니다. 5. 사용자가 카카오톡에서 공유를 완료합니다. 6. 디벨로퍼스에 공유 웹훅을 설정하였을 경우 [공유 웹훅 연동](/api-sdk/share/reward-result)을 통해 결과가 통지됩니다. ## 공유 타입 | 타입 | 공유 범위 | 말풍선 형태 | 비고 | | --- | --- | --- | --- | | 카카오톡 공유 | 카카오톡 내 메시지 | 사전 정의된 템플릿 | 카카오가 제공하는 템플릿 ID 사용 | | URL 복사 | 외부 브라우저·블로그 등 카카오톡 외부 | OG 태그 스크랩 | `pickerSettings.args.copy_url`에 단축 URL 전달 | 예시 - 공유 타입별 공유 피커 ## 카카오톡 공유 템플릿 ID 카카오톡 공유는 하나의 템플릿 ID로 메시지 타입별 소재를 구분해 사용합니다. 템플릿 ID는 카카오가 사전 생성해 파트너사에 전달하는 값이며, 디벨로퍼스 문서에서는 [사용자 정의 템플릿](https://developers.kakao.com/docs/ko/message-template/custom#how-to-use)이라는 이름으로 안내됩니다. | 환경 | 템플릿 ID | 피커 groupId | | --- | --- | --- | | CBT | 126532 | 10 | | PROD | 126533 | 12 | 메시지 타입: | 타입 | 적용 여부 | 설명 | 예시 이미지 | | --- | --- | --- | --- | | `GAME_SHARE` | 필수 | 보상 없이 단순 게임을 공유 | | | `REWARD_SHARE` | 선택 | 공유를 통해 보상(아이템·점수 등)을 제공 | | | `RANKING_SHARE` | 선택 | 랭킹·스테이지 클리어 자랑하기 | | ## 구현 상세 안내 ### SDK 초기화 파트너사 앱의 JavaScript 키로 SDK를 초기화합니다. ```ts window.Kakao.init('JAVASCRIPT_KEY'); ``` 설치 스크립트와 버전 요구사항은 [카카오 JS SDK](/api-sdk/sdk/kakao-js)에 정리되어 있습니다. ### 단축 URL 생성 API 호출 공유 SDK 호출 전에 단축 URL을 먼저 발급받습니다. 응답의 `short_url`을 이후 `templateArgs.BUTTON_URL`과 `pickerSettings.args.copy_url`에 주입합니다. ```ts interface ShortUrlResponse { short_url: string; } const response: ShortUrlResponse = await callShortUrlApi({gameCode}); ``` API 상세는 [단축 URL 생성](/api-sdk/share/short-url)을 참고하세요. ### 공유 호출 게임 공유·보상 공유·자랑하기 모두 아래 방식으로 `Kakao.Share.sendCustom()`을 호출합니다. `pickerSettings`는 반드시 포함합니다. ```ts type MessageType = 'GAME_SHARE' | 'RANKING_SHARE' | 'REWARD_SHARE'; interface SendCustomPayload { installTalk: boolean; templateId: number; templateArgs: { THU: string; TITLE: string; DESCRIPTION: string; BUTTON_TEXT: string; BUTTON_URL: string; }; pickerSettings: { args: {copy_url: string}; groupId: number; limit: number; type: 'default'; logs: { section: 'gameplay'; customProps: { gameplay_message_type: MessageType; gameplay_origin: string; gameplay_game_type: string; gameplay_template_id: number; }; }; }; serverCallbackArgs: { APP_USER_ID: number; APP_ID: number; GAME_TYPE: string; MESSAGE_TYPE: MessageType; HAS_REWARD: boolean; SHARE_ID?: string; }; } window.Kakao.Share.sendCustom({ installTalk: true, templateId: 126533, // CBT=126532, PROD=126533 templateArgs: { THU: THUMBNAIL_URL, TITLE: 'MESSAGE_TITLE', DESCRIPTION: 'MESSAGE_DESCRIPTION', BUTTON_TEXT: '지금 플레이', BUTTON_URL: response.short_url, }, pickerSettings: { args: { copy_url: response.short_url, }, groupId: PICKER_GROUP_ID, // CBT=10, PROD=12 limit: 1, type: 'default', logs: { section: 'gameplay', customProps: { gameplay_message_type: 'GAME_SHARE', gameplay_origin: `${PARTNER_NAME}_GAME`, gameplay_game_type: `${PARTNER_NAME}_${GAME_TITLE}`, gameplay_template_id: TEMPLATE_ID, // CBT=126532, PROD=126533 }, }, }, serverCallbackArgs: { APP_USER_ID: 1111111, APP_ID: 1234567, GAME_TYPE: 'sample-game', MESSAGE_TYPE: 'GAME_SHARE', HAS_REWARD: true, SHARE_ID: 'a3f2c5b7-9d11-4e8a-9f01-2b6c7e8a9d10', }, } satisfies SendCustomPayload); ``` ## 필드 상세 ### templateArgs 템플릿에 `${KEY}` 형태로 정의된 값을 동일한 key로 전달합니다. 같은 템플릿을 사용하더라도 공유 대상 게임에 따라 실제 메시지 내용과 이미지가 달라지도록 구성합니다. | 인자 | 설명 | 스펙 | | --- | --- | --- | | `THU` | 공유 대상 게임의 대표 이미지 또는 썸네일 URL | — | | `TITLE` | 메시지 제목 | 최대 1줄, 최대 15자 (공백 포함) | | `DESCRIPTION` | 메시지 본문 | 최대 2줄, 100자 내외 | | `BUTTON_TEXT` | 버튼 텍스트 | 최대 10자 (공백 포함) | | `BUTTON_URL` | 버튼 랜딩 링크. 단축 URL 응답값(`short_url`) 사용 | — | ### serverCallbackArgs 공유 웹훅으로 전달되어 로그 수집에 사용됩니다. | 필드 | 타입 | 적용 여부 | 설명 | | --- | --- | --- | --- | | `APP_USER_ID` | `long` | ✓ | 파트너사 앱 사용자 식별자 (공유 주체) | | `APP_ID` | `long` | ✓ | 파트너사 식별자 (다중 게임 운영 시 라우팅) | | `GAME_TYPE` | `string` | ✓ | 게임플레이 파트너센터에 등록한 게임 코드와 동일한 게임 식별자 | | `MESSAGE_TYPE` | `enum` | ✓ | `GAME_SHARE` (게임 공유) 또는 `RANKING_SHARE` (자랑하기) | | `HAS_REWARD` | `boolean` | ✓ | `true`: 보상 있음, `false`: 단순 공유 | | `SHARE_ID` | `string` (UUID) | | 파트너사가 공유 시점에 발급하는 트랜잭션 식별자. 콜백 응답 매칭 키 | ### pickerSettings | 필드 | 설명 | 값 | | --- | --- | --- | | `args.copy_url` | URL 복사 링크 | 단축 URL 응답값(`short_url`) | | `groupId` | 공유 피커 그룹 ID | CBT `10`, PROD `12` | | `limit` | 공유 대상 선택 가능 수 | `1` | | `type` | 공유 대상 선택 화면 유형 | `default` | | `logs.section` | 공유 로그 구분값 | `gameplay` | | `logs.customProps.gameplay_message_type` | 소재 구분 | `GAME_SHARE` / `RANKING_SHARE` / `REWARD_SHARE` | | `logs.customProps.gameplay_origin` | 파트너사 게임 출처 구분값 | `{파트너사명}_GAME`, 사전 협의 필요 | | `logs.customProps.gameplay_game_type` | 파트너사명과 게임 이름 결합 식별값 | `{파트너사명}_${GAME_TITLE}` | | `logs.customProps.gameplay_template_id` | 사용 템플릿 ID | CBT `126532`, PROD `126533` | ## 참고 문서 * [카카오 JS SDK](/api-sdk/sdk/kakao-js): SDK 설치와 초기화 * [단축 URL 생성](/api-sdk/share/short-url): 공유용 단축 URL 발급 * [공유 웹훅 연동](/api-sdk/share/reward-result): 공유 성공 후 파트너사 서버로 결과 통지 * [심사 체크리스트](/docs/checklist/review-checklist): 공유 관련 자체 점검 사항 * [카카오톡 공유 JavaScript 가이드](https://developers.kakao.com/docs/ko/kakaotalk-share/js-link) * [사용자 정의 템플릿 사용자 인자 가이드](https://developers.kakao.com/docs/ko/message-template/custom#user-argument-text) --- --- url: /docs/ads/product-overview.md description: 카카오톡 게임플레이에서 지원하는 애드핏 리워드·전면형 광고 상품 안내 --- # 광고 상품 소개 게임플레이에는 **애드핏에서 제공하는 광고 상품만 연동**할 수 있습니다. 지원하는 상품은 **리워드(보상형) 광고**와 **전면형 광고** 두 가지입니다. ## 지원 상품 | 상품 | 보상 | 소재·노출 방식 | | --- | --- | --- | | 리워드(보상형) 광고 | 있음 | 사용자가 자발적으로 시청을 선택하는 풀스크린 동영상 광고. 시청 조건을 충족하면 보상을 지급하고 엔드카드를 노출 | | 전면형 광고 | 없음 | 화면 전환 사이에 노출할 수 있는 풀스크린 이미지 광고 | ## 리워드(보상형) 광고 사용자의 자발적인 시청 참여를 기반으로 보상을 제공하는 풀스크린 광고입니다. * 광고를 보기 전 보상 내용과 지급 조건을 안내합니다. * 애드핏에서 설정한 최소 시청 시간 또는 전체 시청 조건을 충족한 사용자에게 보상을 지급합니다. * 동영상 재생이 끝나면 엔드카드를 노출해 광고주 페이지로 이동할 수 있습니다. * 동영상은 세로형 화면을 기본으로 노출하며, 게임 화면 방향과 광고단위 설정에 따라 표시됩니다. ### 상품 시안 ## 전면형 광고 게임 화면 전환 사이에 노출할 수 있는 비보상형 풀스크린 이미지 광고입니다. * 광고 시청에 따른 게임 보상은 지급하지 않습니다. * 1:1 또는 4:5 비율의 이미지 소재를 화면에 맞춰 노출합니다. * 행동 유도 버튼을 누르면 광고주 페이지로 이동합니다. * 사용자는 `다시 보지 않기` 또는 `닫기`로 광고를 종료할 수 있습니다. ### 상품 시안 ## 다음 단계 * [광고 UX 가이드](/docs/ads/ux-guideline): 광고 노출 위치와 사용자 경험 기준 * [애드핏 설정](/docs/ads/iaa-options): 매체 등록과 광고단위 발급 * [애드핏 광고 SDK](/api-sdk/sdk/adfit): 광고 연동과 이벤트 처리 --- --- url: /docs/ads/ux-guideline.md description: 게임웹뷰 안에서 애드핏 보상형·전면형 광고를 운영할 때 지켜야 하는 UX 기준 --- # 광고 UX 가이드 파트너사 게임이 애드핏 보상형·전면형 광고를 노출할 때 준수해야 하는 UX 원칙과 배치 정책을 정리합니다. 이 문서는 정책성 기준이며, 실제 SDK 사용법은 [애드핏 광고 SDK](/api-sdk/sdk/adfit)를 참고하세요. ## 적용 범위 * 카카오톡 게임웹뷰 안에서 노출되는 애드핏 보상형·전면형 광고 * 심사 대상 항목이며 위반 시 재작업이 요청될 수 있습니다. ## 광고 운영 원칙 ### Opt-in 기반 운영 * 보상형·전면형 광고는 사용자가 보상 또는 광고 노출을 인지하고 자발적으로 시청을 선택하는 참여형 광고입니다. * 사용자의 명확한 액션(버튼 클릭 등) 이후에만 노출합니다. * 자동 실행 및 예기치 않은 전면 노출은 금지합니다. * 동일한 사용자 동선에서 전면 광고를 반복 호출하거나 시청을 강요하는 방식은 금지합니다. ### 서비스 UI와 광고의 구분 * 사용자가 "서비스 화면"과 "광고"를 혼동하지 않도록 광고는 광고로 명확히 식별될 수 있어야 합니다. * 광고를 서비스 기능처럼 위장하거나 오해를 유발하는 UI 구성은 금지합니다. * 사용자가 광고가 어떤 애플리케이션(서비스)에 구현·연결되어 있는지 명확히 파악할 수 있어야 합니다. **금지 예시** | 유형 | 예시 | | --- | --- | | 광고를 게임 플레이로 위장 | "보너스 레벨", "숨겨진 스테이지" | | 광고를 서비스 기능으로 위장 | "프리미엄 콘텐츠 보기" | ### 사용자 경험 보호 * 광고 실패·No fill 시 현재 화면을 유지하고 비침습적 안내(Toast 등)를 제공합니다. * 광고 종료 후 진입 직전 화면·상태로 정확히 복구합니다. * 보상 지급은 `rewarded` 이벤트를 기준으로 처리합니다. 세부 권장 사항은 아래 [UX 권장 가이드](#ux-권장-가이드)를 참고하세요. ## 광고 게재 위치 정책 ### 공통 원칙 방문자가 콘텐츠를 사용하는 동안 실수로 클릭할 수 있는 위치에 광고를 배치할 수 없습니다. * 링크, 재생 버튼, 다운로드 버튼, 이전·다음 버튼, 드롭다운 메뉴, 내비게이션 바 등 실수 클릭이 발생할 수 있는 요소 근처에 광고 배치 금지 * 광고 닫기 버튼이 광고 영역 내에 위치하는 배치 금지 문구·이미지 등 어떤 방식으로든 방문자가 광고를 클릭하도록 고의로 유도할 수 없습니다. * 클릭을 유도·부탁하는 문구·이미지 사용 금지 * 화살표 등으로 광고를 가리키거나 색상·애니메이션으로 광고 영역을 부각시키는 행위 금지 기타 금지 사항: * 오해의 소지가 있는 제목(예: "추천", "유용한 링크") 아래 광고 배치 금지 * 오클릭을 유발하기 쉬운 콘텐츠 위치(유아·어린이 대상 매체 포함) 광고 배치 금지 * 사용자가 원하지 않았음에도 새로고침·페이지 갱신이 반복되는 페이지의 광고 배치 금지 * 콘텐츠를 덮거나 가리는 영역에 광고 배치 금지 * 광고 클릭 없이는 페이지를 이동할 수 없는 위치에 광고 배치 금지. 광고 화면에서도 뒤로가기·메뉴 버튼이 존재해야 합니다 * 광고가 배치되는 공간은 고정되어 있어야 합니다. 스크롤 등으로 위치가 흔들리며 오클릭을 유발하는 배치 금지 * 광고와 유사하게 만든 콘텐츠를 광고 주변에 배치하여 광고를 위장하는 행위 금지 * 백그라운드·위젯·앱 종료 후 등 포그라운드가 아닌 상태에서의 광고 노출 금지 * 서비스 이용 맥락과 무관한 시점의 광고 노출 또는 과도한 반복 노출 금지 * 중요 정보 확인·결제·입력·본인확인 등 사용자의 핵심 행동 진행 중 광고 노출 금지 ### 전면 광고 및 보상형 광고 * 사용자의 명확한 행동(버튼 클릭 등)에 의해 실행될 때만 노출합니다. * 앱 로드 시점, 앱 종료 시점, 백그라운드 상태, 앱 외부 환경에서의 광고 노출은 금지합니다. * 결제·입력·본인확인·중요 정보 확인 등 핵심 행동이 진행 중일 때는 노출할 수 없습니다. * 동일한 사용자 동선에서 전면 또는 보상형 광고를 반복적으로 연속 노출하는 행위는 금지합니다. ### 보상형 광고 추가 정책 * 보상형 광고는 사용자의 자발적 참여(Opt-in)를 전제로 하는 광고 상품입니다. * 보상 조건, 보상 지급 여부, 보상 지급 시점을 사용자가 명확히 인지할 수 있도록 안내합니다. * 퍼블리셔가 설정한 리워드 지급 최소 시청 시간은 보상 조건에 해당합니다. * 보상 조건 충족 이전에 광고를 종료하면 해당 시청은 보상 대상에서 제외됩니다. * 보상 조건 충족 이후 제공되는 서비스로 복귀하는 버튼 또는 엔드카드 이동 버튼은 광고 스킵이 아닌 정상 종료 UX로 간주합니다. ## 기본 제공 이벤트 광고 SDK가 제공하는 표준 이벤트입니다. | 이벤트 | 발생 시점 | | --- | --- | | `loaded` | 광고 로드 완료 | | `failed` | 광고 로드 실패 | | `opened` | 광고 표시 시작 | | `closed` | 광고 종료 | | `rewarded` | 보상 지급 조건 충족 (보상형만) | | `unloaded` | 광고 리소스 해제 | 세부 스펙은 [애드핏 광고 SDK: 이벤트](/api-sdk/sdk/adfit#이벤트)를 참고하세요. ## UX 권장 가이드 ### No fill·실패 처리 * `loaded` 전에는 "광고 보기" 버튼을 disabled 또는 hidden으로 유지합니다. * `failed` 시 화면 전환은 지양하고 Toast 메시지로 안내합니다. * 사용자가 버튼을 눌렀을 때 대기 시간 없이 광고가 재생되도록, 이전 광고가 닫힌 직후(`closed`) 다음 광고를 미리 로드하는 것을 권장합니다. 권장 안내 문구 예시: > "현재 이용 가능한 광고가 없습니다. 잠시 후 다시 시도해 주세요." > > "광고가 준비 중입니다. 잠시 후 다시 이용해 주세요." ### 보상 지급 시점 `rewarded`, `closed` 이벤트가 모두 제공되지만 **보상은 `rewarded` 이벤트 기준으로 지급**하는 것을 권장합니다. 지급 누락을 방지할 수 있습니다. ### Android Back Key 처리 Back Key는 시청 의사를 철회하는 신호입니다. 즉시 종료 대신 **보상 포기 확인 UX**를 권장합니다. 권장 흐름: 1. Back 1회: `ad.close()` 호출 2. "시청을 중단하시겠어요?" 팝업 노출 3. 사용자가 "시청 중단" 선택 시 `closed` 수신 4. 진입 직전 화면으로 복귀 5. "리워드 지급 실패" 안내 Toast 노출 ### 광고 종료 후 화면 복구 * 광고 진입 직전(Origin) 화면·상태를 저장한 뒤 `closed` 수신 시점에 복구합니다. * 보상 기준 미달로 종료된 경우 리워드 지급 실패 안내 Toast를 함께 노출합니다. 권장 안내 문구 예시: > "광고 시청이 완료되지 않아 보상을 받을 수 없습니다." > > "보상을 받으려면 광고를 끝까지 시청해 주세요." ## 참고 문서 * [광고 상품 소개](/docs/ads/product-overview) * [애드핏 광고 SDK](/api-sdk/sdk/adfit) * [애드핏 설정](/docs/ads/iaa-options) * [심사 체크리스트](/docs/checklist/review-checklist) --- --- url: /docs/ads/iaa-options.md description: 애드핏 매체 등록과 리워드·전면형 광고단위 발급 및 운영 설정 방법 --- # 애드핏 설정 파트너사가 애드핏 광고를 게재하기 위해 필요한 매체 등록과 리워드·전면형 광고단위 발급 절차를 안내합니다. 테스트 광고·대체 광고·민감 카테고리 차단처럼 운영 전에 확인할 설정도 함께 적용하세요. 매체 등록과 광고단위 발급은 [애드핏](https://adfit.kakao.com)에서 진행합니다. 애드핏 가입과 기본 이용 방법은 카카오비즈니스의 [애드핏 가이드](https://kakaobusiness.gitbook.io/main/partner/adfit)를 함께 확인하세요. ## 적용 대상 * 애드핏 플랫폼에서 카카오톡 게임플레이 매체로 광고단위를 발급받으려는 파트너사 관련 UX·정책 기준은 [광고 UX 가이드](/docs/ads/ux-guideline)를 참고하세요. ## 애드핏 가입 절차 애드핏은 사전 승인 또는 초대를 받은 파트너사만 가입할 수 있습니다. 가입 전에 **카카오 담당자로부터 인증코드를 받은 뒤** 아래 순서에 따라 사업자 가입을 진행하세요. 이미 애드핏 계정이 있는 파트너사는 인증코드를 발급받지 않고 그대로 사용하며, 계정 정보를 카카오 담당자에게 전달하세요. 1. 카카오 담당자에게 애드핏 가입 인증코드를 받습니다. 2. 전달받은 인증코드를 입력하고 인증합니다. 3. 이용약관에 동의하고 회원 유형으로 **사업자**를 선택합니다. 4. 사업자 정보와 알림 설정을 입력해 가입을 완료합니다. 인증코드는 최초 계정 생성에 한 번만 사용할 수 있습니다. 여러 명이 같은 사업자 계정을 운영하는 경우, 최초 가입자가 계정을 만든 뒤 다른 운영 인원을 멤버로 초대하세요. 사업자 정보 입력 항목과 상세 화면은 [애드핏 사업자 가입 가이드](https://kakaobusiness.gitbook.io/main/partner/adfit/join#id-3-1)를 참고하세요. ## 설정 순서 1. 카카오 담당자에게 인증코드를 받아 애드핏 사업자 가입을 완료합니다. 2. 카카오톡 Android·iOS 매체를 각각 등록합니다. 3. 리워드 또는 전면형 광고단위를 생성합니다. 4. 테스트 광고·대체 광고·민감 카테고리 차단 등 운영에 필요한 옵션을 설정합니다. ## 매체 등록 게임플레이의 광고는 파트너사 게임이 카카오톡 안에서 실행되는 구조이므로 애드핏 매체를 카카오톡으로 등록합니다. 파트너사는 카카오톡 Android·iOS 매체를 각각 등록하고 카카오에 계정 승인을 요청합니다. 경로: **광고관리 > "+ 매체 등록"** ### 1단계: 매체 등록 진입 로그인 후 경로에 따라 **"+ 매체 등록"** 버튼을 클릭합니다. ### 2단계: 매체 정보 입력 필요한 값으로 표시된 항목은 모두 입력해야 합니다. | 필드 | 값 | | --- | --- | | 매체명 | 예: `카카오톡_Android`, `카카오톡_iOS` (구분 가능한 명칭이면 자유) | | 매체 유형 | 카카오톡은 Android · iOS **각각 매체로 등록** | | 스토어 URL (Android) | `https://play.google.com/store/apps/details?id=com.kakao.talk&hl=ko` | | 스토어 URL (iOS) | `https://apps.apple.com/kr/app/카카오톡-kakaotalk/id362057947` | | 매체 카테고리 | `소셜/커뮤니케이션` | 위 정보를 입력하고 \*\*"등록"\*\*을 선택하면 플랫폼에 앱 등록이 완료됩니다. ### 3단계: 화이트리스트 처리 요청 카카오톡 매체로 광고단위를 발급하려면 **파트너사 계정 화이트리스트 처리**가 필요합니다. 매체 등록 후 파트너사 계정 정보를 **게임플레이 파트너센터 > 회사 정보**에 입력하세요. 계정명은 애드핏 내 아래 두 위치에서 확인할 수 있습니다. 계정 승인이 완료되면 카카오가 채널 ID를 발급해 전달합니다. * 플랫폼 좌측 상단 * 계정 관리 > 계정 정보 > 사업자명 계정 승인이나 채널 ID 발급에 문제가 있으면 [카카오 애드핏 문의](https://cs.kakao.com/requests?service=160\&locale=ko)를 이용하세요. ## 광고단위 생성 매체 등록과 화이트리스트 처리가 완료되면 광고 상품별로 광고단위를 생성합니다. 상품마다 입력 항목과 부가 설정이 다르므로 자세한 절차는 각 광고단위 설정 페이지에서 확인하세요. | 광고 상품 | 요약 | 상세 가이드 | | --- | --- | --- | | 리워드 광고단위 | 동영상·이미지 유형, 리워드 지급 조건과 대체 광고 등을 설정합니다. | [리워드 광고단위 설정](/docs/ads/adfit-reward-adunit) | | 전면형 광고단위 | 화면 방향에 맞는 유형과 광고 영역 부가 옵션을 설정합니다. | [전면형 광고단위 설정](/docs/ads/adfit-interstitial-adunit) | ## 광고단위 발급 기준 광고단위는 OS별로 발급해 여러 게임에서 공통으로 사용하거나, 게임별로 각각 발급할 수 있습니다. 파트너사의 광고 운영 방식과 게임별 관리 필요성에 따라 발급 기준을 선택하세요. | 구분 | OS 단위 발급 | 게임 단위 발급 | | --- | --- | --- | | 발급 방식 | Android·iOS 등 OS별로 광고단위를 발급해 여러 게임에서 공통 사용 | 게임별로 광고단위를 각각 발급해 운영 | | 장점 | 여러 게임의 트래픽을 하나의 광고단위로 관리 가능.게임을 출시할 때마다 광고단위를 새로 발급할 필요가 없음 | 게임 특성에 맞는 사용자 대상 광고 노출 가능.게임별로 광고단위를 구분해 운영 가능 | | 고려 사항 | 애드핏에서 게임별 실적을 구분할 수 없음.광고 이슈 발생 시 어느 게임에서 발생한 문제인지 확인하기 어려울 수 있음 | 게임 출시 초기에는 광고 트래픽 학습 시간이 필요함 | | 게임별 매출 확인 | [CP별 리포트 API](/api-sdk/ads/cp-report)에서 CPID별로 조회 | 애드핏에서 광고단위별로 확인 | ## 추가 설정 | 설정 | 확인 시점 | 가이드 | | --- | --- | --- | | 대체 광고·테스트 광고 | 광고단위 개발 테스트와 No Ad 대응이 필요한 경우 | [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test) | | 민감 카테고리 차단 | 카카오톡 Android·iOS 매체 등록 후 | [민감 카테고리 차단 설정](/docs/ads/adfit-sensitive-categories) | ## 기타 * **채널 ID 발급**: SDK와 CP별 리포트 API에 사용할 채널 ID를 발급받아야 합니다. 카카오 담당자에게 문의하세요. * **총 매출 확인·정산**: 애드핏에서 총 매출을 확인하고 정산할 수 있습니다. 자세한 절차는 [정산](/docs/policy/settlement)을 참고하세요. * **미디에이션**: 카카오에서 담당하므로 파트너사가 별도 설정할 항목은 없습니다. * **UX 준수**: 광고 노출 시 다크패턴이 발생하지 않도록 반드시 [광고 UX 가이드](/docs/ads/ux-guideline)를 따릅니다. ## 참고 문서 * [광고 상품 소개](/docs/ads/product-overview): 게임플레이 지원 광고 유형과 상품 시안 * [광고 UX 가이드](/docs/ads/ux-guideline): 광고 노출 UX 정책 * [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test): No Ad 대체 소재와 개발 테스트 방법 * [민감 카테고리 차단 설정](/docs/ads/adfit-sensitive-categories): 카카오톡 매체 차단 카테고리 * [애드핏 광고 SDK](/api-sdk/sdk/adfit) * [CP별 리포트 API](/api-sdk/ads/cp-report) --- --- url: /docs/ads/adfit-reward-adunit.md description: 애드핏 리워드 광고단위 생성과 유형 및 부가 옵션 설정 방법 --- # 리워드 광고단위 설정 애드핏에서 리워드 광고단위를 생성하고 게임 화면 방향과 운영 기준에 맞게 설정하는 방법을 안내합니다. ## 광고단위 생성 경로: **광고관리 > 광고단위 탭 > "+ 광고단위 생성"** ### 1단계: 광고단위 등록 진입 로그인 후 경로에 따라 **"+ 광고단위 생성"** 버튼을 클릭합니다. ### 2단계: 매체 선택 광고단위를 생성할 매체를 선택합니다. ### 3단계: 선택한 매체 정보 확인 매체를 선택하면 선택한 매체의 정보가 표시됩니다. 광고단위를 생성할 매체가 맞는지 확인한 후 **"다음"** 버튼을 선택합니다. ### 4단계: 상품 선택 리워드 광고단위를 생성하기 위해 **"리워드"** 상품을 선택합니다. ### 5단계: 광고단위 정보 입력 상품 선택 후 아래로 스크롤하여 광고단위 생성에 필요한 정보와 설정 옵션 값을 입력합니다. | 항목 | 설정 기준 | | --- | --- | | 광고단위명 | 최대 50자 이내로 입력 | | 유형 선택 | 게임 화면 방향에 맞는 광고 유형 선택 | 리워드 광고는 동영상과 이미지 소재를 모두 제공할 수 있도록 **`동영상 유형`과 `동영상/이미지 유형` 2개를 같이 선택**하세요. 게임 화면 모드에 따라 아래와 같이 2개의 광고 유형을 반드시 같이 선택해야 합니다. | 게임 화면 방향 | 필수 선택 유형 | | --- | --- | | 세로형 | `리워드_동영상`, `리워드_동영상/이미지` | | 가로형 | `리워드_동영상_가로형`, `리워드_동영상/이미지_가로형` | ### 6단계: 최소 시청시간 설정 리워드 지급이 가능한 최소 시청시간 조건을 설정합니다. **"미설정"** 시 전체 동영상 광고를 시청해야 사용자가 리워드를 받을 수 있습니다. **"설정"** 시 5~60초 사이의 값을 입력할 수 있습니다. 일부 동영상 광고의 길이가 설정 시간보다 짧은 경우에는 동영상 시청을 완료하면 조건을 충족한 것으로 간주합니다. ### 7단계: 닫기 버튼 문구 설정 동영상 광고 시청 후 광고 화면을 닫는 버튼의 문구를 설정합니다. **"미설정"** 시 기본 문구인 \*\*"리워드 받기"\*\*가 표시됩니다. **"설정"** 시 한글과 공백을 포함해 최대 6자까지 입력할 수 있습니다. ### 8단계: 리워드 콜백 URL 설정 리워드 지급 요청 이벤트(`reward_eligible`)를 서버로 수신하려는 경우 사용합니다. **"미설정"** 시 기본 광고 지표는 애드핏 **"보고서"** 메뉴에서 확인할 수 있습니다. **"설정"** 시 입력한 서버 URL로 이벤트를 수신할 수 있습니다. ### 9단계: 대체 광고 설정 애드핏 심사가 완료된 매체에서 실소재가 응답되지 않는 경우(No Ad), 광고단위에 등록한 대체 광고를 노출하는 기능입니다. 설정 순서: **대체 광고 "설정" 선택 > "소재 등록" 선택 > 동영상 파일과 필요한 값 입력 > 등록 > 저장 > 수정 정보 저장** 대체 광고 소재의 제작 기준과 등록 방법은 [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test)을 참고하세요. ### 10단계: 실소재 노출 중단 대체 광고가 등록된 상태에서 실소재 대신 대체 광고를 노출해야 할 때 사용합니다. 광고단위 출시 전 개발 테스트에서 사용할 수 있습니다. 1. **대체 광고**: "설정" 선택 > "소재 등록" 선택 > 동영상 파일과 필요한 값 입력 > 등록 > 저장 2. **실소재 노출 중단**: "설정" 선택 > "확인" 선택 > 수정 정보 저장 ::: warning 주의사항 실소재 노출 중단을 설정하면 실광고를 정상적으로 노출할 수 있는 상태에서도 대체 광고가 표시됩니다. 개발 테스트가 끝난 후 같은 광고단위로 출시하려면 반드시 **미설정**으로 변경해야 합니다. ::: ### 11단계: 노출 빈도 설정 동일 사용자에게 하루(00~24시) 동안 광고를 노출할 최대 횟수를 설정합니다. **"미설정"** 시 횟수 제한 없이 노출되며, **"설정"** 시 1~5회 범위에서 지정할 수 있습니다. 모든 입력 값과 옵션 값을 점검한 후 **"다음"** 버튼을 선택하면 광고단위가 발급됩니다. ## 광고단위 삭제 경로: **광고관리 > 광고단위 탭 > 삭제할 광고단위명 선택 > "광고단위 정보" 우측 버튼 > 삭제** 삭제 확인 모달의 주의 사항을 확인한 뒤 \*\*"확인"\*\*을 선택하면 광고단위가 삭제됩니다. ## 참고 문서 * [애드핏 설정](/docs/ads/iaa-options): 매체 등록과 광고단위 생성 안내 * [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test): 대체 광고 등록과 개발 테스트 방법 * [애드핏 광고 SDK](/api-sdk/sdk/adfit) --- --- url: /docs/ads/adfit-interstitial-adunit.md description: 애드핏 전면형 광고단위 생성과 유형 및 부가 옵션 설정 방법 --- # 전면형 광고단위 설정 애드핏에서 전면형 광고단위를 생성하고 게임 화면 방향과 운영 기준에 맞게 설정하는 방법을 안내합니다. ## 광고단위 생성 경로: **광고관리 > 광고단위 탭 > "+ 광고단위 생성" > 매체 선택 > 상품 선택** ### 1단계: 상품 선택 전면형 광고단위를 생성하기 위해 **"전면형"** 상품을 선택합니다. ### 2단계: 광고단위 정보 입력 상품 선택 후 아래로 스크롤하여 광고단위 생성에 필요한 정보와 설정 옵션 값을 입력합니다. | 항목 | 설정 기준 | | --- | --- | | 광고단위명 | 최대 50자 이내로 입력 | | 유형 선택 | `전면형_이미지` 선택 | ### 3단계: 광고영역 테두리 광고영역 테두리에서 **"설정"** 옵션을 선택하면 입력란이 활성화되고 기본값으로 **"색상: 없음"** 값이 표시됩니다. 색상표에서 원하는 색상을 선택하거나 맞춤 색상란에 `#000000` 형식의 Hex 색상 코드를 입력할 수 있습니다. ### 4단계: 실소재 노출 중단 대체 광고가 등록된 상태에서 실소재 대신 애드핏 기본 광고를 노출해야 할 때 사용합니다. 광고단위 출시 전 개발 테스트에서 사용할 수 있습니다. 설정 순서: **실소재 노출 중단 "설정" 선택 > "확인" 선택 > 수정 정보 저장** ::: warning 주의사항 실소재 노출 중단을 설정하면 실광고를 정상적으로 노출할 수 있는 상태에서도 애드핏 기본 광고가 표시됩니다. 개발 테스트가 끝난 후 같은 광고단위로 출시하려면 설정 상태를 반드시 **"미설정"** 값으로 변경해야 합니다. ::: ### 5단계: 특정 소재 타입 허용 이미지가 없는 텍스트 단독 소재도 수신하려면 체크박스를 선택합니다. 텍스트 단독 소재를 수신하지 않으려면 체크박스를 선택 해제합니다. 모든 입력 값과 옵션 값을 점검한 후 **"다음"** 버튼을 선택하면 광고단위가 발급됩니다. ## 광고단위 삭제 경로: **광고관리 > 광고단위 탭 > 삭제할 광고단위명 선택 > "광고단위 정보" 우측 버튼 > 삭제** 삭제 확인 모달의 주의 사항을 확인한 뒤 **"확인"** 버튼을 선택하면 광고단위가 삭제됩니다. ## 참고 문서 * [애드핏 설정](/docs/ads/iaa-options): 매체 등록과 광고단위 생성 안내 * [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test): 개발 테스트 방법 * [애드핏 광고 SDK](/api-sdk/sdk/adfit) --- --- url: /docs/ads/adfit-fallback-test.md description: 애드핏 리워드 대체 광고 등록과 실소재 노출 중단을 이용한 개발 테스트 방법 --- # 대체·테스트 광고 설정 애드핏 광고 호출에 실소재가 응답되지 않는 경우(No Ad)를 대비해 대체 광고를 등록하고, 라이브 전에 테스트 광고를 확인하는 방법을 안내합니다. 리워드와 전면형은 테스트 소재 제공 방식이 다르므로 광고 유형에 맞는 절차를 적용하세요. ## 설정 방식 비교 | 상황 | 리워드 | 전면형 | | --- | --- | --- | | No Ad 대응 | 광고단위에 등록한 대체 광고 노출 | 애드핏 기본 광고 노출 | | 승인 후 개발 테스트 | 대체 광고 등록 후 `실 소재 노출 중단` 설정 | `실 소재 노출 중단` 설정 | | 매체 심사 승인 전 테스트 | 신규 광고단위를 호출하면 애드핏 기본 소재 노출 | 신규 광고단위를 호출하면 애드핏 기본 소재 노출 | | 테스트 종료 | `실 소재 노출 중단`을 `미설정`으로 변경 | `실 소재 노출 중단`을 `미설정`으로 변경 | ::: warning 주의사항 `실 소재 노출 중단`을 설정하면 정상적으로 실광고를 제공할 수 있는 상태에서도 테스트 소재만 노출되며 적립금이 발생하지 않습니다. 설정 변경 반영에는 최대 2시간이 걸릴 수 있습니다. 운영 전 반드시 `미설정` 상태를 확인하세요. ::: ## 리워드 대체 광고 등록 경로: **애드핏 로그인 > 광고관리 > 광고단위 > 대상 광고단위 선택 > 광고단위 정보 수정** 1. `대체 광고`에서 `설정`을 선택합니다. 2. `소재 등록`을 선택합니다. 3. 동영상 파일·링크 URL·소재 설명을 입력합니다. 4. 소재를 등록하고 광고단위 수정 정보를 저장합니다. ## 대체 광고 소재 제작 광고 UI의 닫기·음소거·리워드·바로가기 버튼은 애드핏에서 제공합니다. 버튼을 동영상 파일 안에 포함하지 말고 순수 동영상 소재만 제작하세요. | 구성 요소 | 적용 | 기준 | | --- | --- | --- | | 동영상 파일 | 필수 | MP4 · 최대 30 MB · 15~60초 | | 권장 비율 | 권장 | `9:16` · `720 × 1280` 또는 `1080 × 1920` | | 지원 비율 | 지원 | `16:9` · `1280 × 720` 또는 `1920 × 1080` | | 미지원 비율 | 미지원 | `1:1`, `4:3`, `21:9` 등 | | 랜딩 URL | 필수 | `http://` 또는 `https://` 포함 · 최대 1000자 | | 소재 설명 | 필수 | 소재를 직관적으로 설명하는 문구. 시각장애인용 음성 안내 정보로 사용 | ### 9:16 소재 Safe Zone * 텍스트·로고·고지문구·메인 오브젝트는 상·하 `89px`, 좌·우 `47px` 영역을 피해 중앙에 배치합니다. * 다른 UI와 겹치지 않도록 하려면 상단 `279px`, 하단 `438px`, 좌·우 `47px` 영역에 주요 텍스트와 메인 오브젝트를 배치하지 않는 것을 권장합니다. ## 승인 후 테스트 광고 확인 ### 리워드 광고 1. 대체 광고 소재를 등록하고 저장합니다. 2. `실 소재 노출 중단`에서 `설정`을 선택합니다. 3. 확인 안내를 읽고 광고단위 수정 정보를 저장합니다. 4. 게임에서 해당 광고단위를 호출해 대체 광고와 이벤트 동작을 확인합니다. 5. 테스트 종료 후 `실 소재 노출 중단`을 `미설정`으로 변경합니다. ### 전면형 광고 1. 대상 광고단위의 `실 소재 노출 중단`에서 `설정`을 선택합니다. 2. 확인 안내를 읽고 광고단위 수정 정보를 저장합니다. 3. 게임에서 해당 광고단위를 호출해 애드핏 기본 광고와 이벤트 동작을 확인합니다. 4. 테스트 종료 후 `실 소재 노출 중단`을 `미설정`으로 변경합니다. ## 매체 심사 승인 전 테스트 신규 가입자는 매체 심사 승인 후에만 생성한 광고단위로 실소재를 운영할 수 있습니다. 심사 승인 전에 리워드 또는 전면형 광고단위를 테스트하려면 신규 광고단위를 게임에 적용해 호출하세요. 애드핏 기본 소재가 노출됩니다. ## 확인 사항 * \[ ] 리워드 대체 광고의 파일·URL·소재 설명을 모두 등록했는지 확인 * \[ ] 대체 광고 영상 안에 애드핏 제공 버튼을 직접 그리지 않았는지 확인 * \[ ] 게임 화면 방향과 소재 비율이 맞는지 확인 * \[ ] 테스트 중 실소재 대신 대체 광고 또는 애드핏 기본 광고가 노출되는지 확인 * \[ ] 운영 전 `실 소재 노출 중단`을 `미설정`으로 되돌렸는지 확인 ## 참고 문서 * [애드핏 설정](/docs/ads/iaa-options): 매체 등록과 광고단위 발급 * [광고 UX 가이드](/docs/ads/ux-guideline): 광고 노출·보상·실패 처리 기준 * [애드핏 광고 SDK](/api-sdk/sdk/adfit): 광고 호출과 이벤트 처리 * [심사 체크리스트](/docs/checklist/review-checklist): 광고 테스트 확인 항목 --- --- url: /docs/ads/adfit-sensitive-categories.md description: 카카오톡 Android·iOS 애드핏 매체에서 차단해야 하는 민감 광고 카테고리 --- # 민감 카테고리 차단 설정 카카오톡 게임플레이에 사용하는 애드핏 매체에서는 서비스 환경에 맞지 않는 민감 광고 카테고리를 차단해야 합니다. Android와 iOS 매체에 동일한 차단 기준을 적용하세요. ## 설정 경로 경로: **애드핏 > 게재 설정 > 차단 설정** 애드핏 관리자에서 위 경로로 이동해 민감 카테고리를 차단할 수 있습니다. ## 적용 대상 | 매체 | 적용 | | --- | --- | | `카카오톡_Android` | 필수 | | `카카오톡_iOS` | 필수 | ## 차단 카테고리 | 카테고리 | 포함 광고 예시 | | --- | --- | | 도박/사행성 | 카지노·로또·복권·스포츠토토 | | 종교 | 기독교·불교·천주교 등 | | 점술/무속 | 사주·운세·팔자·작명 | | 성인 | 성인용품·성인용 콘텐츠·성인 구인구직 | | 비뇨/성/약물 관련 의료 | 비뇨기과·산부인과·대장항문과 관련 광고 | | 즉석만남 | 즉석채팅·영상채팅·성인채팅 | | P2P/웹하드/비표준 콘텐츠 | 콘텐츠 다운로드·공유 사이트 | | 산업 기타 | 다단계·네트워크 마케팅·흥신소 | | 정치/법/정부 | 정당·선거 관련 컨설팅 | | 담배 | 허가받은 금연보조제·관련 구성품·금연필터 | | 고위험물품 | 수련용·식도용·레저용 도검류, 일반 폭죽, 호신용 총기류 | | 다단계 | 네트워크 마케팅 | | 중고차 | 중고차 광고 | | 대부업 | 대부업 광고 | ## 확인 사항 * \[ ] Android·iOS 매체를 각각 확인했는지 확인 * \[ ] 위 14개 카테고리가 모두 차단 상태인지 확인 * \[ ] 신규 매체를 등록하거나 설정을 변경한 경우 차단 상태를 다시 확인 ## 참고 문서 * [애드핏 설정](/docs/ads/iaa-options): 카카오톡 매체 등록과 광고단위 발급 * [대체·테스트 광고 설정](/docs/ads/adfit-fallback-test): 개발 테스트와 No Ad 대응 * [광고 UX 가이드](/docs/ads/ux-guideline): 광고 노출 정책 * [심사 체크리스트](/docs/checklist/review-checklist): 광고 적용 확인 항목 --- --- url: /docs/policy/overview.md description: 카카오톡 게임플레이 운영 원칙 안내 --- # 운영 원칙 게임플레이에 입점한 게임의 안정적인 운영과 이용자 보호를 위해 카카오와 파트너사가 함께 준수해야 하는 기준을 고지합니다. ## 정책 변경 카카오는 서비스 운영 환경, 기술 변화, 법령 개정에 따라 이 정책을 수정할 수 있습니다. 정책 변경 시에는 원칙적으로 사전에 파트너사에 안내합니다. 다만 아래 사유가 발생하는 경우 즉시 적용할 수 있습니다. * 법령 또는 규제기관 지침이 변경된 경우 * 보안·개인정보 보호를 위한 긴급 조치가 필요한 경우 * 서비스 안정성 확보를 위한 긴급 조치가 필요한 경우 * 카카오톡 또는 게임플레이 플랫폼 구조가 변경된 경우 ## 고지 방식 카카오는 정책의 제정·변경·폐지 시 파트너사에 사전 안내하는 것을 원칙으로 합니다. 변경 내용은 파트너사별 오픈채팅방 또는 이메일을 통해 공유합니다. ## 위반 처리 파트너사의 게임이 정책을 준수하지 않는 것으로 확인되면 카카오는 파트너사에 개선을 요청합니다. 요청을 받은 파트너사는 합리적인 기간 내에 필요한 조치를 완료해야 합니다. 정책 위반이 지속되거나 이용자 보호 또는 서비스 안정성에 중대한 영향이 있다고 판단되는 경우, 카카오는 파트너사와 협의 후 해당 게임의 노출·기능 제한 등 필요한 조치를 취할 수 있습니다. 법령 위반, 개인정보 침해, 보안 사고 등 긴급 상황에서는 이용자 보호를 우선해 선조치 후 파트너사와 협의합니다. ## 관련 문서 * [입점 정책](/docs/policy/onboarding) * [데이터 보호 정책](/docs/policy/implementation) * [출시 및 업데이트 정책](/docs/policy/launch) * [서비스 운영](/docs/policy/operations) --- --- url: /docs/policy/onboarding.md description: 게임플레이 입점 정책 안내 --- # 입점 정책 ## 입점 대상 및 조건 카카오톡 내에서 실행 가능한 HTML5 기반 게임이 입점할 수 있습니다. 입점 신청 시 아래 요건을 모두 충족해야 합니다. * 게임 이용 등급은 전체이용가 또는 12세이용가이어야 합니다. * 게임의 핵심 콘텐츠와 기능이 구현되어 있어야 합니다. * 안정적인 서비스 운영이 가능해야 합니다. * 관련 법령 및 등급분류 기준을 준수해야 합니다. * 게임 제공에 필요한 권리 및 운영 권한을 보유해야 합니다. * 게임플레이 운영 정책 및 기술 가이드를 준수해야 합니다. ## 입점 제한 아래에 해당하는 게임은 입점이 제한되거나 보류될 수 있습니다. * 법령 또는 사회적 통념에 위배되는 게임 * 기술적 안정성이 부족한 게임 * 이용자에게 혼란 또는 피해를 줄 우려가 있는 게임 * 제3자의 권리를 침해하는 게임 * 게임플레이 서비스에 적합하지 않다고 판단되는 게임 ## 입점 신청 시 제출 자료 파트너사는 카카오가 지정하는 절차에 따라 입점을 신청합니다. 신청 시 아래 자료를 제출해야 합니다. * 게임 소개 자료 * 실행 가능한 빌드 또는 플레이 영상 * 게임 장르 및 주요 기능 * 수익 모델 * 광고 적용 계획 * 고객지원 정보 * 이용등급 정보 * 카카오가 별도 요청하는 자료 ## 입점 심사 카카오는 제출 자료를 바탕으로 게임성, 안정성, 사업성, 서비스 지속 가능성, 카카오톡과의 적합성을 종합 검토하여 입점 여부를 결정합니다. 결과의 세부 내용은 공개하지 않을 수 있습니다. ## 관련 문서 * [입점 안내](/docs/checklist/start-guide) * [심사 가이드](/docs/checklist/review-guide) --- --- url: /docs/policy/launch.md description: 신규 게임의 출시 심사와 출시 게임의 업데이트 심사 기준 --- # 출시 및 업데이트 정책 ## 출시 심사 신규 게임은 **매주 화요일 오전 11시** 출시를 원칙으로 합니다. 아래 일정은 출시 이력이 있는 파트너사의 신규 게임에 적용하는 기본 일정이며, 실제 출시 주차는 게임별로 협의합니다. 파트너사의 첫 게임은 최초 연동 심사가 포함되므로 카카오와 별도 일정을 협의합니다. 자세한 심사 범위와 요청 방법은 [심사 가이드](/docs/checklist/review-guide)를 참고하세요. | 단계 | 담당 | 일정 | 비고 | | --- | --- | --- | --- | | 파트너사 자체 점검 | 파트너사 | 요청 전 | 게임플레이 파트너센터에 게임 정보를 모두 입력하고 개발 연동에 대한 자체 점검을 완료합니다. | | 출시 심사 요청 | 파트너사 | 상시 | 파트너센터에서 게임 정보와 개발 연동 자체 점검 결과를 확인한 뒤 출시 심사를 요청합니다. | | 심사 진행 | 카카오 | 매주 수·목요일 | 매주 화요일까지 접수된 게임을 요청 순서대로 심사합니다.심사를 요청한 게임 수에 따라 일정이 더 소요될 수 있습니다. | | 심사 결과 확인 | 파트너사 | 심사 완료 시 | 파트너센터의 심사 현황에서 승인·반려 결과와 항목별 반려 사유를 확인합니다. | | 수정 및 재심사 요청 | 파트너사 | 상시 | 반려 항목을 수정한 뒤 파트너센터에서 다시 출시 심사를 요청합니다. | | 재심사 진행 | 카카오 | 매주 수·목요일 | 수정 사항을 다시 심사하며 요청한 게임 수에 따라 일정이 더 소요될 수 있습니다. | | 심사 승인 안내 | 카카오 | 매주 목요일 오후 | 추가 수정 사항이 없으면 심사 승인을 안내합니다. | | 게임 출시 | 카카오 | 화요일 오전 11시 | 실제 출시 주차는 게임별로 별도 협의합니다. | ## 심사가 필요하지 않은 업데이트 게임 콘텐츠, 밸런스, 버그 수정 등 카카오 연동 기능에 영향을 주지 않는 업데이트입니다. 별도 심사 없이 자유롭게 배포할 수 있으며 업데이트 내용과 배포 시점을 업데이트 노트에 작성해 카카오에 공유합니다. ## 업데이트 심사 출시된 게임의 게임 정보 또는 개발 연동을 변경할 때 요청하는 심사입니다. 변경 대상에 맞는 정보를 게임플레이 파트너센터에 입력하고 업데이트 심사를 요청합니다. ### 게임 정보 변경 게임 이름·설명문구·아이콘·프로모션 이미지·게임 링크·이용등급·장르·랭킹 설정 등 파트너센터에서 관리하는 게임 정보를 수정합니다. 승인된 정보만 게임플레이 서비스에 반영됩니다. ### 개발 연동 변경 카카오싱크·게임웹뷰·공유·광고 SDK·액션데이터·Tiara Web SDK를 통한 게임 로그 수집·전송 등 변경한 연동 항목을 선택하고 항목별 수정 사항과 자체 점검 결과를 입력합니다. 테스트 게임 URL이 있다면 함께 입력하고, 업데이트 심사를 승인받은 뒤 변경 사항을 배포합니다. | 단계 | 담당 | 일정 | 비고 | | --- | --- | --- | --- | | 업데이트 심사 요청 | 파트너사 | 상시 | 게임 정보를 수정하거나 개발 연동 변경 항목과 항목별 수정 사항·자체 점검 결과·테스트 URL을 입력한 뒤 요청합니다. | | 심사 진행 | 카카오 | 매주 수·목요일 | 매주 화요일까지 접수된 요청을 순서대로 심사합니다. | | 심사 결과 확인 | 파트너사 | 심사 완료 시 | 파트너센터에서 승인·반려 결과와 항목별 반려 사유를 확인합니다. | | 수정 및 재심사 요청 | 파트너사 | 상시 | 반려 사유를 반영한 뒤 파트너센터에서 다시 업데이트 심사를 요청합니다. | 게임 정보와 개발 연동을 함께 변경한다면 하나의 업데이트 심사에 변경 내용을 모두 입력합니다. ## 관련 문서 * [심사 가이드](/docs/checklist/review-guide) * [심사 체크리스트](/docs/checklist/review-checklist) --- --- url: /docs/policy/implementation.md description: 기술 구현, 개인정보·보안, 이용자 데이터 관리에 관한 파트너사 준수 기준 정책 --- # 데이터 보호 정책 > \[!WARNING] > 이 페이지의 일부 항목은 카카오 내부 업데이트 중입니다. 확정 전까지 세부 기준은 카카오 담당자에게 확인하세요. ## 기술 구현 파트너사는 카카오가 제공하는 API 및 기술 가이드를 준수하여 게임을 구현해야 합니다. 게임은 카카오톡 실행 환경에서 정상 동작해야 하며 아래 사항을 준수해야 합니다. * 카카오톡 이용 경험을 저해하지 않아야 합니다. * 비정상적인 리소스 사용을 유발하지 않아야 합니다. * 주요 기능이 정상 동작해야 합니다. * 오류 발생 시 적절한 예외 처리를 제공해야 합니다. 카카오는 서비스 안정성을 위해 기술적 개선이 필요하다고 판단하는 경우 파트너사에 수정을 요청할 수 있으며, 파트너사는 이에 협조해야 합니다. ## 개인정보 및 보안 파트너사는 개인정보보호법 및 관련 법령을 준수해야 합니다. 이용자의 개인정보를 수집하는 경우, 수집 주체가 파트너사임을 이용자에게 명확히 고지해야 하며 아래 사항을 반드시 준수해야 합니다. * 개인정보는 최소한으로 수집합니다. * 수집 목적 범위 내에서만 이용합니다. * 저장·전송 시 적절한 보안 조치를 적용합니다. * 접근 권한을 최소한으로 관리합니다. * 침해 예방을 위한 관리적·기술적 보호 조치를 적용합니다. * 법령에 따른 보관 의무를 준수합니다. * 이용자의 삭제 요청 또는 이용 목적 종료 시 개인정보를 즉시 파기합니다. 개인정보 유출 또는 침해 사고가 발생하거나 의심되는 경우, 즉시 카카오에 통지하고 필요한 조치를 수행해야 합니다. ## 이용자 데이터 활용 범위 카카오가 제공하는 이용자 식별정보, 게임 이용정보, 순위 정보, 플레이 기록 등은 게임플레이 서비스 제공·운영 목적으로만 사용할 수 있습니다. 아래 목적으로는 활용할 수 없습니다. * 게임플레이 외 서비스 운영 * 별도 마케팅 또는 광고 집행 * 제3자 제공 또는 판매 * 데이터 양도 또는 임대 * 카카오가 승인하지 않은 사업 목적 활용 ## 데이터 연계 제한 게임플레이를 통해 확보한 이용자 데이터를 외부 플랫폼·서비스의 데이터와 결합하여 사용할 수 없습니다. 게임플레이 이용자를 외부 플랫폼으로 유도하거나 식별·분류하기 위한 목적으로 데이터를 활용하는 것도 금지됩니다. 카카오의 사전 승인 없이 게임플레이 이용자 데이터와 외부 서비스 데이터를 연계한 분석·운영·마케팅 활동은 허용되지 않습니다. ## 이용자 식별정보 관리 게임플레이 이용자는 카카오가 제공하는 식별 체계를 기반으로 게임을 이용합니다. 파트너사는 카카오가 제공한 식별정보를 게임 서비스 제공 목적 범위 내에서만 사용해야 합니다. 식별정보를 제3자에게 제공하거나 별도 서비스 가입, 마케팅·광고 목적으로 활용하는 것은 금지됩니다. ## 데이터 보관 및 파기 이용 목적이 종료되거나 계약이 종료되면, 법령에 따라 보관이 필요한 정보를 제외하고 관련 데이터를 즉시 파기해야 합니다. 카카오는 파기 여부 확인을 위해 필요한 자료 제출 또는 확인 절차를 요청할 수 있으며, 파트너사는 이에 협조해야 합니다. ## 관련 문서 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal) --- --- url: /docs/policy/operations.md description: 게임 노출, 업데이트, CS, 장애·점검, 지표 모니터링, 광고 운영, 서비스 종료에 관한 파트너사 준수 기준 --- # 서비스 운영 ## 게임 노출 카카오는 게임플레이 홈의 이용자 경험을 위해 플레이 지표, 이용자 반응, 서비스 품질 등 다양한 요소를 종합적으로 고려하여 노출 게임을 선정할 수 있습니다. 노출 기준의 세부 내용은 공개하지 않을 수 있으며, 카카오의 판단에 따라 노출 순서와 방식은 변경될 수 있습니다. ## 게임 업데이트 파트너사는 게임 콘텐츠 업데이트를 자율적으로 진행할 수 있습니다. 단, 업데이트 내용이 게임플레이 운영 정책 및 플랫폼 기술 기준을 준수해야 합니다. 업데이트를 진행하기 전에 변경 내용과 배포 일정을 카카오에 사전 고지해야 합니다. 카카오 연동 범위에 영향을 주는 업데이트는 사전 심사가 필요합니다. 업데이트 유형별 심사 절차는 [출시 및 업데이트 정책](/docs/policy/launch)을 참고하세요. ## CS 운영 파트너사는 게임 내 이용자 문의를 처리할 고객지원 채널을 직접 운영해야 합니다. 게임 관련 CS는 파트너사가 직접 응대합니다. 이용자로부터 게임플레이 홈, 계정 등 카카오 플랫폼과 관련된 문의가 접수된 경우 카카오로 이관합니다. 고객지원 운영 시 아래 기준을 준수합니다. * 게임 내 고객센터 진입점을 제공합니다. 게임웹뷰 공통 헤더를 통해 제공하는 것이 권장됩니다. * 개인정보 처리 관련 문의는 파트너사 개인정보처리방침에 따라 처리합니다. 카카오가 이용자 피해 사례 또는 반복 민원을 파악한 경우 파트너사에 해당 내용을 전달하고 개선을 요청할 수 있습니다. ## 장애 및 점검 게임 장애 또는 점검이 예정된 경우, 일정을 사전에 카카오에 고지하고 진행합니다. 사전 고지가 어려운 긴급 상황에서는 인지하는 즉시 카카오에 공유하고 복구 일정을 안내합니다. ## 광고 운영 파트너사는 게임플레이 내 광고 운영 시 [광고 UX 가이드](/docs/ads/ux-guideline)를 반드시 준수해야 합니다. 아래는 주요 금지 사항입니다. * 이용자의 명확한 선택 없이 광고를 자동 실행하거나 강제 노출하는 방식 * 광고를 서비스 기능처럼 위장하는 UI 구성 * 동일 동선에서 광고를 반복 호출하거나 시청을 강요하는 방식 * 광고 수익을 목적으로 게임 진행을 의도적으로 방해하는 설계 광고 정책 위반이 확인되면 카카오는 수정을 요청하며, 시정되지 않을 경우 광고 기능이 제한될 수 있습니다. ## 서비스 종료 파트너사는 카카오에 서비스 종료 의사를 전달하고 합의를 완료한 후 종료를 진행할 수 있습니다. 카카오와 합의 전에는 종료 일정이 외부에 공개되지 않도록 유의해주시기 바랍니다. 서비스 종료 시 아래 사항을 반드시 이행해야 합니다. * 종료일 최소 **30일 전**에 종료 사유와 일정을 이용자에게 공지합니다. * 이용자의 개인정보(카카오톡 닉네임, 프로필 등)를 게임 서버 등에 저장한 경우, 서비스 종료 후 해당 정보를 파기하고 대표자 명의의 파기 확인서를 카카오에 제출합니다. * 게임플레이 노출 제거, 게임 서버 차단, 카카오 API 차단 등 종료 처리는 카카오와 별도 협의한 일정에 따라 진행합니다. ## 관련 문서 * [출시 및 업데이트 정책](/docs/policy/launch) * [광고 UX 가이드](/docs/ads/ux-guideline) * [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay) > 고객센터 진입점 구현 * [액션데이터 API](/api-sdk/data/action-data) --- --- url: /docs/policy/pr.md description: 게임플레이 관련 보도자료, 기사, 인터뷰 등 대외 커뮤니케이션 가이드 --- # PR 및 대외 커뮤니케이션 파트너사가 게임플레이와 관련된 내용을 포함한 보도자료, 기사, 인터뷰 등 대외 커뮤니케이션 자료를 배포하고자 하는 경우 사전에 카카오에 공유해 주세요. 카카오와의 협업 사실을 포함한 대외 커뮤니케이션은 게임플레이 입점 계약서 체결 이후부터 가능합니다. ## 서비스명 표기 대외 커뮤니케이션 시 서비스명은 **"카카오톡 게임플레이"** 또는 **"게임플레이"** 로 표기합니다. | 권장 표현 (O) | 자제할 표현 (X) | | --- | --- | | "카카오톡 게임플레이를 통해 출시합니다." | "카카오 게임하기에 출시합니다." | | "게임플레이 플랫폼을 통해 즐길 수 있습니다." | "카카오톡에 입점합니다." / "카카오톡과 제휴를 맺고…" | ## 지표 및 현황 표기 자사 게임에 대해 사실이 확인된 내용만 사용합니다. 게임플레이 내 다른 게임과의 비교, 불확실한 지표, "최초" · "최고" · "1위" 등의 표현은 반드시 카카오에 사실 확인 후 사용해 주세요. 확인되지 않은 경우 해당 표현은 자제해 주세요. --- --- url: /docs/policy/settlement.md description: 광고 매출 수익 배분 및 정산 절차 --- # 정산 게임플레이 내 광고를 통해 발생한 매출은 카카오의 광고 플랫폼 [애드핏](https://adfit.kakao.com/dashboard)을 통해 정산할 수 있습니다. ## 정산 절차 매출이 발생한 월을 M월이라 할 때, 정산은 아래 일정에 따라 진행됩니다. 지급일이 휴일인 경우 직전 영업일에 지급합니다. | 시점 | 내용 | | --- | --- | | M+1월 말일 | 파트너사가 [애드핏](https://adfit.kakao.com/dashboard)에서 직접 적립금 지급 요청 | | M+1월 말일 | 파트너사가 월별 매출액·순광고매출액·카카오 배분 금액 산정 내역을 카카오에 전달 | | M+2월 10일 | 카카오가 수익배분 금액에 대한 세금계산서 발행 (M+1월 말일자 기준) | | M+2월 말일 | 파트너사가 세금계산서 금액을 카카오 지정 계좌에 현금 지급 | ## 정산 이의 제기 카카오가 제출된 정산 내역에 이의를 제기하는 경우 양사가 협의를 통해 해결합니다. 이의 제기일로부터 5영업일 이내에 합의가 이루어지지 않을 경우, 파트너사가 제출한 정산 내역을 기준으로 대금 지급을 진행합니다. 이후 차액이 확인되면 확인된 익월 대금 지급에 반영합니다. --- --- 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) --- --- url: /api-sdk/sdk.md description: 게임플레이 JS SDK 와 개별 SDK 직접 연동 중 하나를 고르는 기준과 마이그레이션 안내 --- # SDK 연동 방식 선택 게임플레이 연동에는 두 가지 방식이 있습니다. **둘 중 하나만 고릅니다.** ## 연동방식 선택 기준 | 상황 | 방식 | | --- | --- | | 이제 연동을 시작합니다 | [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/) | | 이미 개별 SDK 로 연동을 마쳤습니다 | 당분간 그대로 두고, 여유가 생기면 게임플레이 JS SDK 로 옮깁니다 | 신규 연동에는 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)를 권장합니다. 게임웹뷰 브리지·카카오 로그인·공유·광고를 하나의 `Gameplay` 객체로 다루므로 개별 SDK 의 등록 절차와 버전을 각각 따라갈 필요가 없습니다. 게임플레이 JS SDK 는 게임플레이 서비스보다 늦게 나왔습니다. 그래서 이미 개별 SDK 로 연동을 마친 파트너사를 위해 [개별 SDK 문서](#개별-sdk-직접-연동)를 당분간 유지합니다. 다만 장기적으로는 게임플레이 JS SDK 로 옮기는 것을 방향으로 삼고 있습니다. ## 동시 구성 지양 안내 두 방식을 함께 구성하는 것은 권장하지 않습니다. 게임플레이 JS SDK 는 내부에서 `window.kakaotalkGamePlay`·`window.Kakao`·`window.kakaoAdFit` 을 다루므로, 게임 코드가 같은 SDK 객체를 따로 로드하면 같은 객체가 두 번 올라가 초기화 순서에 따라 설정이 덮이거나 콜백이 중복 호출될 수 있습니다. 마이그레이션 중이라면 게임 코드에서 개별 SDK 의 ` ``` `{버전}` 과 `integrity` 는 [다운로드](/api-sdk/sdk/gameplay-js/download)에서 확인하세요. **`integrity` 는 그 버전의 값과 일치해야 합니다.** 버전만 올리고 `integrity` 를 그대로 두면 브라우저가 무결성 검증에 실패해 SDK 가 로드되지 않습니다. ## TypeScript 같은 경로의 `gameplay-sdk.d.ts` 를 내려받아 프로젝트에 두고 `tsconfig.json` 의 `include` 에 추가하면, `import` 없이 `Gameplay` 객체에 타입이 적용됩니다. ```json { "include": ["src/**/*", "./gameplay-sdk.d.ts"] } ``` 이 파일 하나에 SDK 가 노출하는 모든 타입과 `Gameplay` 전역 선언이 함께 들어 있습니다. 별도 `@types/...` 패키지는 없습니다. 자세한 사용법은 [다운로드: TypeScript](/api-sdk/sdk/gameplay-js/download#typescript)를 참고하세요. ## 초기화 ```ts await Gameplay.init({ gameName: '게임 이름', gameCode: 'sample-game', appId: 1234567, clientKey: 'YOUR_JAVASCRIPT_KEY', }); ``` | 옵션 | 타입 | 설명 | | --- | --- | --- | | `gameName` | `string` | 필수게임 이름. 닫기 버튼을 눌렀을 때 SDK 가 띄우는 [이탈 확인 팝업](/api-sdk/sdk/gameplay-js/ui#나가기-버튼)의 제목입니다 | | `gameCode` | `string` | 필수파트너사가 정해 게임플레이 파트너센터에 등록한 게임 코드. [단축 URL 생성](/api-sdk/share/short-url)의 `gameCode` · 광고 CPID 와 같은 값입니다 | | `appId` | `number` | 필수카카오디벨로퍼스 [앱 ID](https://developers.kakao.com/docs/ko/app-setting/app#app-id) | | `clientKey` | `string` | 카카오디벨로퍼스가 발급하는 JavaScript 키. 카카오 로그인·공유를 쓰는 게임만 지정합니다 | `tiara` · `ad` · `webview` · `ui` 를 포함한 전체 옵션은 [전체 메서드](/api-sdk/sdk/gameplay-js/reference#init-options)에 있습니다. ::: danger clientKey 를 쓰면 try/catch 로 감쌉니다 `clientKey` 를 지정했거나 `window.Kakao` 가 이미 로드되어 있으면 `init()` 이 카카오 JS SDK 를 로드합니다. 이 로드가 실패하거나 응답이 없으면 `init()` 이 `KAKAO_NOT_AVAILABLE` 로 reject 됩니다. 감싸지 않으면 광고 차단기·CSP 차단·네트워크 지연 상황에서 unhandled rejection 이 됩니다. ::: ## 게임 로그 게임 로그(Tiara)는 **SDK 가 대신 보냅니다.** Tiara Web SDK 를 직접 연동하지 않아도 되고, 게임이 구현할 항목도 없습니다. `init()` 에 넘긴 `gameCode` · `appId` 와 카카오 사용자 식별값이 그대로 쓰입니다. ::: warning 이미 Tiara 를 직접 연동했다면 `tiara: false` 로 꺼 주세요. 켠 채로 두면 같은 로그가 두 번 쌓입니다. ::: 무엇이 언제 나가는지는 [전체 메서드](/api-sdk/sdk/gameplay-js/reference#게임-로그)를 참고하세요. ## 전체 예시 init 으로 웹뷰 상태를 선언하고, UI·광고·공유를 거쳐 종료까지 이어지는 흐름입니다. ```ts async function bootstrapGame(): Promise { try { await Gameplay.init({ gameName: '게임 이름', gameCode: 'sample-game', appId: 1234567, clientKey: 'YOUR_JAVASCRIPT_KEY', webview: { orientation: 'landscape', scrollEnabled: false, }, }); } catch (error) { console.error('게임플레이 SDK 초기화 실패', error); return; } Gameplay.UI.Toast.show('게임을 준비하고 있습니다.', {duration: 1500}); const ad = await Gameplay.createInterstitialAd({ adUnit: 'DAN-...', ctag: {cp: 'game-code', channel: 'ch-id'}, }); ad.onClose(() => startGame()); ad.load(); ad.open(); } async function onGameClear(): Promise { await Gameplay.talkShare({ templateId: 12345, serverCallbackArgs: { APP_USER_ID: 1001, APP_ID: 42, GAME_TYPE: 'my-game', MESSAGE_TYPE: 'GAME_SHARE', HAS_REWARD: false, }, }); } async function onGameExit(): Promise { await Gameplay.close(); } void bootstrapGame(); ``` ## 기능 확인 카카오톡 버전마다 지원하는 브리지 메서드가 다르므로, 버전을 비교해 기능을 분기하지 않습니다. 패치·백포트 빌드가 섞이면 버전 비교가 실제 지원 여부와 어긋날 수 있기 때문입니다. 대신 `isAvailable()` 로 메서드가 실제로 존재하는지 직접 확인합니다. ```ts declare function semverGte(version: string | undefined, target: string): boolean; declare const info: {talkVersion?: string}; // 권장하지 않음 — 버전으로 추정하면 패치·백포트 빌드에서 어긋납니다 if (semverGte(info.talkVersion, '26.7.0')) { await Gameplay.setScrollEnabled(false); } // 권장 — 메서드 존재를 직접 확인합니다 if (Gameplay.isAvailable('setScrollEnabled')) { await Gameplay.setScrollEnabled(false); } ``` `getDeviceInfo()` 가 반환하는 `talkVersion` 은 기능 분기가 아니라 톡 업데이트 안내 UX, 분석 지표, 버그 리포트 용도로 씁니다. ## 참고 문서 * [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/): SDK 개요와 게임웹뷰 SDK 와의 관계 * [다운로드](/api-sdk/sdk/gameplay-js/download): CDN 주소와 버전별 `integrity` 값 * [전체 메서드](/api-sdk/sdk/gameplay-js/reference): 메서드와 에러 코드 전체 명세 * [UI 컴포넌트](/api-sdk/sdk/gameplay-js/ui): managed UI 5개 컴포넌트의 옵션과 표시 정책 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/sdk/gameplay-js/download.md description: 게임플레이 JS SDK 의 CDN 주소와 버전별 integrity 값, TypeScript 선언 파일 --- # 게임플레이 JS SDK 다운로드 CDN 에서 ` ``` ::: danger integrity 와 crossorigin 을 함께 씁니다 `integrity` 는 그 버전의 값과 **일치해야** 합니다. 어긋나면 브라우저가 스크립트 실행을 거부하고, `Gameplay` 객체가 만들어지지 않아 `Gameplay.init()` 에서 `ReferenceError` 가 납니다. `crossorigin="anonymous"` 가 없으면 브라우저가 검증 자체를 수행하지 못합니다. ::: 버전 경로는 한 번 배포되면 내용이 바뀌지 않습니다. 새 버전은 새 경로로 올라가므로 URL 과 `integrity` 를 함께 바꿉니다. 초기화 방법은 [시작하기](/api-sdk/sdk/gameplay-js/getting-started#초기화)를 참고하세요. ## 파일 목록 같은 경로에 두 파일이 함께 배포됩니다. 파일명을 누르면 주소가 열립니다. `min.js` 는 **태그 복사**로 `integrity` 가 채워진 ` ``` 주의: * 브릿지 페이지는 **inline script만 있는 정적 HTML** 이어야 합니다. ` ``` 트레이드오프: * 초기 렌더까지 흰 화면 구간이 잠깐 존재 (배경 스타일로 완화) * HTML 개조 후에도 첫 진입 시 실제 JS 실행 시점은 이전과 유사하지만, **native header는 `didFinishNavigation` 기준으로 이미 사라진 뒤**이므로 잔상은 발생하지 않습니다. * 라우팅·백엔드 변경 없이 프론트 빌드 산출물만 수정하면 되는 저비용 대응입니다. ## 참고 문서 * [게임 실행 흐름](/docs/webview/launch-flow): 웹뷰 진입부터 게임 실행까지의 화면 전환 구조 * [웹뷰 컴포넌트 가이드](/docs/design/webview-component-guide): 화면 컴포넌트와 디자인 사양 * [게임웹뷰 테스트 방법](/docs/webview/test-guide): 화이트리스트 도메인 웹뷰 실행 방법 * [카카오싱크 API: 게임 중 추가 동의](/api-sdk/kakaosync/rest-api#게임-중-추가-동의): 별도 웹뷰 open/close 스킴 사용법 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/sdk/adfit.md description: 애드핏 전면 광고·보상형 전면 광고 SDK 의 설치·인스턴스 생성·노출 제어·이벤트 스펙 --- # 애드핏 광고 SDK 애드핏 광고 SDK 로 파트너사 게임에서 전면 광고와 보상형 전면 광고를 노출하는 방법입니다. 두 광고는 설치·노출 제어·이벤트가 동일하며, 인스턴스를 만드는 팩토리 메서드와 보상 처리만 다릅니다. > **관련 가이드**: [광고 UX 가이드](/docs/ads/ux-guideline), [애드핏 설정](/docs/ads/iaa-options) ::: info 신규 연동이라면 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)가 광고 SDK 를 내부에서 다루므로 `Gameplay.*` 호출만으로 전면·보상형 광고를 노출할 수 있습니다. 이 문서는 애드핏 광고 SDK 를 **직접** 연동하는 방식입니다. 두 방식을 동시에 구성하는 것은 권장하지 않습니다. 자세한 내용은 [SDK 연동 방식 선택](/api-sdk/sdk/)을 참고하세요. 광고단위 발급은 방식과 무관하게 파트너사가 직접 진행합니다. ::: ## SDK 설치 광고를 노출할 페이지에 아래 스크립트를 삽입합니다. ```html ``` ### 페이지 메타태그 설정 모바일 브라우저에서 광고를 상단 내비게이션 영역까지 자연스럽게 표시하려면, 광고를 노출할 페이지 `` 의 viewport 메타태그에 `viewport-fit=cover` 를 지정합니다. ```html ``` 기존 viewport 메타태그가 있다면 새 태그를 추가하지 않고 `content` 값에 `viewport-fit=cover` 만 덧붙입니다. ## 타입 정의 SDK는 브라우저 어디서든 접근할 수 있는 `window.kakaoAdFit` 객체로 제공됩니다. TypeScript 프로젝트에서는 아래처럼 `window.kakaoAdFit` 타입을 선언하면 이후 예제를 그대로 컴파일할 수 있습니다. ```ts type AdFitAdEvent = 'loaded' | 'failed' | 'opened' | 'closed' | 'rewarded' | 'unloaded'; interface AdFitAdOptions { ctag?: {cp: string; channel: string}; safeAreaInset?: { top: number; bottom: number; left: number; right: number; }; } interface AdFitAd { load(): void; open(): void; close(): void; destroy(): void; addListener(event: AdFitAdEvent, handler: () => void): void; removeListener(event: AdFitAdEvent, handler: () => void): void; } declare global { interface Window { kakaoAdFit: { cmd: Array<() => void>; createInterstitialAd(adUnit: string, options?: AdFitAdOptions): AdFitAd; createRewardedInterstitialAd(adUnit: string, options?: AdFitAdOptions): AdFitAd; }; } } ``` `rewarded` 는 보상형 광고에서만 발생합니다. 전면 광고 인스턴스에 등록해도 호출되지 않습니다. ## 인스턴스 생성 광고의 노출·미노출을 관리할 인스턴스를 생성합니다. 광고 관련 모든 스크립트는 SDK 설치 이후 실행되어야 하므로 `window.kakaoAdFit.cmd.push` 콜백 안에서 작성합니다. | 광고 유형 | 팩토리 메서드 | | --- | --- | | 전면 광고 | `window.kakaoAdFit.createInterstitialAd(adUnit, options?)` | | 보상형 전면 광고 | `window.kakaoAdFit.createRewardedInterstitialAd(adUnit, options?)` | ```html ``` 생성 이후의 메서드와 이벤트는 두 유형이 같습니다. 보상형 광고에만 `rewarded` 이벤트가 추가됩니다. ### 옵션 팩토리 메서드의 두 번째 인자로 `AdFitAdOptions` 를 전달합니다. 아래 옵션들은 함께 지정할 수 있습니다. | 옵션 | 용도 | | --- | --- | | `ctag` | 채널 CP 수집 | | `safeAreaInset` | 게임웹뷰가 제공하는 Safe Area 값 전달 (단위: px). 리워드·전면형 광고 운영 시 반드시 적용 | ### 채널 CP 수집 채널 CP 를 수집하려면 `ctag` 를 지정합니다. 게임별 광고 지표를 구분하려면 `ctag`의 CPID와 채널 ID를 정확하게 설정해야 합니다. ::: danger 주의사항 게임별 광고 수익 통계를 지원하려면 `ctag.cp`의 CPID를 게임플레이 파트너센터에 등록한 게임 코드와 동일하게 설정해야 합니다. 값이 다르거나 누락되면 광고 수익이 해당 게임과 연결되지 않으므로 반드시 설정하세요. ::: | 값 | 설정 기준 | | --- | --- | | **CPID** (`cp`) | 게임플레이 파트너센터에 등록한 게임 코드와 **동일한 값**을 입력합니다.메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 그대로 유지합니다. | | **채널 ID** (`channel`) | 카카오에서 발급한 값을 입력합니다.발급값 확인이 필요한 경우 카카오 담당자에게 문의하세요. | 게임마다 CPID가 다르므로 게임별 광고 SDK 인스턴스에 정확한 값을 매핑합니다. ```ts const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea(); const options: AdFitAdOptions = { ctag: { cp: '파트너사가 설정한 게임 코드와 동일한 CPID', channel: '카카오에서 발급한 채널 ID', }, safeAreaInset, }; const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options); ``` ### Safe Area 설정 ::: danger 주의사항 보상형 전면 광고와 전면 광고의 광고단위를 적용할 때는 `safeAreaInset` 설정이 반드시 필요합니다. 게임웹뷰의 전체 화면 사용 여부와 관계없이 두 광고 상품을 운영하면 모두 적용해야 합니다. ::: [게임웹뷰 SDK의 `getSafeArea()`](/api-sdk/sdk/kakaotalk-gameplay#getsafearea)가 반환한 `top`, `bottom`, `left`, `right` 값을 가공하지 않고 `safeAreaInset`으로 그대로 전달하세요. 값이 `0`인 방향도 생략하지 말고 `0`으로 전달합니다. ```ts const safeAreaInset = await window.kakaotalkGamePlay.getSafeArea(); // 예: {top: 47, bottom: 34, left: 0, right: 0} const options: AdFitAdOptions = { safeAreaInset, }; const ad = window.kakaoAdFit.createRewardedInterstitialAd(adUnit, options); ``` ## 광고 노출 제어 인스턴스 생성 이후 아래 네 개의 메서드로 광고 노출을 제어합니다. | 메서드 | 동작 | | --- | --- | | `ad.load()` | 광고 로딩 (노출하지 않음) | | `ad.open()` | 광고 노출 (로딩이 안 되어 있으면 로딩부터 진행) | | `ad.close()` | 광고 닫기 시도. 사용자가 닫기 버튼을 누른 것과 동일하게 동작 | | `ad.destroy()` | 강제로 광고를 닫고 제거 | ```ts window.kakaoAdFit.cmd.push(() => { const ad = window.kakaoAdFit.createInterstitialAd(adUnit, options); ad.load(); ad.open(); ad.close(); ad.destroy(); }); ``` **`ad.close()` 참고**: 광고 시청 중에 호출하면 닫기 버튼을 누른 것과 동일하게 동작합니다. 닫기 버튼 클릭 시 확인 팝업이 노출되는 경우, `ad.close()` 호출로 동일한 팝업을 노출할 수 있습니다. ## 이벤트 특정 시점마다 발생하는 이벤트에 리스너를 등록·해제할 수 있습니다. ### 이벤트 종류 | 이벤트 | 발생 시점 | | --- | --- | | `loaded` | 광고 로딩 완료 | | `failed` | 광고 로딩 실패 | | `opened` | 광고 노출 | | `closed` | 광고 종료 | | `rewarded` | **보상 지급 조건 충족** (보상형 광고 전용) | | `unloaded` | 광고 리소스 해제 | ### 이벤트 등록·해제 ```ts function handleLoaded(): void { /* 광고 로드 완료 시 동작 */ } ad.addListener('loaded', handleLoaded); ad.removeListener('loaded', handleLoaded); ``` ### 보상 지급 시점 보상은 `rewarded` 이벤트에서 지급하는 것을 권장합니다. `closed` 에서 지급하면 시청 도중 이탈한 사용자에게도 보상이 지급되어 지급 누락이나 오지급이 발생할 수 있습니다. 세부 UX 정책은 [광고 UX 가이드: 보상 지급 시점](/docs/ads/ux-guideline#보상-지급-시점)을 참고하세요. ## 전체 예제 ### 전면 광고 ```html
``` ### 보상형 광고 ```html
``` ## 참고 문서 * [광고 UX 가이드](/docs/ads/ux-guideline): 노출 정책, 보상 지급, Back Key 처리, 화면 복구 UX * [애드핏 설정](/docs/ads/iaa-options): 광고단위 발급과 리워드 설정 * [CP별 리포트 API](/api-sdk/ads/cp-report) * 기술 문의 — [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/sdk/kakao-js.md description: 게임플레이 파트너사가 카카오 로그인·카카오싱크와 카카오톡 공유를 연동하기 위한 카카오 JS SDK 설치와 초기화 --- # 카카오 JS SDK 카카오 JS SDK는 카카오디벨로퍼스에서 제공하는 웹용 SDK입니다. 게임플레이 파트너사는 카카오 로그인·카카오싱크의 사용자 인증과 동의 흐름, 카카오톡 공유 기능을 연동할 때 이 SDK를 설치하고 초기화해야 합니다. 이 문서는 **게임플레이 연동에 필요한 부분만** 다룹니다. SDK 버전 목록·`integrity` 값·브라우저 지원 범위처럼 자주 바뀌는 정보는 카카오디벨로퍼스가 정본이며, 이 페이지에 옮겨 적지 않습니다. 설치 전 전체 흐름은 [카카오디벨로퍼스 시작하기 가이드](https://developers.kakao.com/docs/ko/javascript/getting-started)를 참고하세요. 사용자 인증과 동의 흐름은 [카카오싱크 API](/api-sdk/kakaosync/rest-api)를 참고하세요. 공유 메시지를 구성하고 호출하는 방법은 [공유 설정](/docs/share/settings)을 참고하세요. ::: info 신규 연동이라면 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)가 카카오 JS SDK 를 내부에서 로드하므로 `Gameplay.*` 호출만으로 로그인·공유를 처리할 수 있습니다. 이 문서는 카카오 JS SDK 를 **직접** 연동하는 방식입니다. 두 방식을 동시에 구성하는 것은 권장하지 않습니다. 자세한 내용은 [SDK 연동 방식 선택](/api-sdk/sdk/)을 참고하세요. JavaScript 키 발급은 방식과 무관하게 파트너사가 직접 진행합니다. ::: ## 사전 준비 설치 전에 아래 세 가지를 먼저 확인합니다. | 항목 | 확인 위치 | 비고 | | --- | --- | --- | | JavaScript 키 | **\[앱] > \[플랫폼 키] > \[JavaScript 키]** | 파트너사 앱의 JavaScript 키를 사용합니다. 어드민 키를 쓰지 않습니다. [앱 키 확인](https://developers.kakao.com/docs/ko/app-setting/app#javascript-key) | | `integrity` 값 | [카카오 JS SDK 다운로드](https://developers.kakao.com/docs/ko/javascript/download) | SDK 버전과 짝이 맞는 값을 복사합니다 | | JavaScript SDK 도메인 | **\[앱] > \[플랫폼 키] > \[JavaScript 키] > \[JavaScript SDK 도메인]** | 등록한 도메인에서만 SDK 가 동작합니다 | | 제품 링크 도메인 | **\[앱] > \[제품 링크 관리] > \[웹 도메인]** | 게임플레이 도메인 `https://gameplay.kakao.com` 을 등록합니다 | ## SDK 설치 `` 에 SDK 스크립트를 추가합니다. 게임플레이 공유 연동은 **`2.8.0` 이상**을 요구합니다. ```html ``` `{버전}` 과 `integrity` 는 [디벨로퍼스 다운로드 페이지](https://developers.kakao.com/docs/ko/javascript/download)에서 복사합니다. 두 값은 **짝이 맞아야** 합니다. 버전만 올리고 `integrity` 를 그대로 두면 브라우저가 무결성 검증에 실패해 SDK 가 로드되지 않습니다. ## 초기화 파트너사 앱의 JavaScript 키로 초기화합니다. 카카오 로그인·카카오싱크 또는 카카오톡 공유 기능을 호출하기 전에 한 번만 실행하면 됩니다. ```ts declare global { interface Window { Kakao: { init(appKey: string): void; isInitialized(): boolean; }; } } if (!window.Kakao.isInitialized()) { window.Kakao.init('JAVASCRIPT_KEY'); } ``` `isInitialized()` 로 감싸면 SPA 에서 라우팅이 반복돼도 중복 초기화를 피할 수 있습니다. ## 전체 예제 ```html ``` 초기화 이후 카카오 로그인·카카오싱크 연동에는 `Kakao.Auth.authorize()`를, 카카오톡 공유에는 `Kakao.Share.sendCustom()`을 사용합니다. 인증과 동의 흐름은 [카카오싱크 API](/api-sdk/kakaosync/rest-api)를, 템플릿 ID·`templateArgs`·`pickerSettings` 구성은 [공유 설정: 구현 상세 안내](/docs/share/settings#구현-상세-안내)를 참고하세요. ## 참고 문서 * [공유 설정](/docs/share/settings): 게임플레이 공유 템플릿과 호출 방법 * [단축 URL 생성](/api-sdk/share/short-url): 공유 버튼에 넣을 단축 URL 발급 * [카카오 JS SDK 시작하기](https://developers.kakao.com/docs/ko/javascript/getting-started): 브라우저 지원 범위, 플랫폼 등록 절차 * [카카오 JS SDK 다운로드](https://developers.kakao.com/docs/ko/javascript/download): 버전별 CDN 주소와 `integrity` 값 * [카카오톡 공유 JavaScript 가이드](https://developers.kakao.com/docs/ko/kakaotalk-share/js-link) * 기술 문의 — [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/sdk/tiara-web.md description: Tiara Web SDK로 게임 로그(Pageview, Event 등)를 수집·전송하는 방법 --- # Tiara Web SDK Tiara Web SDK를 직접 연동해 게임 로그를 수집·전송하는 방법입니다. ::: info 신규 연동이라면 게임플레이 JS SDK를 사용하는 게임은 SDK의 로그 적용 방식을 따르므로 Tiara Web SDK를 별도로 설치하지 않습니다. 이 문서는 **게임플레이 JS SDK를 사용하지 않는 게임에서 Tiara Web SDK를 직접 연동하는 방식**을 안내합니다. 두 방식을 동시에 구성하는 것은 권장하지 않습니다. 자세한 내용은 [SDK 연동 방식 선택](/api-sdk/sdk/)을 참고하세요. ::: 게임플레이 JS SDK를 적용하지 않은 게임은 이 가이드와 [게임 로그 설정](/api-sdk/sdk/tiara-game-logs)에 따라 Tiara Web SDK를 설치하고 필수 게임 로그를 구현하세요. ::: info 게임플레이 JS SDK 를 쓰는 게임 [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)가 이 문서의 수집·전송을 대신 처리합니다. `init()` 에 넘긴 `gameCode` 와 `appId` 가 그때 쓰입니다. **이 문서대로 직접 연동할 필요가 없습니다** — 자세한 내용은 [전체 메서드: 게임 로그](/api-sdk/sdk/gameplay-js/reference#게임-로그)을 참고하세요. ::: ## 개요 ### 주요 수집 내용 * **Pageview (화면 조회)**: 사용자가 특정 페이지(화면)에 방문했음을 기록합니다. * **Event (사용자 행동)**: 클릭 등 Pageview를 제외한 사용자 행동을 기록합니다. * **ViewableImpression (콘텐츠 노출)**: 게임 종료 팝업 등 특정 영역이 사용자에게 실제로 노출됐음을 기록합니다. * **Usage (체류시간)**: 페이지 체류시간을 기록합니다. ### 주요 용어 | 용어 | 설명 | 예시 | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | 액션 | Tiara Web SDK가 수집하는 게임 로그 단위(Action). Pageview·Event·ViewableImpression·Usage 네 가지 타입으로 나뉩니다 | Pageview, Event, ViewableImpression, Usage | | 서비스 도메인 | 데이터를 수집할 서비스 고유 식별자. 게임플레이 파트너사는 카카오에서 제공하는 도메인을 사용합니다 | gameplay.kakao.com | | 페이지 | 화면을 구분하는 이름. 게임플레이 파트너사는 고정값을 사용합니다. 모든 액션은 페이지 정보를 기본으로 합니다 | SDK게임 | | 섹션 | 페이지들을 그룹핑하는 상위 카테고리. 게임플레이 파트너사는 게임 코드 기준 고정값을 사용합니다 | SDK\_{게임ID} | | 액션명 | 발생한 행동을 설명하는 이름. 게임플레이 필수 게임 로그는 게임 로그 정의 표의 Name 값을 그대로 사용합니다 | Event: 게임\_더보기\_클릭Pageview: SDK\_게임\_조회 | ### ActionType 사용자의 행동을 구분하는 가장 큰 단위입니다. 단위에 따라 사용하는 SDK 함수가 다릅니다. | Action Type | 설명 | SDK 함수 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | | Pageview | 사용자가 하나의 화면을 볼 때 사용합니다. 팝업이나 메뉴 레이어에는 사용하지 않습니다 | `trackPage('액션명')` | | Event | 사용자가 직접 행동을 취한 경우 사용합니다. 대표적으로 클릭 동작입니다 | `trackEvent('액션명')` | | ViewableImpression | 화면 상의 특정 콘텐츠 영역의 노출을 기록합니다. 노출은 사용자가 실제로 해당 영역을 본 경우를 뜻하며, 게임플레이에서는 게임 종료 팝업 노출에 사용합니다 | `trackViewImp('액션명')` | | Usage | 페이지 단위로 사용자의 체류시간을 기록합니다. 보통 체류시간 측정을 위해 사용하며, 서비스에서 직접 페이지 진입·이탈 시점을 확인해 측정한 시간을 기록합니다. ms 단위로 기록합니다. 최대값은 3시간으로, 그 이상 값이 입력되면 null로 변환되어 저장됩니다 | `trackUsage('액션명')` | ### 세팅시 주의사항 * 아래 필드는 설정 후 페이지 전환 등 TiaraTracker 인스턴스가 재생성되기 전까지 고정됩니다. * Page, PageMeta: `setPage()` 및 `setPageMeta()` 호출 이후 고정 * SPA 등 TiaraTracker 인스턴스가 재생성되지 않는 환경에서는 필요 시 페이지 전환 이후 다음 필드를 초기화합니다. * Page, PageMeta: `setPage()` 및 `setPageMeta()`로 초기화 ## SDK 설치 및 초기화 ### 스크립트 추가 분석하려는 웹 페이지의 상단에 아래 내용을 추가합니다. `` 영역 사용을 권장합니다. ```html ``` ### 기본 설정 (초기화) 스크립트 로드 후 아래 설정 항목(Deployment·서비스 도메인·페이지명·Section)을 설정합니다. ## 설정 항목 TiaraTracker에 지정하는 설정값입니다. 게임플레이 입점 시 반드시 맞춰야 하는 값은 [게임 로그 설정의 필수 세팅 항목](/api-sdk/sdk/tiara-game-logs#필수-세팅-항목)을 먼저 확인하세요. ### Deployment 세팅 게임플레이 파트너사는 `production`만 사용합니다. 개발·테스트 단계에서도 동일하게 `production`을 사용하며, `dev`·`cbt`·`sandbox`로 전송한 로그는 게임플레이 로그로 수집되지 않습니다. ```ts TiaraTracker.getInstance().setDeploymentProduction().track(); ``` ### 서비스 구분 전송되는 데이터의 서비스를 구분하기 위한 정보를 설정합니다. 게임플레이 입점 파트너사는 카카오에서 제공하는 svcDomain 값을 그대로 사용합니다. ```text .setSvcDomain('gameplay.kakao.com') ``` ### 페이지명 게임플레이 파트너사는 `SDK게임`으로 고정합니다. 세팅 이후에는 페이지 전환 등 TiaraTracker 인스턴스 초기화 전까지 고정됩니다. ```text .setPage('SDK게임') ``` ### Section 게임플레이 파트너사는 `SDK_{게임ID}`로 고정합니다. `{게임ID}`는 게임플레이 파트너센터에 등록한 게임 코드를 그대로 사용하며, 게임 이름이나 공백은 사용할 수 없습니다. ```text .setSection('SDK_{게임ID}') ``` ### 설정 일괄 적용 아래 항목은 초기화 시 일괄 적용할 수 있습니다. ```ts TiaraTracker.init(config); ``` | 파라미터 | 설명 | | --- | --- | | svcDomain | 서비스를 구분하는 값. 게임플레이 파트너사는 gameplay.kakao.com 고정 사용 | | thirdProvideAgree | 기본값 null제3자 정보 제공 동의 여부. 게임플레이 파트너사는 true 고정 사용 | | thirdAdAgree | 기본값 null광고 마케팅 제공에 동의한 경우 true, 동의하지 않은 경우 false | | deployment | 기본값 production서비스 배포 상태. 게임플레이 파트너사는 production만 사용합니다 | 사용 예제입니다. ```ts const config = { svcDomain: 'gameplay.kakao.com', thirdProvideAgree: true, thirdAdAgree: false, deployment: 'production', }; TiaraTracker.getInstance().init(config); ``` ### TiaraTracker 설정 예제 ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .setDeployment('production') .setAccessToken('access_token') // 또는 .setAppUserId + .setKakaoAppKey .track(); ``` 모든 설정값을 초기화하려면 아래를 실행합니다. ```ts TiaraTracker.initTracker(); ``` ### AccessToken / AppUserId 카카오 계정 연동을 위해 AccessToken 또는 AppUserId를 반드시 설정합니다. 아래 세 가지 방식 중 하나를 선택하며, 미세팅 시 카카오 분석 환경에서 게임 로그를 집계·활용할 수 없습니다. AccessToken·AppUserId·kakaoAppKey는 카카오디벨로퍼스 Prod(Real) phase 기준 값을 사용합니다. ```text .setAccessToken("access_token") // 또는 .setAppUserId("app_user_id") + .setKakaoAppKey("kakaoappkey") // 또는 .setAppUserId("app_user_id") + .setKakaoAppId("kakaoappid") ``` app\_user\_id를 넣을 때는 kakaoAppKey 또는 kakaoAppId를 반드시 함께 설정해야 합니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .setAccessToken('xxx-xxx-xxx-xxx') // 또는 .setAppUserId('xxx-xxx-xxx-xxx'); ``` ### 제3자 동의 여부 세팅 게임플레이 플랫폼에 입점하는 파트너사는 제3자 정보 제공 동의 여부를 필수로 세팅하고, 광고 마케팅 동의 여부는 사용자 선택값을 알고 있는 경우 함께 세팅합니다. 해당 정보는 로그인한 상태에서만 세팅합니다. 게임플레이 사용자는 진입 시 제3자 정보 제공 동의를 필수로 거치므로 `thirdProvideAgree`는 항상 `true`로 설정합니다. 미설정 또는 `false` 상태의 게임 로그는 카카오 내부에서 분석·활용할 수 없습니다. [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)를 쓰는 게임은 이 setter 를 직접 호출하지 않습니다. 광고 마케팅 동의 여부는 `init({tiara: {thirdAdAgree}})` 로 넘기고, 제3자 정보 제공 동의는 SDK 가 `true` 로 고정합니다. | setter | 매개변수 타입 | 설명 | | -------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | setThirdProvideAgree | boolean | (필수 동의) 제3자 정보 제공 동의 여부. 게임플레이 진입을 위한 필수 동의로, 미동의 사용자는 진입 자체가 불가능합니다. 게임플레이 사용자는 항상 동의 상태이므로 true로 세팅합니다 | | setThirdAdAgree | boolean | (선택 동의) 광고 마케팅 동의 여부. 사용자가 선택할 수 있는 동의이므로 동의/미동의 케이스가 모두 발생합니다. 사용자 선택에 따라 true 또는 false로 세팅합니다 | 게임 로그 필드 `common.third_provide_agree = 1`은 `thirdProvideAgree: true`와 같습니다. 동의한 사용자는 반드시 `true(=1)`로 설정해 전송합니다. ## 게임 로그 전송 방법 게임플레이 필수 게임 로그의 액션명은 [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의) 표의 Name 값을 그대로 사용합니다. ### Pageview 페이지(화면) 정보를 트래킹할 때 사용합니다. ```ts trackPage('액션명'); ``` 사용 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); TiaraTracker.getInstance().trackPage('SDK_게임_조회').track(); ``` ### Event 이벤트 통계를 수집할 때 사용합니다. 이벤트란 클릭 등 Pageview를 제외한 사용자 행동입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); TiaraTracker.getInstance().trackEvent('게임종료_팝업_확인_클릭').track(); ``` ### Usage 페이지 체류시간을 수집할 때 사용합니다. 체류시간은 Foreground 상태에서 실제 페이지를 사용한 시간을 기준으로 측정합니다. * Foreground/Background 전환은 게임웹뷰 SDK의 [registerNativeHandler와 UPDATE 이벤트](/api-sdk/sdk/kakaotalk-gameplay#registernativehandler-handlername-와-update-이벤트) 중 `LIFECYCLE` 이벤트로 감지합니다. * `FOREGROUND`: 체류시간 측정 시작 또는 재시작 (0ms부터 측정) * `BACKGROUND`: 현재까지 측정한 체류시간을 Usage로 기록 및 전송 * 페이지 진입 시 최초 측정을 시작하며, 이후 `FOREGROUND` 전환마다 새로운 사용 세션으로 간주해 0ms부터 다시 측정합니다. * 페이지 이탈 시 측정 중인 체류시간이 있으면 마지막 구간을 기록 및 전송합니다. * ms 단위로 기록하며 최대 3시간(10,800,000ms)입니다. 초과 시 null로 변환되어 저장됩니다. ```text .trackUsage('액션명') .usage(usage정보) ``` 사용 예제입니다. ```ts const usage = {duration: '120000'}; TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임') .trackUsage('SDK_게임_체류시간') .usage(usage) .track(); ``` | 파라미터 | 설명 | 예제 | | --------------------- | ----------------------------------------------------------------- | -------- | | duration | 현재 Foreground Usage 구간의 체류시간(ms). 최대 10,800,000 (3시간) | "120000" | ### ViewableImpression `trackViewImp('액션명')` 형태로 액션명을 반드시 전달합니다. 사용 예제입니다. ```ts TiaraTracker.getInstance().trackViewImp('게임종료_팝업_노출').track(); ``` ## 추가 정보 전송 ### ActionKind [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의)에 ActionKind가 명시된 로그(예: `SDK_게임_조회`의 `ViewContent`)는 해당 값을 반드시 동일하게 전송합니다. `SDK_게임_조회` 로그의 전송 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); const pageMeta = { id: 'GAME_001', type: 'h5', name: '퍼즐 게임 샘플', }; TiaraTracker.getInstance() .trackPage('SDK_게임_조회') .actionKind('ViewContent') .pageMeta(pageMeta) .track(); ``` ### Page meta 해당 페이지(page)에 대한 메타 정보를 부가적으로 추가할 수 있습니다. 게임플레이 표준값은 [게임 로그 설정](/api-sdk/sdk/tiara-game-logs)을 참고하세요. 세팅 이후에는 페이지 전환 등 TiaraTracker 인스턴스 초기화 전까지 고정됩니다. ```text .pageMeta(pageMeta) ``` 전송 예제는 [ActionKind](#actionkind)를 참고하세요. ## 이벤트별 스펙 행동 유형별로 전송해야 하는 파라미터 규격입니다. ### Click 이벤트 액션이 클릭인 경우 클릭 항목에 대한 추가 정보를 전송할 수 있습니다. ```text .click(클릭정보) ``` [게임 로그 정의](/api-sdk/sdk/tiara-game-logs#게임-로그-정의)에 click 정보가 명시된 로그(더보기·공유하기·문의하기·내 게임 관리·닫기·접기)만 `click.layer1: 'header'`를 세팅합니다. 사용 예제입니다. ```ts TiaraTracker.getInstance() .setSvcDomain('gameplay.kakao.com') .setSection('SDK_{게임ID}') .setPage('SDK게임'); const click = {layer1: 'header'}; TiaraTracker.getInstance().trackEvent('게임_더보기_클릭').click(click).track(); ``` ## 참고 문서 * [게임 로그 설정](/api-sdk/sdk/tiara-game-logs): 필수 세팅 항목과 게임 로그 11종 정의 * [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 액션데이터 요청 본문 샘플 * [액션데이터 API](/api-sdk/data/action-data): 게임 이벤트 전송 규격 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/sdk/tiara-game-logs.md description: Tiara Web SDK로 구현하는 필수 게임 로그 11종과 필수 세팅 항목, 표준 page_meta 값 --- # 게임 로그 설정 게임플레이 JS SDK를 사용하지 않는 게임에서 Tiara Web SDK로 구현해야 하는 필수 게임 로그를 안내합니다. SDK 설치와 메서드 사용법은 [Tiara Web SDK](/api-sdk/sdk/tiara-web)를 참고하세요. ::: tip 게임플레이 JS SDK를 쓰는 게임 **이 문서의 구현은 필요하지 않습니다.** SDK가 게임 로그를 대신 보냅니다. 액션명도 SDK 전용 명세를 쓰므로 아래 표와 다릅니다. 자세한 내용은 [전체 메서드: 게임 로그](/api-sdk/sdk/gameplay-js/reference#게임-로그)을 참고하세요. ::: ## 필수 세팅 항목 게임플레이 JS SDK를 사용하지 않는 게임에서 Tiara Web SDK를 직접 적용할 때 다음 4가지를 반드시 설정해야 합니다. | # | 항목 | 값 / 방법 | | --- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | 1 | 서비스 도메인 (svcDomain) | gameplay.kakao.com 고정. 별도 신규 신청은 필요하지 않습니다 | | 2 | 제3자 정보 제공 동의 (thirdProvideAgree) | true 고정. 게임플레이 진입 시 제3자 제공 동의를 필수로 수령합니다. 설정 방법은 [제3자 동의 여부 세팅](/api-sdk/sdk/tiara-web#제3자-동의-여부-세팅)을 참고하세요 | | 3 | 필수 게임 로그 11종 | 아래 [게임 로그 정의](#게임-로그-정의)에 정의된 11종의 게임 로그를 Tiara Web SDK 가이드의 trackPage / trackEvent / trackViewImp / trackUsage 메서드로 구현합니다 | | 4 | 카카오 사용자 식별값 (AccessToken 또는 AppUserId) | 두 방식 중 하나로 필수 세팅. 미세팅 시 카카오 분석 환경에서 게임 로그를 집계·활용할 수 없습니다. 설정 방법은 [AccessToken / AppUserId](/api-sdk/sdk/tiara-web#accesstoken-appuserid)를 참고하세요 | svcDomain은 모든 입점 파트너사가 동일하게 `gameplay.kakao.com` 값을 사용합니다. 파트너사·게임 구분은 게임플레이 파트너센터에 등록한 게임 코드로 처리합니다. ## 게임 로그 정의 게임플레이 입점 파트너사가 필수로 구현하는 게임 로그 11종입니다. 이 가이드의 메서드(`trackPage` · `trackEvent` · `trackViewImp` · `trackUsage`)로 구현하며, `{게임ID}`는 게임플레이 파트너센터에 등록한 게임 코드를 그대로 사용합니다. 메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 사용합니다. 게임 이름이나 공백은 사용할 수 없습니다. ::: tip 게임플레이 JS SDK 를 쓴다면 이 표가 아닙니다 아래 값은 **직접 연동하는 게임용**입니다. [게임플레이 JS SDK](/api-sdk/sdk/gameplay-js/)는 `section` · `page` · 액션명이 모두 다릅니다 — 두 경로의 로그를 분석 단계에서 가를 수 있어야 하기 때문입니다. | | 직접 연동 (이 표) | 게임플레이 JS SDK | | --- | --- | --- | | `Section` | `SDK_{게임ID}` | `sdk_ui_{게임ID}` | | `Page` | `SDK게임` | `SDK_UI` | | `Name` | 아래 표 | `SDK_UI_` 접두어로 통일 | ::: | # | 발생 시점 | Section | Page | Type | Name | 비고 | | --- | --- | --- | --- | --- | --- | --- | | 1 | 게임 페이지 진입 | `SDK_{게임ID}` | `SDK게임` | `Pageview` | `SDK_게임_조회` | `actionKind: ViewContent` · `page_meta` 세팅 필수(`id` 필수) | | 2 | 게임 체류시간 수집 | `SDK_{게임ID}` | `SDK게임` | `Usage` | `SDK_게임_체류시간` | `duration`(ms) 필드 필수 | | 3 | 상단 더보기 버튼 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임_더보기_클릭` | `click.layer1: header` | | 4 | 더보기 > 공유하기 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임공유하기_클릭` | `click.layer1: header` | | 5 | 더보기 > 문의하기 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임문의하기_클릭` | `click.layer1: header` | | 6 | 더보기 > 내 게임 관리 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `내게임관리_클릭` | `click.layer1: header` | | 7 | 상단 닫기 버튼 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임_닫기_클릭` | `click.layer1: header` | | 8 | 상단 접기 버튼 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임_접기_클릭` | `click.layer1: header` · iOS 접기 기능 적용 게임만 | | 9 | 게임 종료 팝업 노출 | `SDK_{게임ID}` | `SDK게임` | `ViewImp` | `게임종료_팝업_노출` | — | | 10 | 게임 종료 팝업의 확인 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임종료_팝업_확인_클릭` | — | | 11 | 게임 종료 팝업의 취소 클릭 | `SDK_{게임ID}` | `SDK게임` | `Event` | `게임종료_팝업_취소_클릭` | — | SDK 메서드 매핑 규칙은 다음과 같습니다. * `Pageview` → `trackPage` * `Event` → `trackEvent` * `ViewImp` → `trackViewImp` * `Usage` → `trackUsage`에 `usage` 정보를 함께 전달 각 메서드의 호출 형태와 `page_meta` 구성 방법은 [게임 로그 전송 방법](/api-sdk/sdk/tiara-web#게임-로그-전송-방법)과 [추가 정보 전송](/api-sdk/sdk/tiara-web#추가-정보-전송) 섹션을 참고하세요. ## 게임플레이 표준 page\_meta 값 ActionKind가 `ViewContent`인 게임 로그(`SDK_게임_조회`)는 `page_meta` 세팅이 필수입니다. | 파라미터 | 적용 | 게임플레이 표준값 | | --- | --- | --- | | id | 필수 | 게임 코드 (예: GAME\_001) | | type | 권장 | h5 고정 | | name | 권장 | 게임명 | 세팅 방법은 [Page meta](/api-sdk/sdk/tiara-web#page-meta)를 참고하세요. ## 참고 문서 * [Tiara Web SDK](/api-sdk/sdk/tiara-web): SDK 설치·초기화와 메서드 사용법 * [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 액션데이터 요청 본문 샘플 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/kakaosync/rest-api.md description: 게임웹뷰 진입 시 카카오싱크 간편가입과 자동 로그인을 구현하는 REST API 요청·응답 스펙 --- # 카카오싱크 API 이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다. 실제 구현 전 반드시 [카카오싱크 개발 가이드](https://developers.kakao.com/docs/ko/kakaosync/dev-guide)에서 전체 연동 흐름을, [카카오 로그인 REST API 공식 가이드](https://developers.kakao.com/docs/ko/kakaologin/rest-api)에서 최신 요청·응답 규격과 제약사항을 확인하세요. > **관련 가이드**: [카카오싱크 설정](/docs/authentication/kakao-login-sync)에서 비즈 앱, 채널, 동의항목, 서비스 약관 설정을 먼저 완료하세요. 카카오톡 게임웹뷰에서 카카오싱크 간편가입과 파트너사 로그인을 처리하는 REST API 스펙입니다. 게임 URL 진입 즉시 인가 코드를 요청하고, 앱 미동의 사용자에게는 동의 화면을 표시하며 동의 완료 사용자에게는 별도 버튼 없이 서비스 세션을 발급하는 흐름을 기준으로 합니다. ## API 목록 | API | Method · URL | 적용 여부 | | --- | --- | --- | | 인가 코드 요청 | `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` | 필수 | | 토큰 갱신 | `POST https://kauth.kakao.com/oauth/token` | 필수 | | 액세스 토큰 정보 조회 | `GET https://kapi.kakao.com/v1/user/access_token_info` | 선택 | 연결 해제는 파트너사가 직접 호출하는 API가 아니라 [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)으로 처리됩니다. 자세한 내용은 아래 [연결 해제](#연결-해제)를 참고하세요. 채널 친구 상태를 서비스 기능에 사용한다면 [카카오톡 채널 관계 조회 API](https://developers.kakao.com/docs/ko/kakaotalk-channel/rest-api)를 추가로 연동합니다. ## 공통 ### 호출 도메인 | 도메인 | 용도 | | --- | --- | | `https://kauth.kakao.com` | 인가 코드, 토큰 발급과 갱신을 처리하는 인증 서버입니다. | | `https://kapi.kakao.com` | 사용자 정보, 서비스 약관, 연결 상태를 처리하는 API 서버입니다. | ### 인증 정보 보관 * REST API 키와 클라이언트 시크릿은 파트너사 서버에서만 사용합니다. * 액세스 토큰과 리프레시 토큰은 파트너사 서버에 안전하게 저장합니다. * 어드민 키를 게임웹뷰의 HTML이나 브라우저 요청에 포함하지 않습니다. * 카카오 회원번호(`id`)를 파트너사 회원의 고정 매핑 키로 사용합니다. * 이메일과 전화번호는 변경될 수 있으므로 고정 식별자로 사용하지 않습니다. ### 가입·로그인 처리 순서 1. 게임 URL 진입 즉시 `prompt` 없이 인가 코드를 요청합니다. 2. 앱 미동의 사용자는 카카오싱크 동의 화면을 완료하고, 동의 완료 사용자는 화면 전환 없이 인가 코드를 받습니다. 3. 파트너사 서버가 인가 코드를 액세스 토큰과 리프레시 토큰으로 교환합니다. 4. 사용자 정보와 서비스 약관 동의 내역을 조회합니다. 5. 카카오 회원번호로 기존 회원을 찾거나 신규 회원을 생성합니다. 6. 파트너사 서비스 세션을 생성한 뒤 게임을 실행합니다. 카카오 토큰 발급만으로 파트너사 로그인이 완료되지는 않습니다. 회원 등록 또는 기존 회원 매핑과 파트너사 서비스 세션 생성까지 직접 구현해야 합니다. ## 인가 코드 요청 게임 URL이 로드되면 로그인 버튼을 표시하지 않고 이 요청으로 바로 리디렉션합니다. ```http GET https://kauth.kakao.com/oauth/authorize ``` ### Request Query | 이름 | 타입 | 입력값 | 적용 여부 | | --- | --- | --- | --- | | `client_id` | `String` | 파트너사 앱 REST API 키 | 필수 | | `redirect_uri` | `String` | 디벨로퍼스 앱에 등록한 Redirect URI | 필수 | | `response_type` | `String` | `code` 고정 | 필수 | | `state` | `String` | 요청별로 생성한 예측 불가능한 값 | 필수 | | `scope` | `String` | 추가 동의가 필요한 동의항목 ID를 쉼표로 연결 | 선택 | | `service_terms` | `String` | 추가 동의가 필요한 서비스 약관 태그를 쉼표로 연결 | 선택 | `state`는 카카오 API 기준 선택 파라미터지만 게임플레이 연동에서는 CSRF 방지를 위해 반드시 사용합니다. 콜백에서 요청 세션에 저장한 값과 응답 값을 비교하고 일치하지 않으면 요청을 중단하세요. ::: danger `prompt=none`을 사용하지 않습니다 `prompt=none`은 로그인이나 동의처럼 사용자 동작이 필요할 때 UI를 표시하지 않고 오류를 반환합니다. 게임플레이는 앱 미동의 사용자에게 카카오싱크 동의 화면을 바로 표시해야 하므로 인가 코드 요청에서 `prompt` 파라미터를 보내지 않습니다. ::: ```text https://kauth.kakao.com/oauth/authorize ?response_type=code &client_id=${REST_API_KEY} &redirect_uri=${ENCODED_REDIRECT_URI} &state=${STATE} ``` ### 사용자 상태별 동작 | 사용자 상태 | 카카오 화면 | 결과 | | --- | --- | --- | | 앱 미동의 | 카카오싱크 동의 화면 표시 | 동의 완료 후 `code` 반환 | | 앱 동의 완료 | 별도 화면 없음 | 즉시 `code` 반환 | | 동의 화면 취소 | 게임 미실행 처리 | `error=access_denied` 반환 | ### Response Query | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `code` | `String` | 토큰 발급에 사용할 일회용 인가 코드 | 성공 시 | | `state` | `String` | 요청에 전달한 값 | 요청에 전달한 경우 | | `error` | `String` | 실패 사유 코드 | 실패 시 | | `error_description` | `String` | 실패 사유 설명 | 실패 시 | ```http HTTP/1.1 302 Found Location: https://partner.example.com/oauth/kakao/callback?code=${AUTHORIZE_CODE}&state=${STATE} ``` 인가 코드는 한 번만 사용할 수 있습니다. 토큰 발급에 실패하면 같은 코드를 재사용하지 말고 인가 코드 요청부터 다시 시작합니다. ## 토큰 발급 Redirect URI로 받은 인가 코드를 파트너사 서버에서 토큰으로 교환합니다. ```http POST https://kauth.kakao.com/oauth/token Content-Type: application/x-www-form-urlencoded;charset=utf-8 ``` ### Request Body | 이름 | 타입 | 입력값 | 적용 여부 | | --- | --- | --- | --- | | `grant_type` | `String` | `authorization_code` 고정 | 필수 | | `client_id` | `String` | 파트너사 앱 REST API 키 | 필수 | | `redirect_uri` | `String` | 인가 코드 요청에 사용한 Redirect URI | 필수 | | `code` | `String` | 콜백으로 받은 인가 코드 | 필수 | | `client_secret` | `String` | REST API 키의 [클라이언트 시크릿](https://developers.kakao.com/docs/ko/app-setting/app#client-secret) | 기능 활성화 시 필수 | ```bash curl -X POST 'https://kauth.kakao.com/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id=${REST_API_KEY}' \ --data-urlencode 'redirect_uri=${REDIRECT_URI}' \ --data-urlencode 'code=${AUTHORIZE_CODE}' \ --data-urlencode 'client_secret=${CLIENT_SECRET}' ``` ### Response Body | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `token_type` | `String` | `bearer` 고정 | 항상 | | `access_token` | `String` | 카카오 API 호출에 사용하는 액세스 토큰 | 항상 | | `expires_in` | `Integer` | 액세스 토큰 만료 시간(초) | 항상 | | `refresh_token` | `String` | 액세스 토큰 갱신에 사용하는 토큰 | 항상 | | `refresh_token_expires_in` | `Integer` | 리프레시 토큰 만료 시간(초) | 항상 | | `scope` | `String` | 사용자가 동의한 동의항목 ID 목록. 여러 개이면 공백으로 연결됩니다 | 조건부 | ```json { "token_type": "bearer", "access_token": "${ACCESS_TOKEN}", "expires_in": 43199, "refresh_token": "${REFRESH_TOKEN}", "refresh_token_expires_in": 5184000, "scope": "profile_nickname profile_image" } ``` ## 사용자 정보 조회 액세스 토큰으로 사용자의 카카오 회원번호와 동의한 사용자 정보를 조회합니다. ```http GET https://kapi.kakao.com/v2/user/me Authorization: Bearer ${ACCESS_TOKEN} Content-Type: application/x-www-form-urlencoded;charset=utf-8 ``` ### Request Query | 이름 | 타입 | 설명 | | --- | --- | --- | | `secure_resource` | `Boolean` | 프로필 이미지 URL의 HTTPS 사용 여부 | | `property_keys` | `String[]` | 응답에 포함할 사용자 정보 키 목록 | ```bash curl -G 'https://kapi.kakao.com/v2/user/me' \ -H 'Authorization: Bearer ${ACCESS_TOKEN}' \ --data-urlencode 'secure_resource=true' \ --data-urlencode 'property_keys=["kakao_account.profile"]' ``` ### Response Body | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `id` | `Long` | 파트너사 앱 안에서 사용자를 식별하는 카카오 회원번호 | 항상 | | `connected_at` | `Datetime` | 앱과 연결된 시각 | 조건부 | | `synched_at` | `Datetime` | 카카오싱크 간편가입을 완료한 시각 | 조건부 | | `kakao_account` | `Object` | 사용자가 동의한 카카오계정 정보. 전체 필드는 [kakao\_account](https://developers.kakao.com/docs/ko/kakaologin/rest-api#kakaoaccount) 참고 | 조건부 | | `properties` | `Object` | 앱에서 관리하는 [사용자 프로퍼티](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#user-properties) | 조건부 | ```json { "id": 123456789, "connected_at": "2026-08-12T01:23:45Z", "synched_at": "2026-08-12T01:23:45Z", "kakao_account": { "profile_nickname_needs_agreement": false, "profile_image_needs_agreement": false, "profile": { "nickname": "게임플레이 사용자", "thumbnail_image_url": "https://example.kakaocdn.net/profile-thumbnail.jpg", "profile_image_url": "https://example.kakaocdn.net/profile.jpg" } } } ``` 동의항목을 `필수 동의`로 설정했더라도 사용자의 카카오계정에 값이 없으면 응답에 포함되지 않을 수 있습니다. 각 `*_needs_agreement` 값이 `true`이면 해당 정보는 사용자의 추가 동의 후 제공할 수 있습니다. ## 서비스 약관 동의 내역 조회 간편가입에 등록한 필수 서비스 약관에 모두 동의했는지 확인합니다. ```http GET https://kapi.kakao.com/v2/user/service_terms Authorization: Bearer ${ACCESS_TOKEN} ``` ### Request Query | 이름 | 타입 | 설명 | | --- | --- | --- | | `result` | `String` | `agreed_service_terms` 또는 `app_service_terms` | | `tags` | `String` | 조회할 서비스 약관 태그를 쉼표로 연결한 값. [서비스 약관 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#service-terms)에 등록한 태그입니다 | 간편가입 완료 여부는 [사용자 정보 조회](#사용자-정보-조회) 응답의 `synched_at`으로 먼저 확인할 수 있습니다. 값이 있으면 카카오싱크 간편가입을 거친 사용자입니다. 다만 `synched_at`은 가입 시점의 기록이므로 이후 필수 약관을 추가했다면 기존 사용자도 값이 남아 있습니다. 현재 시점의 필수 약관 동의 상태는 `result=app_service_terms`로 앱의 사용 중인 약관 전체를 조회하고 각 필수 약관의 `agreed` 값으로 확인합니다. ```bash curl -G 'https://kapi.kakao.com/v2/user/service_terms' \ -H 'Authorization: Bearer ${ACCESS_TOKEN}' \ --data-urlencode 'result=app_service_terms' ``` ### Response Body | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `id` | `Long` | 카카오 회원번호 | 항상 | | `service_terms` | `ServiceTerms[]` | 서비스 약관 동의 내역 | 조건부 | **`ServiceTerms`** | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `tag` | `String` | 간편가입 설정에 등록한 약관 태그 | 항상 | | `required` | `Boolean` | 필수 약관 여부 | 항상 | | `agreed` | `Boolean` | 사용자 동의 여부 | 항상 | | `revocable` | `Boolean` | 동의 철회 가능 여부 | 항상 | | `agreed_at` | `Datetime` | 마지막 동의 시각 | 조건부 | | `agreed_by` | `String` | `KAUTH` 또는 `KAPI` 동의 경로 | 조건부 | `tag`는 디벨로퍼스에 등록한 서비스 약관과 API 조회 결과를 연결하는 식별자입니다. 파트너사 서버에 저장한 약관 태그와 응답의 `tag`를 비교해 동의 상태를 판단합니다. 운영 중 디벨로퍼스의 약관 태그를 임의로 변경하면 기존 사용자의 동의 상태를 정확히 판단할 수 없으므로 서버에 저장한 값과 동일하게 유지하세요. ```json { "id": 123456789, "service_terms": [ { "tag": "service_terms", "required": true, "agreed": true, "revocable": true, "agreed_at": "2026-08-12T01:23:45Z", "agreed_by": "KAUTH" } ] } ``` 필수 약관의 `agreed`가 `false`이거나 목록에 없다면 서비스 회원 가입을 완료하지 않습니다. 필요한 약관 태그를 `service_terms`에 지정해 인가 코드 요청을 다시 수행하거나 파트너사 자체 약관 동의 화면을 제공합니다. ```text https://kauth.kakao.com/oauth/authorize ?response_type=code &client_id=${REST_API_KEY} &redirect_uri=${ENCODED_REDIRECT_URI} &service_terms=${REQUIRED_TERM_TAGS} &state=${STATE} ``` ## 토큰 갱신 액세스 토큰이 만료되기 전 또는 API에서 토큰 만료 응답을 받았을 때 리프레시 토큰으로 갱신합니다. ```http POST https://kauth.kakao.com/oauth/token Content-Type: application/x-www-form-urlencoded;charset=utf-8 ``` ### Request Body | 이름 | 타입 | 입력값 | 적용 여부 | | --- | --- | --- | --- | | `grant_type` | `String` | `refresh_token` 고정 | 필수 | | `client_id` | `String` | 파트너사 앱 REST API 키 | 필수 | | `refresh_token` | `String` | 토큰 발급 응답으로 받은 리프레시 토큰 | 필수 | | `client_secret` | `String` | REST API 키의 [클라이언트 시크릿](https://developers.kakao.com/docs/ko/app-setting/app#client-secret) | 기능 활성화 시 필수 | ```bash curl -X POST 'https://kauth.kakao.com/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded;charset=utf-8' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=${REST_API_KEY}' \ --data-urlencode 'refresh_token=${REFRESH_TOKEN}' \ --data-urlencode 'client_secret=${CLIENT_SECRET}' ``` ### Response Body | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `token_type` | `String` | `bearer` 고정 | 항상 | | `access_token` | `String` | 갱신된 액세스 토큰 | 항상 | | `expires_in` | `Integer` | 액세스 토큰 만료 시간(초) | 항상 | | `refresh_token` | `String` | 갱신된 리프레시 토큰 | 조건부 | | `refresh_token_expires_in` | `Integer` | 갱신된 리프레시 토큰 만료 시간(초) | 조건부 | 리프레시 토큰의 만료 시간이 1개월 이상 남아 있으면 응답에 새 리프레시 토큰이 포함되지 않습니다. 새 값이 포함된 경우에만 기존 리프레시 토큰을 교체하세요. 리프레시 토큰도 만료되었으면 게임 URL 진입 시 수행한 인가 코드 요청부터 다시 시작합니다. ## 액세스 토큰 정보 조회 액세스 토큰의 앱 ID, 사용자 회원번호, 남은 유효 시간을 확인할 때 사용합니다. 모든 API 호출 전에 선행할 필요는 없으며 운영상 토큰 상태 확인이 필요한 경우에만 사용합니다. ```http GET https://kapi.kakao.com/v1/user/access_token_info Authorization: Bearer ${ACCESS_TOKEN} ``` ```bash curl -G 'https://kapi.kakao.com/v1/user/access_token_info' \ -H 'Authorization: Bearer ${ACCESS_TOKEN}' ``` | 이름 | 타입 | 설명 | 제공 여부 | | --- | --- | --- | --- | | `id` | `Long` | 카카오 회원번호 | 항상 | | `expires_in` | `Integer` | 액세스 토큰 만료 시간(초) | 항상 | | `app_id` | `Integer` | 토큰이 발급된 앱 ID | 항상 | ## 게임 중 추가 동의 게임 플레이 중 새로운 `scope` 또는 서비스 약관 동의가 필요하면 현재 게임웹뷰를 직접 이탈시키지 않고 별도 인앱브라우저에서 인가 코드 요청을 수행합니다. 1. 추가 동의가 필요한 항목 ID 또는 서비스 약관 태그를 확인합니다. 2. 플랫폼에 맞는 인앱브라우저 열기 스킴으로 인가 코드 요청 URL을 엽니다. 3. `scope` 또는 `service_terms`에 필요한 값만 지정합니다. 4. Redirect URI에서 인가 코드와 `state`를 검증하고 토큰을 다시 발급합니다. 5. Redirect URI 페이지가 인앱브라우저 닫기 스킴을 실행해 기존 게임으로 복귀합니다. | 플랫폼 | 열기 스킴 | 닫기 스킴 | | --- | --- | --- | | iOS | `kakaotalk://inappbrowser?url={AUTHORIZE_URL}` | `kakaotalk://web/close` | | Android | `kakaotalk://web/open?url={AUTHORIZE_URL}` | `kakaotalk://web/close` | 동의항목 추가 동의는 [추가 항목 동의 받기](https://developers.kakao.com/docs/ko/kakaologin/utilize#additional-consent), 서비스 약관 추가 동의는 [서비스 약관 선택해 로그인하기](https://developers.kakao.com/docs/ko/kakaologin/utilize#login-serviceterms)의 요청 규격을 따릅니다. 닫기는 두 플랫폼 모두 `kakaotalk://web/close` 를 사용합니다. 이 스킴은 **호출한 웹뷰 자신**을 닫으므로, 게임웹뷰 위에 띄운 동의 창에서 호출하면 동의 창만 닫히고 게임웹뷰는 그대로 유지됩니다. 자세한 스킴 규격은 [게임웹뷰 SDK의 인앱브라우저 스킴](/api-sdk/sdk/kakaotalk-gameplay#인앱브라우저-스킴)을 참고하세요. ## 연결 해제 사용자의 파트너사 서비스 탈퇴와 앱 연결 해제는 [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)으로 처리됩니다. 앱 연결 해제는 카카오가 수행하므로, 파트너사가 연결 해제 API(`POST https://kapi.kakao.com/v1/user/unlink`)를 직접 호출하는 별도 연동은 필요하지 않습니다. 파트너사는 웹훅으로 전달되는 연결 해제 이벤트를 수신해 회원 정보 삭제와 게임 이용 데이터 파기, 내부 연결 상태 정리를 수행합니다. 파트너사 앱 하나에 여러 게임이 연결되어 있어도 카카오싱크 연결은 파트너사 앱 단위입니다. 연결 해제 시 파트너사의 모든 게임에서 서비스 이용이 해지된다는 점을 사용자에게 안내해야 합니다. 연결 해제 이벤트 수신·검증과 `reason`별 처리 기준은 [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)에서 확인하세요. ## 에러 처리 | 코드 | 발생 상황 | 처리 | | --- | --- | --- | | `access_denied` | 사용자가 동의 화면에서 취소 | 게임을 실행하지 않고 취소 안내를 표시합니다. | | `KOE006` | 디벨로퍼스에 등록하지 않은 Redirect URI로 인가 코드를 요청 | 디벨로퍼스에 등록한 값과 요청 값을 일치시킵니다. | | `KOE303` | 인가 코드 요청과 토큰 요청의 `redirect_uri`가 서로 다름 | 두 요청에 같은 Redirect URI를 사용합니다. | | `KOE237` | 토큰 발급 요청 수 제한 초과 | 즉시 반복 요청하지 않고 공식 문제 해결 가이드를 확인합니다. | | `-2` | 필수 파라미터 누락 또는 잘못된 값 | 요청 형식과 앱 설정을 확인합니다. | | `-401` | 유효하지 않거나 만료된 액세스 토큰 | 토큰을 갱신하고, 갱신할 수 없으면 인가 코드 요청부터 다시 시작합니다. | | `-402` | 필요한 동의항목 권한 부족 | `required_scopes`를 확인해 추가 동의를 요청합니다. | 카카오 API의 `-1`은 일시적인 내부 장애일 수 있습니다. 이 응답만으로 사용자를 로그아웃하거나 토큰을 즉시 폐기하지 말고 일시 오류로 처리합니다. ## 운영 적용 전 확인 * \[ ] 게임 URL 진입 시 로그인 버튼 없이 인가 코드 요청이 시작되는지 확인합니다. * \[ ] 인가 코드 요청에 `prompt=none`이 포함되지 않았는지 확인합니다. * \[ ] 앱 미동의 사용자에게 카카오싱크 동의 화면이 표시되는지 확인합니다. * \[ ] 동의 완료 사용자가 별도 화면 없이 파트너사 서비스 세션을 발급받는지 확인합니다. * \[ ] 인가 코드 콜백에서 `state`를 검증하는지 확인합니다. * \[ ] 카카오 회원번호로 기존 회원과 신규 회원을 정확히 분기하는지 확인합니다. * \[ ] 필수 서비스 약관 태그의 동의 상태를 서버에서 검증하는지 확인합니다. * \[ ] 새 리프레시 토큰이 응답에 있을 때만 저장 값을 교체하는지 확인합니다. * \[ ] 서비스 탈퇴·연결 해제를 계정 상태 변경 웹훅으로 수신해 회원 정보 삭제와 데이터 파기를 처리하는지 확인합니다. ## 참고 문서 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 비즈 앱·채널·동의항목·서비스 약관 설정 * [친구 목록 조회 API](/api-sdk/kakaotalk-social/friends): 친구 기능의 추가 동의와 친구 정보 조회 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 연결 해제 이벤트 수신·처리 * [게임웹뷰 SDK](/api-sdk/sdk/kakaotalk-gameplay): 인앱브라우저 열기·닫기 스킴 * [카카오싱크 개발 가이드](https://developers.kakao.com/docs/ko/kakaosync/dev-guide): 카카오 공식 가입·로그인 구현 흐름 * [카카오 로그인 REST API](https://developers.kakao.com/docs/ko/kakaologin/rest-api): 각 API의 전체 요청·응답 필드와 오류 코드 * 기술 문의 — [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/kakaotalk-social/friends.md description: 친구 목록 API와 친구 피커의 선택 기준 및 카카오톡 친구 목록 조회 REST API 핵심 스펙 --- # 친구 목록 조회 API 이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다. 실제 구현 전 반드시 [카카오톡 친구 목록 조회 REST API 공식 가이드](https://developers.kakao.com/docs/ko/kakaotalk-social/rest-api#get-friends)에서 최신 요청·응답 규격과 제약사항을 확인하세요. 파트너사 앱에 연결되고 친구 목록 제공에 동의한 사용자 사이의 친구 정보를 조회합니다. 친구 랭킹처럼 파트너사가 친구 데이터를 직접 구성하는 기능은 친구 목록 API를 사용하고, 사용자가 특정 친구를 고르는 기능은 친구 피커를 사용할 수 있습니다. > **관련 가이드**: [카카오싱크 설정의 친구 목록 조회](/docs/authentication/kakao-login-sync#친구-목록-조회)에서 동의항목 설정과 친구 정보 제공 조건을 먼저 확인하세요. ## 제공 방식 선택 | 방식 | 적합한 기능 | 제공 형태 | | --- | --- | --- | | 친구 목록 API | 게임 결과와 연계한 친구 랭킹 등 파트너사가 목록 UI와 데이터를 직접 구성하는 기능 | API 응답으로 친구 목록 제공 | | 친구 피커 | 메시지 전송 등 사용자가 특정 친구를 직접 선택하는 기능 | 카카오가 제공하는 피커 화면에서 선택한 친구 정보 제공 | 두 방식 모두 파트너사 앱에 연결되고 `friends` 동의항목에 동의한 친구만 제공합니다. 친구 피커는 사용자의 전체 카카오톡 친구를 보여주는 화면이 아니며, 파트너사 게임을 이용 중인 친구 중 친구 정보 제공 조건을 만족하는 사용자만 선택할 수 있습니다. ## 사전 조건 1. 카카오디벨로퍼스의 **\[앱] > \[추가 기능 신청]** 에서 `카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)` 사용 권한을 신청합니다. 신청 방법은 [개인정보 동의항목 추가 기능 신청](https://developers.kakao.com/docs/ko/kakaosync/prerequisite#additional-feature-request)을 참고하세요. 2. 사용 권한을 받은 뒤 **\[카카오 로그인] > \[동의항목]** 에서 동의 단계를 `선택 동의`로 설정합니다. 동의 단계의 의미는 [카카오 로그인 동의항목 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#scope-setting)을 참고하세요. 3. 친구 기능을 요청한 사용자가 `friends` 동의항목에 동의했는지 확인합니다. 4. 동의하지 않은 사용자는 [게임 중 추가 동의](/api-sdk/kakaosync/rest-api#게임-중-추가-동의) 흐름으로 `scope=friends` 동의를 요청합니다. API 응답에는 아래 조건을 모두 만족하는 친구만 포함됩니다. * 파트너사 앱에 연결된 사용자 * `friends` 동의항목에 동의한 사용자 * 조회 사용자의 숨김 또는 차단 친구가 아닌 사용자 * 프로필 공개 설정이 공개 상태인 사용자 조회 사용자도 `friends` 동의가 필요하므로, 결과적으로 파트너사 앱 가입자 사이에 쌍방 동의가 완료된 경우에만 친구 정보가 제공됩니다. ## Endpoint ```http GET https://kapi.kakao.com/v1/api/talk/friends ``` | 항목 | 값 | | --- | --- | | 인증 | 사용자 액세스 토큰 | | Authorization | `Bearer ${ACCESS_TOKEN}` | ## Request 주요 조회 옵션만 사용하고, 전체 파라미터와 정렬 정책은 [카카오톡 친구 목록 조회 REST API](https://developers.kakao.com/docs/ko/kakaotalk-social/rest-api#get-friends)를 참고하세요. | 이름 | 타입 | 설명 | | --- | --- | --- | | `offset` | `Integer` | 기본값 `0`친구 목록 시작 위치 | | `limit` | `Integer` | 기본값 `10`페이지당 친구 수. 최대 `100` | | `order` | `String` | 기본값 `asc`정렬 방향. `asc` 또는 `desc` | | `friend_order` | `String` | 기본값 `favorite`정렬 기준. `favorite` 또는 `nickname` | ```bash curl -G "https://kapi.kakao.com/v1/api/talk/friends" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -d "offset=0" \ -d "limit=20" \ -d "friend_order=nickname" ``` ## Response 응답의 `elements`에 제공 조건을 만족하는 친구 정보가 포함됩니다. 페이지 이동에는 `before_url`과 `after_url`을 사용합니다. | 필드 | 타입 | 설명 | | --- | --- | --- | | `elements` | `Friend[]` | 친구 정보 배열 | | `total_count` | `Integer` | 제공 가능한 전체 친구 수 | | `before_url` | `String` | 이전 페이지 URL | | `after_url` | `String` | 다음 페이지 URL | | `favorite_count` | `Integer` | 즐겨찾기 친구 수 | `Friend`의 주요 필드는 회원번호 `id`, 메시지 전송용 사용자 고유 ID `uuid`, 즐겨찾기 여부 `favorite`, 닉네임 `profile_nickname`, 프로필 썸네일 `profile_thumbnail_image`입니다. ```json { "elements": [ { "id": 123456789, "uuid": "sample-friend-uuid", "favorite": false, "profile_nickname": "게임친구", "profile_thumbnail_image": "https://example.com/profile.jpg" } ], "total_count": 1, "favorite_count": 0 } ``` ## 에러 | 상황 | 처리 | | --- | --- | | 액세스 토큰이 없거나 만료됨 | 유효한 사용자 액세스 토큰을 다시 발급한 뒤 요청합니다. | | 사용자가 `friends` 항목에 동의하지 않음 | 친구 기능 진입 시 추가 동의를 요청합니다. | | 예상한 친구가 응답에 없음 | 앱 연결, 쌍방 동의, 숨김·차단 여부, 프로필 공개 설정을 확인합니다. | ## 제약 조건 * 사용자의 전체 카카오톡 친구를 제공하는 API가 아닙니다. * 친구 목록 API와 친구 피커 모두 친구 정보 제공 조건을 만족하는 사용자만 제공합니다. * 친구 목록 응답은 10분 동안 캐시되므로 변경 사항이 즉시 반영되지 않을 수 있습니다. * 사용자가 선택 동의를 거부하거나 취소해도 친구 기능 외의 게임 이용은 계속할 수 있도록 예외 처리합니다. 세부 요청·응답 필드와 오류 코드는 [카카오톡 친구 목록 조회 REST API](https://developers.kakao.com/docs/ko/kakaotalk-social/rest-api#get-friends)를 참고하세요. ## 참고 문서 * [카카오싱크 설정](/docs/authentication/kakao-login-sync#친구-목록-조회) * [카카오싱크 API](/api-sdk/kakaosync/rest-api#게임-중-추가-동의) * [카카오톡 친구 피커](https://developers.kakao.com/docs/ko/kakaotalk-social/common#picker-friends) * [카카오톡 친구 정보 제공 조건](https://developers.kakao.com/docs/ko/kakaotalk-social/common#policy-friend) * [카카오톡 친구 목록 조회 REST API](https://developers.kakao.com/docs/ko/kakaotalk-social/rest-api#get-friends) * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/share/reward-result.md description: 카카오톡 공유 발생 후 카카오디벨로퍼스 연동으로 보상 가능 여부 판정 참고 데이터를 수신하는 방식 안내 --- # 공유 웹훅 연동 이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다. 실제 구현 전 반드시 [카카오톡 공유 웹훅 공식 가이드](https://developers.kakao.com/docs/ko/kakaotalk-share/callback)에서 최신 요청·응답·인증 규격과 제약사항을 확인하세요. 카카오톡 공유 발생 후 카카오디벨로퍼스 연동을 통해 보상 가능 여부 판정 참고 데이터를 수신할 수 있습니다. 파트너사는 이 문서의 규격을 참고해 수신 API 엔드포인트를 자체 구현하고, 카카오디벨로퍼스의 **\[앱] > \[웹훅] > \[카카오톡 공유 웹훅]** 에 수신 URL을 등록합니다. 웹훅 URL은 HTTPS와 443 포트만 등록할 수 있습니다. 공유 SDK 호출 시 `server_callback_args`에 담은 식별 값이 웹훅 본문으로 echo back되어, 카카오 서버가 공유 컨텍스트를 복원하고 보상 판정 참고 데이터를 파트너사 서버로 전달합니다. > **관련 가이드**: [공유 설정](/docs/share/settings) ## 파트너사 처리 요구사항 * 수신 API는 **3초 이내에 HTTP 상태 코드 2XX로 응답해야 합니다.** 권장이 아니라 필수 응답 규격입니다. * 3초 안에 처리를 끝낼 수 없다면 이벤트를 먼저 수신·저장해 응답하고 보상 판정은 비동기로 처리합니다. * 응답이 없거나 지연되면 재시도가 발생하므로, 같은 이벤트를 여러 번 받아도 결과가 같도록 멱등 처리합니다. ## 참고 문서 * [카카오톡 공유 웹훅](https://developers.kakao.com/docs/ko/kakaotalk-share/callback): 요청·응답·인증 상세 규격 * [공유 설정](/docs/share/settings): 공유 SDK 호출과 `server_callback_args` 구성 * [심사 체크리스트](/docs/checklist/review-checklist): 공유 관련 자체 점검 항목 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/data/terms-withdrawal.md description: 카카오 로그인 계정 상태 변경 웹훅으로 사용자의 동의 철회·연결 해제 이벤트를 수신해 데이터 파기를 처리하는 가이드 --- # 계정 상태 변경 웹훅 연동 이 문서는 게임플레이 파트너사의 연동에 필요한 카카오디벨로퍼스 공식 가이드 내용을 요약한 안내입니다. 실제 구현 전 반드시 [카카오 로그인 계정 상태 변경 웹훅 공식 가이드](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf)에서 최신 요청·응답·검증 규격과 제약사항을 확인하세요. 카카오가 파트너사 서버로 사용자의 카카오 로그인 계정 상태 변경 이벤트를 전달하는 웹훅입니다. 약관 동의 철회·연결 해제는 카카오디벨로퍼스에 등록하는 **카카오 로그인 계정 상태 변경 웹훅**으로 수신합니다. 약관 철회로 인한 파트너사 앱 연결 해제는 카카오가 대신 처리합니다. 파트너사는 웹훅으로 전달되는 연결 해제 이벤트를 수신해 **게임 이용 데이터 파기와 내부 상태 정리**를 수행합니다. 약관 철회로 연결 해제된 사용자와 개별 앱에서 연결 해제된 사용자를 같은 웹훅에서 함께 받아 처리할 수 있습니다. 파트너사는 `OAUTH: User Unlinked` 이벤트를 수신해 `reason`으로 약관 철회와 개별 앱 연결 해제를 구분하고, 데이터 파기와 내부 상태 정리를 수행합니다. > **관련 가이드**: [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정, [카카오싱크 API](/api-sdk/kakaosync/rest-api): 연결 해제 요청, [심사 체크리스트](/docs/checklist/review-checklist): 철회 처리 자체 점검 항목 ::: info 기존 약관 동의 철회 통지 API에서 전환 중이라면 파트너사 자체 구현 콜백으로 약관 동의 철회를 통지받던 파트너사는 [동의 철회·연결 해제 웹훅 (디벨로퍼스 마이그레이션 가이드)](/api-sdk/data/terms-withdrawal-migration)를 참고해 전환하세요. 연동 대상, `reason`별 처리 기준, 파트너사 처리 요구사항, 연동 흐름 등 상세 규격도 해당 가이드에서 확인할 수 있습니다. ::: ## 참고 문서 * [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf): SET 구조·검증·응답 규격 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정 * [카카오싱크 API](/api-sdk/kakaosync/rest-api): 서비스 탈퇴와 연결 해제 요청 * [동의 철회·연결 해제 웹훅 (디벨로퍼스 마이그레이션 가이드)](/api-sdk/data/terms-withdrawal-migration): 기존 연동 전환 안내 * [심사 체크리스트](/docs/checklist/review-checklist) * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/data/user-nicknames.md description: 파트너사가 회원번호 목록으로 게임플레이 프로필 닉네임을 일괄 조회하는 API --- # 사용자 닉네임 목록 조회 API 파트너사가 카카오 서버로 호출하는 API입니다. 전달한 회원번호(`user_ids`) 목록에 대해 각 사용자의 게임플레이 프로필 닉네임을 일괄 조회합니다. 게임 안에서 사용자 표기·랭킹에 카카오톡 게임플레이 닉네임을 그대로 사용할 때 씁니다. ## Endpoint ```http GET https://kapi.kakao.com/v1/gameplay/profiles ``` ## 요구 사항 * [카카오 로그인 사용 설정](https://developers.kakao.com/docs/ko/kakaologin/prerequisite#kakao-login-activate) ## 인증 파트너사 디벨로퍼스 앱의 [어드민 키](https://developers.kakao.com/docs/ko/app-setting/app#admin-key)로 인증합니다. | Header | 설명 | | --- | --- | | `Authorization` | 필수`KakaoAK {SERVICE_APP_ADMIN_KEY}`: 인증 방식, 서비스 앱 어드민 키로 인증 요청 | | `Content-Type` | 필수`application/x-www-form-urlencoded;charset=utf-8` | ::: danger 주의사항 어드민 키는 앱의 모든 권한을 가지므로 **어떤 경우에도 외부에 노출되면 안 됩니다.** 게임 클라이언트 번들·소스 저장소·로그에 키를 남기지 말고, 파트너사 서버의 환경 변수나 시크릿 저장소에서 주입합니다. 게임웹뷰에서 이 API를 직접 호출하면 요청 헤더에 키가 그대로 드러나므로, 반드시 파트너사 서버를 경유해 호출합니다. ::: ## Request 조회할 회원번호를 쿼리 파라미터로 전달합니다. | 파라미터 | 타입 | 설명 | | --- | --- | --- | | `user_ids` | `Long[]` | 필수게임플레이 프로필을 조회할 사용자의 회원번호 목록. 회원번호는 카카오계정과 앱이 연결될 때 부여하는 앱별 사용자 ID입니다. **최대 50개**이며, 초과하면 여러 번 나누어 호출합니다. | ```bash curl -G GET "https://kapi.kakao.com/v1/gameplay/profiles" \ -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \ --data-urlencode 'user_ids=[123456789,987654321]' ``` ## Response `200 OK`. | 필드 | 타입 | 제공 여부 | 설명 | | --- | --- | --- | --- | | `targets` | `GameplayProfileInfo[]` | 항상 | 조회된 게임플레이 프로필 목록. 조회된 프로필이 없으면 빈 배열 | **`GameplayProfileInfo`** | 필드 | 타입 | 제공 여부 | 설명 | | --- | --- | --- | --- | | `user_id` | `Long` | 항상 | 서비스 앱의 회원번호 | | `nickname` | `String` | 항상 | 게임플레이 프로필 닉네임 | **조회된 프로필이 있는 경우** ```json { "targets": [ { "user_id": 123456789, "nickname": "카카오프렌즈" }, { "user_id": 987654321, "nickname": "게임마스터" } ] } ``` **조회된 프로필이 없는 경우** ```json { "targets": [] } ``` ::: warning 주의사항 * **조회할 수 없는 사용자는 응답에서 제외됩니다.** 따라서 요청한 회원번호 개수와 `targets` 길이가 다를 수 있고, 하나도 조회되지 않으면 빈 배열이 옵니다. * **응답을 요청 목록의 인덱스(순번)와 1:1로 가정하면 어긋납니다.** 결과를 매칭할 때는 순번이 아니라 각 항목의 `user_id` 값을 키로 매핑해야 합니다. * 닉네임을 얻지 못한 사용자를 위해 게임 자체의 대체 표기(예: `user138531`)를 준비해 두는 것을 권장합니다. ::: ## 에러 응답 코드와 에러 코드는 카카오 API 공통 규격을 따릅니다. 상세는 [에러 코드](https://developers.kakao.com/docs/ko/rest-api/error-code#common)를 참고하세요. ## 참고 문서 * 게임플레이 파트너센터: 게임 정보 관리 * [액션데이터 API](/api-sdk/data/action-data): 사용자별 실제 랭킹 기록값 전송 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 회원번호 확보를 위한 인증·동의 설정 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/ads/cp-report.md description: 채널별 CP(Content Provider) 보고서를 조회하는 애드핏 External API --- # CP별 리포트 API 채널별 CP(Content Provider) 보고서를 조회하는 애드핏 External API입니다. 퍼블리셔가 API Key 인증으로 채널별 일간·월간 보고서 데이터를 조회할 수 있습니다. ## 리포트 설정값 게임별 광고 지표를 정확하게 조회하려면 CPID와 채널 ID를 아래 기준으로 설정해야 합니다. | 값 | 설정 기준 | | --- | --- | | **CPID** | 게임플레이 파트너센터에 등록한 게임 코드와 **동일한 값**을 입력합니다.메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 그대로 유지합니다. | | **채널 ID** | 카카오에서 발급한 값을 사용합니다.발급값 확인이 필요한 경우 카카오 담당자에게 문의하세요. | > **관련 가이드**: [광고 UX 가이드](/docs/ads/ux-guideline), [애드핏 설정](/docs/ads/iaa-options) ## Endpoint ```http GET https://adfit-external-api.kakao.com/publisher/v3/report/channel/{channel} ``` | 항목 | 값 | | --- | --- | | 환경 | Production 전용 | | 인증 | API Key (Query Parameter) | | Content-Type | `application/json` | ## API Key 발급 애드핏 프론트(`https://adfit.kakao.com`)에 로그인한 뒤 **보고서 > API 키 관리** 메뉴에서 발급받습니다. 메뉴가 보이지 않는 경우 애드핏에 문의합니다. * API Key는 퍼블리셔별로 발급됩니다 * 일일 요청 제한: **200회** ## Request ### Path Parameters | 이름 | 타입 | 설명 | | --- | --- | --- | | `channel` | `string` | 필수채널 ID.카카오에서 파트너사별로 발급하는 값 | ### Query Parameters | 이름 | 타입 | 포맷 | 설명 | | --- | --- | --- | --- | | `apikey` | `string` | — | 필수발급받은 API Key | | `fromDate` | `string` | `yyyy-MM-dd` 또는 `yyyy-MM` | 필수조회 시작일 | | `toDate` | `string` | `yyyy-MM-dd` 또는 `yyyy-MM` | 필수조회 종료일 | | `periodType` | `string` | `DAY` 또는 `MONTH` (대소문자 무관) | 기본값 `DAY`조회 단위 | ### 예시 ```bash # 일간 조회 (기본) curl -X GET "https://adfit-external-api.kakao.com/publisher/v3/report/channel/채널명\ ?apikey=YOUR_API_KEY&fromDate=2026-01-01&toDate=2026-01-31" # 월간 조회 curl -X GET "https://adfit-external-api.kakao.com/publisher/v3/report/channel/채널명\ ?apikey=YOUR_API_KEY&fromDate=2026-01&toDate=2026-06&periodType=MONTH" ``` ## Response ### 성공 (`200 OK`) 응답은 리포트 항목 배열이며 날짜 오름차순으로 정렬됩니다. ```json [ { "reportDate": "2025-01-02", "adunitId": "05d24", "adunitName": "광고단위명", "channel": "카카오에서 발급한 채널 ID", "cp": "파트너사가 설정한 게임 코드와 동일한 CPID", "adRequestCount": 0, "winCount": 0, "impressionCount": 1, "viewableImpressionCount": 0, "clickCount": 0, "profit": 0, "fillRate": 0, "vr": 0, "ctr": 0, "ecpm": 0 } ] ``` ### 필드 상세 | 필드 | 타입 | 설명 | 계산식 | | --- | --- | --- | --- | | `reportDate` | `string` | 조회 일자(`yyyy-MM-dd`) 또는 월(`yyyy-MM`) | — | | `adunitId` | `string` | 광고단위 ID | — | | `adunitName` | `string` | 광고단위명 | — | | `channel` | `string` | 카카오에서 발급한 채널 ID | — | | `cp` | `string` | 파트너사가 설정한 게임 코드와 동일한 CPID | — | | `adRequestCount` | `long` | 광고 요청 수 | — | | `winCount` | `long` | 광고 응답(낙찰) 수 | — | | `impressionCount` | `long` | 렌더드 노출 수 | — | | `viewableImpressionCount` | `long` | 노출 수 | — | | `clickCount` | `long` | 클릭 수 | — | | `profit` | `bigDecimal` | 적립금 (원) | — | | `fillRate` | `double` | Fill Rate (%) | `impressionCount / adRequestCount × 100` | | `vr` | `double` | Viewable Rate (%) | `viewableImpressionCount / impressionCount × 100` | | `ctr` | `double` | CTR (%) | `clickCount / viewableImpressionCount × 100` | | `ecpm` | `double` | eCPM | `profit / viewableImpressionCount × 1000` | 모든 필드는 항상 응답에 포함됩니다. 데이터가 없는 경우 숫자 필드는 `0`, 비율 필드는 `0.0`으로 반환됩니다. ## 에러 에러 발생 시 아래 형식으로 응답합니다. ```json { "message": "에러 메시지", "details": null, "code": "ERROR_CODE" } ``` ### 주요 에러 케이스 | HTTP | 메시지 | 원인 | | --- | --- | --- | | `400` | 파라미터 형식이 잘못되었습니다. 사용 가능한 값: `yyyy-MM-dd`, `yyyy-MM` | 날짜 포맷 오류 | | `400` | 허용된 조회 기간을 초과하였습니다. (일: 90일, 월: 12개월) | 조회 기간 초과 | | `400` | 허용되지 않은 기간 유형입니다. | `periodType` 값 오류 | | `401` | — | API Key 인증 실패 | | `403` | — | 권한 없음 또는 IP 차단 | ## 제약 조건 | 항목 | 제한 | | --- | --- | | 일간 조회 기간 | 최대 90일 (`periodType=DAY`) | | 월간 조회 기간 | 최대 12개월, 365일 (`periodType=MONTH`) | | 날짜 순서 | `fromDate ≤ toDate` | | 일일 요청 수 | 200회 (퍼블리셔 API Key 기준) | | 정렬 | 응답은 날짜 오름차순 | ## 참고 문서 * [애드핏 광고 SDK](/api-sdk/sdk/adfit) * [애드핏 설정](/docs/ads/iaa-options) * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/share/short-url.md description: 카카오톡 공유 SDK 호출 전에 공유용 단축 URL을 발급하는 API --- # 단축 URL 생성 공유 피커에서 URL 복사 기능을 사용하려면 공유 SDK 호출 전에 단축 URL을 발급받아야 합니다. 응답의 `short_url`을 공유 SDK 호출 시 `templateArgs.BUTTON_URL`과 `pickerSettings.args.copy_url`에 주입합니다. > **관련 가이드**: [공유 설정](/docs/share/settings) ## Endpoint ```http GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url ``` ## 헤더 | Header | 설명 | | --- | --- | | `Authorization` | 필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키 | | `Content-Type` | 필수`application/json` | ## 인증 * Authorization 헤더의 APP\_KEY 검증 * IP ACL 기반(사전 등록된 IP만 허용) 이중 인증 파트너사 정보 전달 양식에서 제출한 IP를 사용합니다. ## 파라미터 | 위치 | 이름 | 타입 | 설명 | | --- | --- | --- | --- | | path | `gameCode` | `string` | 필수파트너사 기준 게임 ID | | query | 파트너사 정의 키 | `string` | 공유 링크에 실어 게임으로 다시 전달할 딥링크 파라미터. `key=value` 형태로 0~N개 전달합니다. 제약은 [딥링크 파라미터](#딥링크-파라미터)를 참고하세요. | 전달한 딥링크 파라미터는 발급된 단축 URL에 포함되어, 사용자가 공유 링크로 게임에 진입할 때 게임으로 다시 전달됩니다. 파라미터를 전달하지 않으면 기존과 동일하게 동작합니다(하위 호환). ### 딥링크 파라미터 게임 진입 시 함께 넘기고 싶은 값을 쿼리 파라미터로 전달하면, 카카오가 검증한 뒤 공유 링크에 추가합니다. 아래 제약을 벗어나면 `-2` 에러가 반환됩니다. | 제약 항목 | 값 | | --- | --- | | 예약 키(사용 불가) | `referer`, `t_src`, `t_ch`, `t_obj` (대소문자 무시) | | 키 허용 문자 | `A~Z`, `a~z`, `0~9`, `_`, `-` | | 최대 파라미터 개수 | 20개 | | 키 최대 길이 | 64자 | | 값 최대 길이 | 512자 | | 파라미터 전체 길이 | 2,048자 | | 값 인코딩 | UTF-8 URL 인코딩되어 추가됩니다 | | 동일 키 중복 | 첫 번째 값만 사용합니다 | 예약 키(`referer`·`t_src`·`t_ch`·`t_obj`)는 카카오 공유 트래킹용으로 예약되어 있어 파트너사 파라미터로 사용할 수 없습니다. **요청 예시** ```http GET https://pf-external-api.kakao.com/v1/api/gameplay/games/{gameCode}/short-url?stage=3&invite=abc123 ``` 위 요청으로 발급한 단축 URL로 사용자가 진입하면 `stage=3`·`invite=abc123`이 게임으로 전달됩니다. ## 응답 ```json { "short_url": "https://gameplay.kakao.com/s/xxxxxxx" } ``` ## 에러 코드 | code | 설명 | | --- | --- | | `-2` | `gameCode`가 전달되지 않았거나, 딥링크 파라미터가 [제약](#딥링크-파라미터)을 벗어난 경우(예약 키 사용, 허용 문자 위반, 개수·길이 초과 등) | | `-852` | `gameCode`로 조회되는 게임이 없는 경우 | | `-900` | 허용되지 않은 IP에서 접근한 경우 | ## Rate Limit 모든 API에 공통으로 요청 IP 기준 Rate Limit이 적용됩니다. | 항목 | 값 | | --- | --- | | 제한 기준 | 요청 IP 단위 | | 허용량 | 최대 1,000 RPS | | Burst | 순간 최대 2,000 requests | 제한 초과 시 `503 Service Temporarily Unavailable`이 반환됩니다. ## 참고 문서 * [공유 설정](/docs/share/settings): 공유 SDK 호출과 단축 URL 적용 위치 * [공유 웹훅 연동](/api-sdk/share/reward-result): 공유 성공 후 파트너사 서버로 결과 통지 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/data/metadata.md description: 게임플레이 파트너센터 오픈과 함께 사용이 중지되는 게임 메타 정보 API와 랭킹 데이터 스펙 --- # 메타데이터 API (사용 중지 예정) 기존 연동 파트너사가 카카오(게임플레이) 서버로 호출해 게임 정보를 관리하던 API입니다. 등록·수정·단건 조회·목록 조회 4개 엔드포인트를 제공하며, 파트너센터 오픈과 함께 사용이 중지됩니다. ::: warning 사용 중지 안내 게임플레이 파트너센터가 오픈하면 메타데이터 API 호출은 오류로 응답되며, 게임 정보를 등록·수정할 수 없습니다. 파트너센터 오픈 시점부터는 게임 정보를 변경할 때 업데이트 심사를 반드시 거쳐야 하므로, 심사를 건너뛰는 API 경로는 제공하지 않습니다. 신규 파트너사는 이 API를 연동하지 않고 현재 가이드에 따라 입점을 준비한 뒤, 파트너센터 오픈 후 게임 정보를 등록하고 출시 심사를 요청하세요. 기존 연동 파트너사는 오픈 전까지 기존 API와 기존 심사 절차를 사용합니다. 아래 스펙은 오픈 전까지 운영 중인 연동을 유지하기 위한 참고 자료입니다. ::: > **관련 가이드**: [심사 가이드](/docs/checklist/review-guide): 파트너센터 출시·업데이트 심사 절차 ## API 목록 | 이름 | Method | Path | | --- | --- | --- | | 신규 등록 | `POST` | `/v1/api/gameplay` | | 수정 | `PUT` | `/v1/api/gameplay` | | 단건 조회 | `GET` | `/v1/api/gameplay/games/{gameCode}` | | 목록 조회 | `GET` | `/v1/api/gameplay/games` | ## 공통 ### Base URL ```http https://pf-external-api.kakao.com ``` ### 헤더 | Header | 설명 | | --- | --- | | `Authorization` | 필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키 | | `Content-Type` | 필수`application/json` | ### 인증 * `Authorization` 헤더의 APP\_KEY 검증 * IP ACL 기반(사전 등록된 IP만 허용) 이중 인증. 파트너사 정보 전달 양식에서 제출한 IP 사용 ### Rate Limit | 항목 | 값 | | --- | --- | | 제한 기준 | 요청 IP 단위 | | 허용량 | 최대 1,000 RPS | | Burst | 순간 최대 2,000 requests | 제한 초과 시 `503 Service Temporarily Unavailable`이 반환됩니다. ### 공통 에러 코드 | code | 설명 | | --- | --- | | `-900` | 허용되지 않은 IP에서 접근 | 각 API별 추가 에러 코드는 아래 각 섹션을 참고하세요. ## 게임 메타 신규 등록 파트너사가 신규 게임을 등록하는 시점에 호출합니다. ```http POST /v1/api/gameplay ``` ### Request Body | 필드 | 타입 | 설명 | | --- | --- | --- | | `code` | `string` | 필수게임별 고유 키. 최대 25자. **광고의 CPID와 반드시 동일해야 함** | | `name` | `string` | 필수타이틀. 최대 30자 | | `description` | `string` | 필수세부 설명. 최대 50자 | | `thumbnail` | `object` | 필수썸네일 정보. [thumbnail 객체](#thumbnail) 참고 | | `link` | `string` | 필수랜딩 URL. 최대 100자 | | `genre` | `object` | 필수장르. [genre 객체](#genre) 참고 | | `play_mode` | `string` | 필수플레이 방식. [play\_mode 정의](#play-mode) 참고 | | `ranking` | `object` | 필수랭킹 메타. [ranking 객체](#ranking) 참고. 랭킹 미사용 게임도 `enabled: false`로 필수 전달 | | `display_info` | `object` | 필수게임 표시 정보. [display\_info 객체](#display-info) 참고 | ### thumbnail | 필드 | 타입 | 설명 | | --- | --- | --- | | `square` | `string` | 정사각형 이미지 URL. `640 × 640` (1:1), 200 KB 이하 | | `wide` | `string` | 와이드 이미지 URL. `1200 × 630` (1.91:1), 1 MB 이하 | 카카오가 전달받은 URL에서 이미지를 다운로드해 카카오 CDN에 업로드합니다. 이미지 도메인은 사전에 카카오에 전달해 외부 프록시 화이트리스트 등록이 필요합니다. ### genre | 필드 | 타입 | 설명 | | --- | --- | --- | | `main` | `string` | 메인 장르 | | `subs` | `string[]` | 서브 장르. 최대 2개 | 메인과 동일한 값을 서브에 포함할 수 없습니다. **장르 코드** | 값 | 설명 | | --- | --- | | `PUZZLE` | 퍼즐 | | `ACTION` | 액션 | | `SHOOTING` | 슈팅 | | `STRATEGY` | 전략 | | `SIMULATION` | 시뮬 | | `RPG` | RPG | | `ADVENTURE` | 어드벤쳐 | | `ARCADE` | 아케이드 | | `BOARD` | 보드 | | `QUIZ` | 퀴즈 | | `SPORTS` | 스포츠 | | `RACING` | 레이싱 | ### display\_info 게임산업진흥법 시행령 별표 3에 따른 법정 표시 의무 항목입니다. | 필드 | 타입 | 설명 | | --- | --- | --- | | `age_rating` | `string` | 필수이용 등급 | | `rating_classification_number` | `string` | 필수등급 분류 결정서의 고유 번호. 최대 30자 (예: 게임물관리위원회 `CC-OM-260204-002`, 구글플레이스토어 `GOOG-SG-250418-0164`) | | `rating_classification_date` | `string` | 필수등급 분류 일자. `YYYY-MM-DD` | | `corporate_name` | `string` | 필수상호. 게임 심의를 받은 자(배급업자 또는 제작업자)의 상호로, 게임별로 다를 수 있음. 최대 50자 | | `business_registration_number` | `string` | 필수제작·배급업 등록(신고) 번호. 게임산업진흥법 제25조에 따라 시·군·구청에 등록·신고한 번호(자유 형식). 회사가 동일하면 게임 간 번호가 같을 수 있음. 최대 30자 (예: `2025-서울강남-06282`) | | `content_descriptors` | `string[]` | 필수게관위 등급 분류 결정서의 게임물 내용 정보. 최대 7개. 해당 항목 없으면 빈 배열 | | `has_probability_item` | `boolean` | 필수게임 내 확률형 아이템 포함 여부 | | `additional_notice` | `string` | 기타 고지사항. 최대 50자 (배급자 정보 등) | **`age_rating`** | 값 | 설명 | | --- | --- | | `ALL` | 전체 이용가 | | `AGE_12` | 12세 이용가 | | `AGE_15` | 15세 이용가 | | `ADULT` | 청소년 이용 불가 | **`content_descriptors`** | 값 | 설명 | | --- | --- | | `SEXUAL` | 선정성 | | `VIOLENT` | 폭력성 | | `FEAR` | 공포 | | `LANGUAGE` | 언어의 부적절성 | | `DRUG` | 약물 | | `CRIME` | 범죄 | | `GAMBLING` | 사행성 | 전체 이용가 게임이라도 해당 내용이 있으면 표시 의무가 있으므로 누락 없이 전달합니다. ### Response `200 OK` (본문 없음) ### 에러 | code | 설명 | | --- | --- | | `-850` | 이미 등록된 게임 (`code` 중복) | | `-900` | 허용되지 않은 IP | ## 게임 메타 수정 ```http PUT /v1/api/gameplay ``` Request Body는 [신규 등록](#request-body)과 동일합니다. **변경되지 않은 필드 값도 모두 전달해야 하며**, 수정된 값이 하나도 없으면 에러가 발생합니다. ### Response `200 OK` ### 에러 | code | 설명 | | --- | --- | | `-851` | 변경된 내역이 없음 | | `-852` | 해당 게임이 존재하지 않음 | | `-900` | 허용되지 않은 IP | ## 게임 메타 단건 조회 `gameCode`로 파트너사 vendor의 등록 게임 1건을 조회합니다. ```http GET /v1/api/gameplay/games/{gameCode} ``` ### Path Parameter | 이름 | 타입 | 설명 | | --- | --- | --- | | `gameCode` | `string` | 필수등록 시 전달한 `code` 값 | ### Response ```json { "code": "my_game_001", "name": "샘플 게임", "description": "샘플 설명", "thumbnail": { "square": "https://vendor-cdn.example.com/games/my_game_001/square.png", "wide": "https://vendor-cdn.example.com/games/my_game_001/wide.png" }, "link": "https://vendor-game.example.com/h5/my_game_001", "genre": {"main": "PUZZLE", "subs": ["ACTION"]}, "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-002", "rating_classification_date": "2026-02-04", "corporate_name": "샘플게임즈", "business_registration_number": "2025-서울강남-06282", "content_descriptors": [], "has_probability_item": false, "additional_notice": null }, "status": "ON" } ``` `thumbnail`은 등록 시 전달한 원본 URL이 반환됩니다 (카카오 CDN 업로드본 아님). **`status`** | 값 | 설명 | | --- | --- | | `ON` | 서비스 중 | | `OFF` | 비활성 | | `QA` | QA 단계 (운영 환경 미노출) | | `DELETED` | 삭제됨 | | `UNKNOWN` | 미정 | ### 에러 | code | 설명 | | --- | --- | | `-2` | vendor 미등록 caller | | `-852` | 본인 vendor의 등록 게임 중 `gameCode` 매칭 없음 | | `-900` | 허용되지 않은 IP | ## 게임 메타 목록 조회 본인 vendor가 등록한 게임 메타 정보를 모두 조회합니다. ```http GET /v1/api/gameplay/games ``` 별도 파라미터 없이 caller APP\_KEY의 vendor로 스코프가 자동 한정됩니다. ### Response [게임 메타 단건 조회](#게임-메타-단건-조회)의 Response Body 배열 형태입니다. * 정렬: 최신 등록순 (`createdAt DESC`) * `status = DELETED`인 게임은 제외 ```json [ {"code": "my_game_002", "name": "신규 게임", "status": "OFF"}, {"code": "my_game_001", "name": "샘플 게임", "status": "ON"} ] ``` ### 에러 | code | 설명 | | --- | --- | | `-2` | vendor 미등록 caller | | `-900` | 허용되지 않은 IP | ## 랭킹 데이터 스펙 ::: warning 랭킹 노출은 사전 조율 후 확정됩니다 `ranking.enabled: true`로 설정해도 모든 게임이 게임플레이 랭킹 영역(리더보드)에 노출되는 것은 아닙니다. 카카오가 전송된 기록값 데이터를 확인하고 파트너사와 사전 조율을 거쳐 노출 대상과 시점을 확정합니다. 랭킹 설정과 기록값 전송은 노출을 위한 데이터 준비 단계이며, 노출 스펙은 추후 변경될 수 있습니다. 게임 내 자체 랭킹은 이와 무관하게 자유롭게 구현할 수 있습니다. ::: 게임플레이 서비스 내 랭킹 영역에 게임별 랭킹을 노출하려면 다음 두 데이터가 매칭되어야 합니다. 랭킹 설정은 파트너센터에 입력하며, 아래 `ranking` 스펙은 파트너센터 오픈 전까지 기존 연동을 유지하기 위한 참고 자료입니다. | 구분 | 설명 | 전달 시점 | | --- | --- | --- | | 파트너센터 랭킹 설정오픈 전: 메타데이터 `ranking` | 플레이 방식, 랭킹 사용 여부, 산정 기준 | 게임 등록·수정 시 | | 사용자 [액션데이터 API](/api-sdk/data/action-data) | 사용자 플레이 실제 기록값 | 플레이 시작·완료·종료 시 | 파트너센터에 설정한 랭킹 기준과 액션데이터의 기록값이 일치해야 랭킹 집계가 가능합니다. 파트너센터 오픈 전까지는 메타데이터 API로 설정한 기준이 기준값이 됩니다. ### `play_mode` 게임 구조를 설명하는 값이며, 실제 랭킹 산정 기준은 `ranking.metrics`에서 별도 정의합니다. | 값 | 설명 | | --- | --- | | `ROUND` | 단판형 게임 | | `STAGE` | 스테이지형 게임 | | `TIME_ATTACK` | 타임어택형 게임 | | `LEVEL` | 레벨형 게임 | ### `ranking` | 필드 | 타입 | 설명 | | --- | --- | --- | | `enabled` | `boolean` | 필수랭킹 사용 여부 | | `metrics` | `object[]` | 랭킹 산정 기록값 목록. 1개만 지원. **`enabled: true`일 때 필수** | | `period_types` | `string[]` | 제공할 랭킹 기간. **`enabled: true`일 때 필수** | | `default_period_type` | `string` | 기본 랭킹 기간. 허용값은 [period\_types](#period-types)와 동일. **`enabled: true`일 때 필수** | 랭킹 미사용 게임은 `ranking.enabled: false`만 전달하고 나머지 하위 필드는 생략할 수 있습니다. ### `metrics` | 필드 | 타입 | 설명 | | --- | --- | --- | | `type` | `string` | 필수기록값 유형 | | `order` | `string` | 필수정렬 방향 | **`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` 외 기간 랭킹이 필요한 경우 * 실시간·시즌·보상 지급용 등 별도 랭킹 정책이 필요한 경우 사전 협의 없이 정의되지 않은 값을 전달하면 랭킹 노출이 제한되거나 데이터가 정상 집계되지 않을 수 있습니다. ## 참고 문서 * [액션데이터 API](/api-sdk/data/action-data): 사용자별 실제 랭킹 기록값 전송 * 게임플레이 파트너센터: 신규 게임 정보 등록·수정 및 심사 요청 * [데이터 샘플 카탈로그](/api-sdk/data/samples#메타데이터-샘플-사용-중지-예정): 기존 파트너용 게임 유형별 등록 요청 본문 예시 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal) * [심사 가이드](/docs/checklist/review-guide) * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /api-sdk/data/action-data.md description: 사용자별 게임 액션데이터 단건·일괄 전송 API --- # 액션데이터 API 파트너사가 카카오(게임플레이) 서버로 사용자별 게임 액션데이터를 전송하는 API입니다. 단건과 일괄(Batch) 두 방식을 제공합니다. 본 스펙은 대표 가이드이며, 실제 적용 시 파트너사별 협의를 통해 세부 사항이 조정될 수 있습니다. > **관련 가이드**: [심사 가이드](/docs/checklist/review-guide), [심사 체크리스트](/docs/checklist/review-checklist) ## API 목록 | 이름 | Method | Path | | --- | --- | --- | | 단건 전달 | `POST` | `/v1/api/gameplay/events` | | 일괄 전달 (Batch) | `POST` | `/v1/api/gameplay/events/batch` | ## 공통 ### Base URL ```http https://pf-external-api.kakao.com ``` ### 헤더 | Header | 설명 | | --- | --- | | `Authorization` | 필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키 | | `Content-Type` | 필수`application/json` | ### 인증 * `Authorization` 헤더의 APP\_KEY 검증 * IP ACL 기반(사전 등록된 IP만 허용) 이중 인증 ### Rate Limit | 항목 | 값 | | --- | --- | | 제한 기준 | 요청 IP 단위 | | 허용량 | 최대 1,000 RPS | | Burst | 순간 최대 2,000 requests | 제한 초과 시 `503 Service Temporarily Unavailable`이 반환됩니다. 대량 데이터를 전송할 때는 일괄 전달 API를 활용하거나 요청 간격을 조절합니다. ## 이벤트 스키마 두 API 모두 아래 스키마의 이벤트 객체를 사용합니다. | 필드 | 타입 | 설명 | | --- | --- | --- | | `app_id` | `string` | 필수파트너사 앱 ID | | `log_id` | `string` | 필수액션데이터 고유 ID. UUID 형식 | | `action_type` | `string` | 필수`enter` / `play` / `load` / `receive` | | `app_user_id` | `long` | 필수사용자 `appUserId` | | `category` | `string` | 필수고정값 `h5` | | `client_ip` | `string` | 필수사용자 접속 IP | | `code` | `string` | 필수액션데이터 구분 코드. 고정값 `action` | | `game_id` | `string` | 필수게임플레이 파트너센터에 등록한 게임 코드와 동일한 게임 고유 ID | | `label` | `string` | 필수아래 label 매트릭스 참고 | | `os` | `string` | 필수OS 환경. 허용값 `js` | | `platform` | `string` | 필수플랫폼 환경. 허용값 `web` | | `player_id` | `string` | 필수게임 내 사용자 고유 ID | | `session_id` | `string` | 필수세션 ID. UUID 형식 | | `timestamp` | `long` | 필수액션 발생 시각 (Unix ms) | | `play_time` | `long` | 게임 체류시간 (ms). **`Exit_Play`에서 필수**. `Loading` ~ `Exit_Play`까지 누적 체류시간을 파트너사가 직접 계산해 전달합니다 | | `action_data` | `object` | 종료 시점 결과값. 키는 `metrics.type` 사용. 랭킹을 사용하는 경우 `Complete_Play`·`Exit_Play`에서 전달하고, 랭킹을 사용하지 않거나 부득이하게 결과값 전송이 어려운 경우 없이 전달할 수 있습니다 | `action_data`의 키는 파트너센터에 설정한 랭킹 지표와 정확히 일치해야 랭킹이 집계됩니다. 파트너센터 오픈 전까지 메타데이터 API로 연동한 파트너사는 `ranking.metrics.type`과 같은 값을 사용합니다. 랭킹 기록은 게임에서 대표로 삼을 **메인 모드 한 가지**에 대해서만 전달합니다. 여러 모드·기록값이 있어도 랭킹에 표시할 대표 요소 하나를 정해 그 결과값만 `action_data`로 보냅니다. 랭킹 노출은 기록값 전달만으로 확정되지 않으며, 카카오가 데이터를 심사하고 파트너사와 사전 조율을 거쳐 확정합니다. 랭킹 설정 항목과 기록값 허용치는 [랭킹 데이터 스펙](/api-sdk/data/metadata#랭킹-데이터-스펙)을 참고하세요. ## label 매트릭스 | `label` | `action_type` | 설명 | | --- | --- | --- | | `Loading` | `enter` | 세션 최초 진입 (1회) | | `Complete_Loading` | `enter` | **게임 로딩 완료**. 세션마다 1회 필수 전달합니다 | | `Start_Play` | `play` | 플레이 1판 시작 | | `Complete_Play` | `play` | **랭킹에 기록할 한 판(라운드/스테이지)의 정상 완료 시점**. 랭킹을 사용하는 경우 랭킹에 표시할 메인 모드에 한해 `action_data`와 함께 전달합니다. 스테이지 실패 등 랭킹에 기록하지 않아야 하는 경우에는 `Complete_Play`를 전달하지 않습니다. 라운드·스테이지·판 단위가 없는 무한형 게임(방치형·끝없는 진척형 등)은 파트너사가 자체 정의한 의미 있는 진척 시점(예: 시설 건설, 보스 처치, 일정 점수 도달)에 전달합니다 | | `Exit_Play` | `play` | **게임 세션 종료**. 사용자가 웹뷰를 닫거나 뒤로가기·X 버튼 등으로 게임을 떠난 시점. 한 세션에 1회 발생하며 `play_time`은 필수입니다. 랭킹을 사용하는 경우 `action_data`도 함께 전달하며, 랭킹을 사용하지 않거나 비정상 종료로 결과값 확보가 불가한 경우 생략할 수 있습니다 | | `Ad_Reward_Loaded` | `load` | 보상형 광고 로드 완료 | | `Ad_Reward_Start` | `enter` | 보상형 광고 시청 시작 | | `Ad_Reward_Received` | `receive` | 보상형 광고 리워드 수령 | | `Ad_Normal_Loaded` | `load` | 비보상형 광고 로드 완료 | | `Ad_Normal_Start` | `enter` | 비보상형 광고 시청 시작 | `Complete_Play`와 `Exit_Play`는 단위가 다른 별개 이벤트입니다. 한 세션 안에서 여러 판을 플레이한 경우 `Complete_Play`는 정상 완료한 판 수만큼, `Exit_Play`는 1회 발생합니다. ## 작성 시 주의사항 * `Complete_Loading`은 게임 로딩 완료 시점에 세션마다 1회 필수로 전달합니다. * `play_time`은 파트너사가 `Loading` ~ `Exit_Play`까지 누적 체류시간(ms)을 직접 계산합니다. * 랭킹 기록은 대표 메인 모드 하나의 결과값만 `action_data`로 전달합니다. `Complete_Play` · `Exit_Play`의 전달 조건은 [label 매트릭스](#label-매트릭스)를 참고하세요. ## 단건 전달 ```http POST /v1/api/gameplay/events ``` ### Response ```json {"success": true} ``` 실패 시: ```json { "success": false, "error_code": -852, "error_message": "game not exist" } ``` **응답 필드** | 필드 | 타입 | 설명 | | --- | --- | --- | | `success` | `boolean` | 필수이벤트 처리 성공 여부 | | `error_code` | `int` | 실패 시 에러 코드 | | `error_message` | `string` | 실패 시 에러 메시지 | ### 이벤트 처리 에러 코드 | code | 설명 | | --- | --- | | `-2` | 유효하지 않은 파라미터 | | `-543` | 사용자 미존재 | | `-852` | 게임 미존재 | | `-1` | 내부 서버 오류 | ### 요청 자체 에러 요청 자체가 유효하지 않으면 응답 본문이 아닌 예외로 반환됩니다. | code | 설명 | | --- | --- | | `-2` | 요청 파라미터 오류 (null body 등) | | `-900` | 허용되지 않은 IP | ## 일괄 전달 (Batch) ```http POST /v1/api/gameplay/events/batch ``` ### Request Body 이벤트 객체의 JSON Array로 전달합니다. | 항목 | 값 | | --- | --- | | 형식 | 이벤트 객체 배열 | | 최대 건수 | **100건** (`1 ≤ size ≤ 100`) | 100건을 초과하면 요청 자체가 에러 처리됩니다. ### Response ```json { "results": [ {"index": 0, "success": true}, { "index": 1, "success": false, "error_code": -852, "error_message": "game not exist" }, {"index": 2, "success": true} ] } ``` `results`는 요청 배열과 동일한 순서로 반환됩니다. **EventResult 객체** | 필드 | 타입 | 설명 | | --- | --- | --- | | `index` | `int` | 필수요청 배열 내 인덱스 (0-based) | | `success` | `boolean` | 필수해당 이벤트 처리 성공 여부 | | `error_code` | `int` | 실패 시 에러 코드 | | `error_message` | `string` | 실패 시 에러 메시지 | ### 이벤트 처리 에러 코드 단건 전달과 동일합니다 (`-2`, `-543`, `-852`, `-1`). ### 요청 자체 에러 | code | 설명 | | --- | --- | | `-2` | 요청 파라미터 오류 (빈 배열, 100건 초과 등) | | `-1` | 내부 서버 오류 | | `-900` | 허용되지 않은 IP | ## 참고 문서 * 게임플레이 파트너센터: 게임 코드와 랭킹 설정 확인 * [메타데이터 API](/api-sdk/data/metadata): 사용 중지 예정 API 의 게임 정보·랭킹 스펙 · 랭킹 데이터 스펙 * [데이터 샘플 카탈로그](/api-sdk/data/samples#액션데이터-샘플): 시나리오별 요청 본문·Batch 예시 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 동의 철회·연결 해제 이벤트 수신 처리 * [Tiara Web SDK](/api-sdk/sdk/tiara-web): 게임 로그 수집·전송 * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- 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) --- --- url: /api-sdk/data/terms-withdrawal-migration.md description: 기존 약관 동의 철회 통지 API를 카카오 로그인 계정 상태 변경 웹훅으로 전환하기 위한 마이그레이션 전용 가이드 --- # 동의 철회·연결 해제 웹훅 (디벨로퍼스 마이그레이션 가이드) ::: info 디벨로퍼스 마이그레이션 가이드 이 문서는 기존 약관 동의 철회 통지 API(파트너사 자체 구현 콜백)를 카카오디벨로퍼스 [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf)으로 전환하기 위한 **마이그레이션 전용 가이드**입니다. 앞으로 제공될 디벨로퍼스 문서로 대체될 예정이며, 그때까지만 제공됩니다. 전환을 마친 뒤의 최신 규격은 [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)을 참고하세요. ::: 카카오가 파트너사 서버로 사용자의 카카오 로그인 계정 상태 변경 이벤트를 전달하는 웹훅입니다. 기존의 약관 동의 철회 통지 API(파트너사 자체 구현 콜백)는 디벨로퍼스에 등록하는 **카카오 로그인 계정 상태 변경 웹훅** 기반 연동으로 변경됩니다. 약관 철회로 인한 파트너사 앱 연결 해제는 카카오가 대신 처리합니다. 파트너사는 웹훅으로 전달되는 연결 해제 이벤트를 수신해 **게임 이용 데이터 파기와 내부 상태 정리**를 수행합니다. 약관 철회로 연결 해제된 사용자와 개별 앱에서 연결 해제된 사용자를 같은 웹훅에서 함께 받아 처리할 수 있습니다. > **관련 가이드**: [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정, [카카오싱크 API](/api-sdk/kakaosync/rest-api): 연결 해제 요청, [심사 체크리스트](/docs/checklist/review-checklist): 철회 처리 자체 점검 항목 요청 본문(SET) 구조, 서명 검증, 성공/실패 응답 규격은 [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf) 문서의 최신 내용을 따릅니다. 이 페이지는 게임플레이 파트너사의 처리 기준만 정의합니다. ## 변경 개요 | 항목 | 기존 방식 | 변경 후 | | --- | --- | --- | | 연동 방식 | 카카오 게임플레이 서버가 파트너사 정의 API로 동의 철회 JSON 통지 | 카카오 로그인 계정 상태 변경 웹훅으로 연결 해제 이벤트 수신 | | 등록 위치 | 카카오와 별도 협의 | 카카오디벨로퍼스 \[카카오 로그인] > \[계정 상태 변경 웹훅] | | 요청 본문 | `user_id` · `timestamp` · `reason` JSON | SET(Security Event Token) 형식의 JWT | | 약관 철회 시 앱 연결 해제 | 파트너사가 직접 처리 | 카카오가 처리 | | 약관 철회 시 파트너사 처리 | 연결 해제 + 데이터 파기 | 데이터 파기 + 내부 상태 정리 | | 개별 앱 연결 해제 처리 | 별도 경로·정책 필요 | 같은 `OAUTH: User Unlinked` 이벤트에서 `reason`으로 구분 | | 요청/응답/검증 상세 | 이 페이지에서 별도 정의 | 디벨로퍼스 계정 상태 변경 웹훅 문서 기준 | ## 연동 대상 파트너사는 카카오디벨로퍼스 앱 관리 페이지의 **\[카카오 로그인] > \[계정 상태 변경 웹훅]** 에 수신 웹훅 URL을 등록합니다. 파트너사가 처리해야 하는 핵심 이벤트는 `OAUTH: User Unlinked`입니다. | 항목 | 내용 | | --- | --- | | 이벤트 타입 | `OAUTH: User Unlinked` | | Schema | `https://schemas.openid.net/secevent/oauth/event-type/user-unlinked` | | 발생 시점 | 사용자가 앱과 연결 해제된 경우 | | 식별 정보 | SET payload의 사용자 회원번호 (`sub`, `subject.sub`) | | 구분 기준 | 이벤트 상세 정보의 `reason` | ## 인증 SET 서명 검증 등 요청 인증·검증 규격은 디벨로퍼스 [계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf) 문서를 따릅니다. 요청 본문(SET) 형식과 `Content-Type`은 디벨로퍼스 계정 상태 변경 웹훅 문서 규격을 따릅니다. ## reason별 처리 기준 | `reason` | 발생 상황 | 파트너사 처리 | | --- | --- | --- | | `REVOKE_ACCOUNT_SERVICE_TERMS` | 통합서비스 약관 동의 철회로 앱 연결이 해제된 경우 | 게임 데이터 파기 및 내부 연결 상태 정리 | | `UNLINK_FROM_APPS` | 사용자가 카카오계정 페이지에서 개별 앱 연결을 해제한 경우 | 게임 데이터 파기 및 내부 연결 상태 정리 | | `UNLINK_FROM_SERVICE` | 서비스 탈퇴로 앱 연결이 해제된 경우 | 서비스 탈퇴 정책에 따른 데이터 파기 및 내부 상태 정리 | | `ACCOUNT_DELETE` | 카카오계정 탈퇴 | 게임 데이터 파기 및 내부 연결 상태 정리 | | `FORCED_ACCOUNT_DELETE` | 장기 휴면 또는 고객센터에 의한 카카오계정 강제 탈퇴 | 게임 데이터 파기 및 내부 연결 상태 정리 | | `UNLINK_FROM_ADMIN` | 카카오 관리자에 의한 탈퇴 처리 | 게임 데이터 파기 및 내부 연결 상태 정리 | | `INCOMPLETE_SIGN_UP` | 가입 미완료 사용자 연결 해제. 최초 로그인 후 24시간 이내에 사용자 정보 조회 API를 호출하지 않은 경우입니다 | 생성된 임시 데이터가 있다면 파기 | ::: tip 핵심 변경점 기존에는 약관 철회 통지를 받은 뒤 파트너사가 직접 앱 연결 해제와 데이터 파기를 함께 처리했습니다. 웹훅 전환 후에는 `REVOKE_ACCOUNT_SERVICE_TERMS` 이벤트에서 **앱 연결 해제는 카카오가 처리**하고, 파트너사는 **데이터 파기와 내부 상태 정리**만 수행합니다. ::: ## 파트너사 처리 요구사항 * 카카오디벨로퍼스에 계정 상태 변경 웹훅 URL을 등록합니다. * 디벨로퍼스 문서 기준으로 SET을 검증하고, 검증에 성공한 이벤트만 처리합니다. * `OAUTH: User Unlinked` 이벤트를 수신하면 `reason`에 따라 약관 철회와 개별 앱 연결 해제를 구분합니다. * `reason = REVOKE_ACCOUNT_SERVICE_TERMS`인 경우 앱 연결 해제는 카카오가 이미 처리하므로, 별도 연결 해제 API를 호출하지 않고 데이터 파기와 내부 상태 정리만 수행합니다. * `reason = UNLINK_FROM_APPS` 등 개별 앱 연결 해제 이벤트도 같은 웹훅에서 처리하고, 게임 데이터 파기 및 내부 연결 상태 정리를 수행합니다. * 철회·연결 해제를 수신한 사용자는 카카오로의 게임 데이터 전송도 중지합니다. * 동일 이벤트가 재수신될 수 있으므로 SET의 요청/토큰 식별자를 기준으로 멱등성을 보장합니다. * 사용자 정보가 없거나 이미 처리된 이벤트도 중복 처리 없이 정상 응답하는 것을 권장합니다. ## 연동 흐름 **통합서비스 약관 동의 철회** | 순서 | 주체 | 동작 | | --- | --- | --- | | 1 | 사용자 | 통합서비스 약관 동의 철회 | | 2 | 카카오 | 파트너사 앱 연결 해제 처리 | | 3 | 카카오 | 계정 상태 변경 웹훅 발송 (`reason = REVOKE_ACCOUNT_SERVICE_TERMS`) | | 4 | 파트너사 | SET 검증 → 데이터 파기·내부 상태 정리 → 디벨로퍼스 규격으로 응답 | **개별 앱 연결 해제·탈퇴** | 순서 | 주체 | 동작 | | --- | --- | --- | | 1 | 사용자 | 카카오계정 페이지에서 앱 연결 해제 (또는 탈퇴 등) | | 2 | 카카오 | 계정 상태 변경 웹훅 발송 (`reason = UNLINK_FROM_APPS` 등) | | 3 | 파트너사 | SET 검증 → 데이터 파기·내부 연결 상태 정리 → 디벨로퍼스 규격으로 응답 | ## 참고 문서 * [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal): 전환 후 최신 규격 * [카카오 로그인 계정 상태 변경 웹훅](https://developers.kakao.com/docs/ko/kakaologin/callback#ssf): SET 구조·검증·응답 규격 * [카카오싱크 설정](/docs/authentication/kakao-login-sync): 앱·서비스 약관 설정 * [카카오싱크 API](/api-sdk/kakaosync/rest-api): 서비스 탈퇴와 연결 해제 요청 * [심사 체크리스트](/docs/checklist/review-checklist) * 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353) --- --- url: /release-notes.md description: 게임플레이 파트너 가이드의 제품·API·SDK 변경 이력 --- # 릴리즈 노트 게임플레이 파트너사에 영향을 줄 수 있는 변경 이력을 **제품 · API · SDK** 세 갈래로 나누어 최신순으로 정리합니다. 파트너사가 액션을 취해야 하는 항목만 다루며, 문서 개선이나 오탈자 수정은 포함하지 않습니다. \ \