---
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): 심사 전 자체 점검 항목