---
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<void>;

async function enterGame(): Promise<void> {
  await authenticate();

  await window.kakaotalkGamePlay.setStatusBarOverlay({enable: true});
}
```

## 이탈 직전 롤백

보완 대응입니다. 플레이 중에도 외부 페이지로 나가는 게임에만 추가로 적용합니다.

### 적용 지점

게임 플레이 도중 외부 페이지로 이동해야 할 때 사용합니다. 이동 직전에 오버레이를 끄고, 게임으로 돌아온 뒤 다시 켭니다.

진입 구간은 [복귀 후 활성화](#복귀-후-활성화) 로 처리하고, 이 방법은 그 위에 얹습니다.

### 구현

이동 직전에 오버레이를 끕니다. **Promise 가 resolve 된 뒤에 이동해야 합니다.** `await` 없이 곧바로 `location.href` 를 바꾸면 브리지 호출이 유실될 수 있습니다.

```ts
async function leaveGame(url: string): Promise<void> {
  await window.kakaotalkGamePlay.setStatusBarOverlay({enable: false});

  window.location.href = url;
}
```

게임 밖으로 나가는 경로는 이 헬퍼 하나를 거치게 만드세요. 이탈 지점마다 개별로 처리하면 한 곳만 빠뜨려도 그 경로에서 문제가 다시 나타납니다. 특히 게임 코드가 직접 트리거하지 않는 이동: 사용자가 탭하는 `<a href>` 링크, 서드파티 모듈이 수행하는 이동: 은 가로채기 어려우므로 이탈 경로를 설계 단계에서 함께 정리해야 합니다.

### 복귀 시 재활성화

돌아온 게임 페이지는 새로 로드되므로 현재 오버레이 상태를 알지 못합니다. 게임이 직접 다시 켜야 합니다.

게임웹뷰 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): 네이티브 브리지 스펙