웹뷰 컴포넌트 가이드

게임웹뷰에 공통으로 적용하는 UI 컴포넌트의 동작과 디자인 기준을 안내합니다.
상태바, 내비게이션, 킵버튼과 기본 메뉴를 우선 적용하고, 게임에서 사용하는 선택 컴포넌트의 규격을 확인하세요.

지원 종료 예정

이 가이드는 게임플레이 JS SDK 를 사용하지 않는 환경에만 해당합니다.
게임플레이 JS SDK를 연동하면 내비게이션·드롭다운 메뉴·로딩·바텀시트·팝업을 SDK 가 직접 제공하므로, 이 문서의 컴포넌트를 게임이 만들지 않습니다. 새로 연동하는 게임은 UI 컴포넌트를 먼저 확인해 주세요.

SDK 를 적용하지 않은 게임은 계속 이 기준으로 제작합니다.
자세한 수치와 예시는 피그마 파일을 참고해 주세요.

게임플레이_디자인가이드_웹뷰 컴포넌트.fig

상태바 필수

상태바는 모든 화면 상단에 반드시 배치합니다.
상태바 확장과 비확장 상태에 따라 게임 화면의 상단 안전영역을 다르게 적용합니다.

iOS

• 1Dynamic Island

Android

• 1Navigation Bar

항목	기준
적용 여부	필수
배치	모든 화면 상단
iOS 기준	393 × 852 해상도에서는 Dynamic Island를 고려
Android 기준	360 × 800 해상도에서는 Camera Cutout을 고려
관련 기능	setStatusBarOverlay, changeStatusBarColor

상태바 확장 권장

게임 웹뷰를 확장할 경우 웹뷰 콘텐츠가 상태바까지 표시되므로, 주요 텍스트·버튼·재화 정보 등은 상태바 영역을 피해서 배치합니다.
참고: setStatusBarOverlay

iOS
393 × 852 기준의 해상도인 경우 Dynamic Island를 고려하여 적용합니다.

Do

상태바 영역과 게임 기능 요소가 겹치지 않게 배치합니다.

Don’t

상태바 영역과 게임 기능 요소가 중첩되지 않도록 구성합니다.

• 1393(14Pro) 해상도 상태바 예시
• 2375 해상도 상태바 예시
• 3320 해상도 상태바 예시

Android
360 × 800 기준의 해상도인 경우 Camera Cutout을 고려하여 적용합니다.

Do

상태바 영역과 게임 기능 요소가 겹치지 않게 배치합니다.

Don’t

상태바 영역과 게임 기능 요소가 중첩되지 않도록 구성합니다.

• 1360 해상도 상태바 예시
• 2320 해상도 상태바 예시

상태바 비확장

게임웹뷰를 확장하지 않는 경우, 웹뷰 콘텐츠는 기본 레이아웃 영역 내에 표시됩니다.
기본 상태바 스타일은 배경 #FFFFFF / 아이콘 #000000으로 적용됩니다.

iOS

Android

상태바 비확장 시, 배경 커스텀 컬러 옵션

기본 상태바 배경 컬러는 #FFFFFF, 아이콘은 #000000으로 적용됩니다.
상태바 배경은 커스텀 컬러로 변경할 수 있으나, 아이콘은 항상 #000000을 유지합니다.

상태바 배경 색상 변경이 필요할 경우, 선택적으로 커스텀 컬러 가이드에 맞춰 변경할 수 있습니다.

• 해당 기능은 카카오톡 26.6.0부터 사용할 수 있습니다.
• 참고: changeStatusBarColor

구분	기준점 컬러	기준
커스텀 컬러	#4C4C4C (어두운 컬러 예시)	HSB 기준 Brightness(B)는 30 이상 권장
블랙	#000000	상태바 아이콘과 동일한 컬러로 사용 금지
내비게이션바 아이콘 컬러	#363636	내비게이션바 아이콘과 동일한 컬러로 사용 금지
원색, 형광색 컬러	#FFFF00 (형광 컬러 예시)	눈의 피로도가 높은 원색·형광색 컬러 금지

iOS
393 × 852 기준의 해상도인 경우 Dynamic Island를 고려하여 적용합니다.

• 1기본 상태바 배경 컬러 적용 예시
• 2커스텀 컬러 배경 적용 예시
• 3어두운 배경 컬러 적용 예시

