게임플레이 파트너 가이드

테마 전환

상태바 오버레이 설정 방법 ​

setStatusBarOverlay 로 게임웹뷰를 상태바 영역까지 확장한 뒤 게임이 외부 URL 로 이동하면, 이동한 페이지도 상태바 밑으로 밀려 상단이 잘립니다.
카카오싱크 약관 동의창처럼 파트너사가 화면을 수정할 수 없는 페이지에서 특히 문제가 됩니다.
이 페이지는 파트너사 게임 코드만으로 이 문제를 막는 방법을 정리합니다.

오버레이 상태 ​

상태바 오버레이는 웹 페이지가 아니라 네이티브 웹뷰 컨테이너가 소유하는 레이아웃 속성입니다.

대상소유자페이지 이동 시
게임 화면 DOM · CSS웹 페이지새 페이지로 교체됩니다
상태바 오버레이네이티브 웹뷰그대로 유지됩니다

두 생명주기가 어긋나는 것이 문제의 원인입니다.
게임이 한 번 오버레이를 켜면 이후 웹뷰에 로드되는 모든 페이지가 확장된 레이아웃을 물려받습니다.
새로 로드된 페이지는 자신이 오버레이 상태인지 알 수 없으므로 스스로 안전영역을 보정할 수도 없습니다.

문제가 되는 흐름 ​

사용자가 게임에 처음 접근해 카카오싱크 약관에 동의하는 흐름입니다.

단계동작오버레이결과
1카카오가 진입 조건을 확인한 뒤 게임 URL 로드꺼짐정상
2게임이 setStatusBarOverlay(true) 호출켜짐게임 화면이 상태바까지 확장
3게임이 prompt 없는 kauth 인가 코드 요청켜짐 (유지)—
4약관 미동의 사용자 → 카카오싱크 동의창으로 리디렉션켜짐 (유지)—
5동의창 렌더켜짐 (유지)상단이 상태바에 가려져 잘림
6동의 완료 후 게임으로 복귀켜짐정상

5단계가 문제입니다.
동의창은 카카오싱크가 제공하는 화면이라 파트너사가 안전영역 대응을 넣을 수 없습니다.
설정은 카카오싱크 설정, 인증 흐름은 카카오싱크 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 미만에서 호출이 실패해도 게임이 정상 진행되는지 확인
  • [ ] 약관 미동의 신규 사용자로 최초 진입을 재현해 동의창 상단이 잘리지 않는지 확인

참고 문서 ​