---
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 자체 점검 항목