Android
360 × 800 기준의 해상도인 경우 Camera Cutout을 고려하여 적용합니다.

• 1기본 상태바 배경 컬러 적용 예시
• 2커스텀 컬러 배경 적용 예시
• 3어두운 배경 컬러 적용 예시

Tablet

• 1상태바에 지정한 컬러는 레터박스 배경 컬러로 사용합니다.
• 2커스텀 컬러 사용 시, 내비게이션바의 아이콘 위치를 기기 기준 우측 상단으로 변경합니다.

주의사항

Do

게임 배경과 연관성 높은 대표 컬러를 사용합니다.

Don’t

눈의 피로도가 매우 높고 가독성을 저해하는 원색, 형광색은 지양합니다.

Do

게임 배경과 연관성 높은 대표 컬러를 사용합니다.

Don’t

상태바와 내비게이션 바에 서로 다른 배경 컬러를 사용하지 않습니다.

내비게이션 필수

내비게이션은 모든 화면 상단에 반드시 배치되며, 게임의 상단 요소와 겹치지 않게 배치합니다.
Leading Controls의 아이콘은 닫기를 사용하며 오른쪽에 위치합니다.

• 1Container
• 2Close Button
• 3More Button
• 4Pull down Menu

항목	기준
적용 여부	필수
배치	모든 화면 상단
Leading Controls	닫기 아이콘 사용, 오른쪽 배치
아이콘 컬러	#FFFFFF 90%
아이콘 크기	20 × 20
아이콘 배경	#FFFFFF 2% + #2E2E2E 67%
아이콘 배경 테두리	#000000 12%, weight 0.5
아이콘 배경 크기	36 × 36

공통 내비게이션바

기존 게임 및 게임 제작 시 내비게이션의 메뉴와 게임 메뉴가 겹치지 않도록 배치하는 것을 권장합니다.

Do

내비게이션 기능 요소와 게임 메뉴가 겹치지 않게 배치합니다.

Don’t

내비게이션과 게임 기능 요소가 겹쳐 올바르게 보이지 않습니다.

가로모드 전용

가로 모드에서도 내비게이션 기능과 게임 메뉴가 겹치지 않아야 합니다.

킵버튼 필수

자동 접기 기능

iOS 게임웹뷰에서 게임을 실행하는 중 접기 버튼을 선택하면 실행 중인 카카오톡 화면으로 돌아가며, 게임으로 재진입할 수 있도록 플로팅 버튼을 제공합니다.
자동 접기, 더보기, 닫기 순서로 노출됩니다.

• 1Keep Button

항목	기준
적용 여부	필수
플랫폼	iOS 전용
사용 시점	게임 실행 중 접기 버튼 선택 시
노출 방식	플로팅 버튼으로 노출
아이콘	게임플레이 아이콘 자동 적용
관련 기능	keepBrowser

플로팅

게임 웹뷰에서 접기 버튼을 선택하면 플로팅 버튼이 노출되며, 다른 화면에서도 게임으로 재진입할 수 있습니다.
플로팅 버튼은 자유롭게 위치를 옮기거나 드래그하여 삭제할 수 있습니다.

플로팅 시 사용되는 아이콘은 게임플레이 아이콘으로 자동 적용되며, 개발사에서 별도로 적용할 부분은 없습니다.
참고: keepBrowser (카카오톡 v26.6.0 이상)

플로팅 버튼을 선택하면 게임 웹뷰로 다시 진입합니다.

드롭다운 메뉴 필수

더보기 메뉴를 선택하면 드롭다운으로 항목을 선택하거나 상태를 확인·변경할 수 있습니다.

항목	기준
적용 여부	필수
메뉴 개수	최대 3개
필수 메뉴	공유하기, 문의하기
선택 메뉴	최대 1개
선택 메뉴 글자 수	최대 10자
텍스트	14pt, #191919
컨테이너	#FFFFFF, radius 8
그림자	#000000 20%, 1, 1, 10, 0

메뉴 상세 필수

공유하기 (첫 번째 메뉴)

• 클릭하면 카카오톡 친구 선택 하프뷰가 노출됩니다.
• 공유 스펙 상세는 공유 설정을 참고하세요.

항목	기준
진입	헤더 풀다운 메뉴 > 첫 번째 메뉴
메뉴명	"공유하기"
대상 도메인	공유 설정 참고

문의하기 (두 번째 메뉴)

• 클릭하면 파트너사의 고객센터(CS) 페이지가 인앱브라우저로 노출됩니다.
• CS 도메인은 게임 실행 도메인과 반드시 분리해야 합니다.
  게임 실행 도메인 하위 경로(예: game.partner.com/support)로 설정하면 인앱브라우저가 아니라 게임웹뷰로 실행되어 정상 동작하지 않습니다.
  게임웹뷰가 도메인당 하나만 유지되는 특성 때문이며, 경로를 나눠도 해소되지 않습니다.
  자세한 내용은 게임웹뷰 SDK: 인앱브라우저 스킴을 참고해 주세요.

항목	기준
진입	헤더 풀다운 메뉴 > 두 번째 메뉴
메뉴명	"문의하기"
대상 도메인	파트너사 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보다 낮은 높이를 사용합니다.

• 1Dimmed
• 2Handler
• 3Title
• 4Contents Area
• 5Button

타입	높이 기준
Small	224 dp/pt
Medium	408 dp/pt
Large	528 dp/pt
Full	상태바·내비게이션을 제외한 전체 영역

토스트

주요 콘텐츠를 가리는 위치는 피하고 간결하고 명확한 내용만 전달합니다.

• 1단어 단위 개행 및 줄바꿈 가능, 최대 두 줄 입력을 권장합니다.

항목	기준
적용 여부	옵션
위치	레이어의 최상위 뷰 (하단 권장)
최소 너비	88 px
최대 너비	464 px
노출 시간	5초 이내
텍스트	14pt, #FFFFFF
컨테이너	#FFFFFF 10% + #1B1C25 67%, radius 12
효과	Background Blur 50%
Bottom Type 위치	Safe area 기준 default 65px, minimum 16px

Do

간결하고 명확한 내용을 전달합니다.

Don’t

장황한 문장의 사용을 지양합니다.

공통 팝업

화면 중앙에 위치하며 좌우 최소 여백을 유지하고 너비가 늘어납니다.

• 1타이틀

항목	기준
적용 여부	옵션
위치	화면 중앙
최대 너비	464 px
폰트	Pretendard
타이틀	17pt, #191919, 최대 2줄
서브 텍스트	15pt, #595959
컨테이너	#FFFFFF, radius 16
그림자	#000000 25%, 0, 0, 8, 0
버튼 텍스트	15pt, #191919
버튼 컨테이너	#000000 6%, radius 8

게임 종료 팝업 필수

• 공통 팝업과 동일한 규격을 사용합니다.
• 게임 이름과 게임을 그만할까요? 텍스트를 노출합니다.
• 게임 이름은 두 줄 노출 후 말줄임 처리합니다.
• 확인 버튼을 선택하면 다른 랜딩으로 이동할 수 없습니다.

• 1Container
• 2Title
• 3Button
• 4Button

항목	기준
적용 여부	필수
사용 시점	게임 종료 시
랜딩	확인 버튼 선택 시 게임플레이 홈 진입

에러 필수

게임 내 에러 상황에 따라 두 가지 타입을 사용합니다.

타입	사용 상황	적용 예시
에러 토스트	게임 진행 중 일시적 에러, 자동 복구 가능	네트워크 순단 후 자동 재연결, 부가 기능 일시 실패
에러 팝업	자체 복구가 어려워 재시도·종료 선택지를 제공해야 하는 경우	리트라이 N회 이상 실패, 세션 만료, 서버 점검 등

유료 데이터 환경 필수

• Wi-Fi 미연결 상태에서 유료 데이터 사용 안내는 Toast Popup 또는 Popup으로 노출합니다.
• 게임 데이터가 100 MB 이상이면 카카오와 사전 협의가 필요합니다.

• 1토스트 팝업 노출

• 2팝업 노출

케이스	기준
Toast Popup	일반적인 유료 데이터 사용 안내
Popup	게임 데이터가 100 MB 이상인 경우 필수

참고 문서

• 게임 공통 제작 가이드: 해상도·타이포그래피·컬러 기준
• 게임 콘텐츠 제작 가이드: 앱 아이콘·배너·공유 이미지 제작 기준
• 상태바 오버레이 설정 방법: 외부 화면 전환 시 상단 잘림 대응
• 게임웹뷰 SDK: 게임웹뷰 기능 구현 스펙
• 심사 체크리스트: 웹뷰 UI 자체 점검 항목