앱인토스 Android WebView 하단 여백이 두 번 잡히는 문제 — env(safe-area-inset-bottom) 대신 JS로 정하기
목차
1. 배너 아래에 48px짜리 빈 띠가 남았습니다
2026년 10월 14일, 앱인토스 미니앱 세 개(차트예측게임, AI 손금 감정 보고서, 나의 성분 분석기)를 앱인토스 웹 SDK 3.8.0과 토스 디자인 시스템(TDS) 2.4.1로 올리면서 모든 화면 맨 아래에 고정 배너 광고를 붙이고 있었습니다. 가이드의 고정형 배너는 너비 100%, 높이 96px입니다. 광고 연동은 배포기 5편에서, WebView 차트 렌더링은 4편에서 다뤘으니, 이번에는 화면 맨 아래 48px 이야기입니다.
3버튼 내비게이션을 쓰는 삼성 Android 기기에서 차트예측게임을 열면 배너 아래에 빈 흰 띠가 남았습니다. 그 기기에서 토스 앱은 WebView를 불투명한 내비게이션 바 위에서 끝나게 배치했으니, WebView 안에서는 바를 피할 필요가 없습니다. 그런데 배너 영역이 바 높이만큼 여백을 한 번 더 두고 있었습니다. 기기 캡처를 재 보니 화면 높이 758px(CSS 픽셀) 중 WebView가 710px, 그 아래 48px가 바였고, 빈 띠도 48px였습니다. 이 값은 나중에 테스트 케이스로 옮겼습니다.
2. 원인: 브리지 값을 0으로 만들어도 env()가 다시 더했습니다
당시 배너 영역의 CSS입니다. 관련 속성만 남겼습니다.
.app-ad-shell {
padding-top: 16px;
padding-bottom: max(var(--app-safe-bottom, 0px), env(safe-area-inset-bottom, 0px));
border-top: 1px solid var(--line);
}하단 여백의 출처가 둘입니다. --app-safe-bottom은 앱인토스 SDK의 SafeArea.get() 값을 JS에서 넣는 변수이고, env(safe-area-inset-bottom)은 WebView가 CSS에 직접 주는 값입니다. 큰 쪽을 쓰는 max()는 흔한 방어 패턴이지만, 두 값이 같은 대상을 가리킬 때만 안전합니다.
그 기기에서는 브리지와 env()가 모두 바 높이인 48px를 하단 inset으로 알려 줬습니다. 첫 수정에서 저는 브리지 값만 0으로 바꿨고, 띠는 그대로였습니다. max(0px, 48px)은 여전히 48px이니까요. max()는 한쪽을 0으로 만들어서는 끌 수 없고, 살아 있는 출처를 전부 세어 봐야 했습니다. 같은 증상을 두 번 고친 이유입니다.
일반 원리로 보면 env(safe-area-inset-*)는 시스템 UI에 가려질 수 있는 뷰포트 가장자리를 브라우저가 알려 주는 값인데, WebView가 화면 어디까지 깔리는지는 WebView를 띄운 앱이 정합니다. 이 기기에서 둘이 왜 어긋났는지는 확인하지 못했습니다. 제가 확인한 것은 이 조합에서는 env()를 믿으면 안 된다는 데까지입니다.
3. 토스도 Android에서는 env()를 빼고 있었습니다
토스는 어떻게 하는지 보려고 프로젝트에 설치된 TDS 2.4.1 번들을 열었습니다. 하단 여백용 CSS 헬퍼의 압축 코드를 풀어 쓰면 이렇습니다.
/* TDS 2.4.1 번들의 safe-area 헬퍼를 풀어 쓴 것 (기본값 20px일 때) */
padding-bottom: 20px;
padding-bottom: max(20px, env(safe-area-inset-bottom));
.android-safe-area & {
padding-bottom: 20px;
}.android-safe-area 아래에서는 env()를 빼고 고정값만 씁니다. 앱인토스 devtools 3.8.0도 기기 프리셋 주석에 하단 Safe Area를 "노치 iPhone 34, 홈버튼/Android 0"으로 적어 두었고, Galaxy 프리셋 여섯 개는 모두 하단 0입니다. 그래서 방향을 정했습니다. Android에서는 env(safe-area-inset-bottom)를 하단 여백에 넣지 않고, 여백은 JS에서 정해 CSS 변수 하나로만 넘깁니다.
4. JS에서 하단 여백 정하기
CSS는 Android일 때만 JS가 정한 값을 쓰게 바꿨습니다. 앱 루트에 data-os를 붙이고, iOS와 데스크톱 브라우저는 env()가 안전망이 되도록 기존 max()를 그대로 뒀습니다.
.app-shell[data-os="android"] .app-ad-shell { padding-bottom: var(--app-safe-bottom, 0px); }다만 WebView가 바 아래까지 깔리는 기기라면 여백을 빼는 순간 광고가 바에 가려집니다. 그래서 useAppSafeArea 훅이 Android에서는 브리지 값을 화면 크기와 비교해 남길지 정합니다.
// useAppSafeArea.ts 일부
const TOLERANCE = 4;
export function androidBottomInset(bottom: number, top: number): number {
if (bottom <= 0 || typeof window === 'undefined') return 0;
const screenHeight = window.screen?.height;
const viewportHeight = window.innerHeight;
if (!(screenHeight > 0) || !(viewportHeight > 0)) return 0;
const outside = screenHeight - viewportHeight;
const onlyTopOutside = Math.abs(outside - top) <= TOLERANCE && Math.abs(outside - bottom) > TOLERANCE;
return outside < bottom - TOLERANCE || onlyTopOutside ? bottom : 0;
}기준은 화면 높이에서 WebView 높이를 뺀 "화면 밖 높이"입니다. 이 값이 하단 inset보다 4px 넘게 작으면 바가 밖에 있을 수 없으니 WebView가 바 아래까지 깔린 것으로 보고 여백을 남깁니다. 밖으로 빠진 높이가 상단 inset과만 같을 때도 바는 WebView 안에 있으니 남깁니다. 나머지는 0입니다. 문제의 기기처럼 화면 밖 높이가 바 높이와 같거나, 위아래 inset이 비슷해 가릴 수 없거나, 값을 못 읽은 경우입니다. 판단이 서지 않으면 실제로 본 배치를 따르게 한 것입니다. 판정은 Safe Area 변경 이벤트, 창과 visualViewport 크기 변화, 화면 회전 때마다 다시 합니다.
검증은 세 갈래였습니다. 먼저 문제 기기 값(758/710, 하단 48 → 0)을 포함한 표 형태 테스트 15개로 Android 판정을 고정했습니다. 화면 전체를 덮는 WebView(→ 48), 30px 상태 표시줄 아래 20px 제스처 바(→ 20), 허용 오차 경계(화면 밖 높이 44px면 0, 43px면 48)가 들어 있습니다.
다음은 재현입니다. 데스크톱 헤드리스 Chrome에서 CDP의 Emulation.setSafeAreaInsetsOverride로 env()를 48px로 만들고, SDK가 읽는 전역 상수 window.__appsInTossConstants에 safeAreaInsets를 넣어 브리지 값까지 흉내 냈습니다. SDK 3.8.0의 SafeArea.get()은 호스트가 주입한 이 상수를 그대로 읽습니다.

헤드리스 Chrome 재현 화면입니다. 하단 inset 48px 조건에서 수정 전과 후를 찍었고, 광고 자리는 같은 높이의 임시 배너로 채운 뒤 문구를 가렸습니다.
수정 후 광고 영역 113px는 위 여백 16px, 배너 96px, 구분선 1px의 합이고, 수정 전 161px는 여기에 48px가 더 붙은 값입니다.
마지막으로 테스트 광고를 쓰는 QA 빌드에만 설정 탭 맨 아래 "화면 정보 (QA 빌드)"를 넣었습니다. 브리지 값, env() 값, 화면·뷰포트 크기, 판정 결과, 실제 광고 하단 여백이 한 화면에 나옵니다. env()는 JS에서 바로 읽을 수 없어 숨긴 요소의 높이로 쟀습니다.
// viewportInfo.ts 일부 (QA 빌드 전용 진단)
function envInset(side: 'top' | 'bottom') {
const probe = document.createElement('div');
probe.style.cssText = `position:fixed;visibility:hidden;pointer-events:none;height:env(safe-area-inset-${side}, 0px)`;
document.body.append(probe);
const height = probe.getBoundingClientRect().height;
probe.remove();
return round(height);
}나머지 두 앱은 TDS의 TDSMobileAITProvider가 body에 넣는 --toss-safe-area-bottom(SDK의 Safe Area 값)을 쓰고, Android에서는 env()를 뺐습니다.
| 미니앱 | 반영 | Android 하단 여백 | 확인 상태 |
|---|---|---|---|
| 차트예측게임 | 10월 14일 검토 요청 번들 | JS 판정, Android에서 env() 제외 | 테스트·헤드리스 재현까지 |
| AI 손금 감정 보고서 | 10월 14일 f4cd1dd | Android면 --toss-safe-area-bottom만 사용 | Android 실기기 미확인 |
| 나의 성분 분석기 | 10월 14일 592e2f3 | 배너 여백에서 env() 제거 | 폰에서 배너·키보드 배치 확인 후 배포 |
5. 키보드가 올라와도 배너는 보이게: 키보드 → 배너 → 8px → CTA
나의 성분 분석기는 첫 화면에서 TDS TextField로 이름을 받고, 그 아래에 하단 고정 버튼(FixedBottomCTA)이 있습니다. 처음에는 입력하는 동안 배너를 숨기는 빌드를 만들었는데, 폰에서 써 보니 키보드가 올라오는 순간 배너가 갑자기 사라졌습니다. 원한 동작이 아니었습니다. 그래서 숨기지 않고 아래부터 키보드, 배너, 8px, CTA 순서로 쌓았습니다.
배너는 App 레벨에 한 번만 마운트하고, 잰 높이를 document.documentElement의 --banner-height와 스토어에 넣었습니다. TDS CTA는 포털로 렌더링되어 트리 아래쪽에 둔 CSS 변수를 상속받지 못하기 때문입니다.
iOS는 키보드를 페이지 위에 덮으므로 고정 요소를 직접 올려야 합니다. 키보드 높이는 TDS와 같은 방식으로, 화면 전체 높이의 fixed 프로브에서 visualViewport.height + offsetTop을 빼서 쟀습니다.
// useBannerAd.ts 일부 — iOS 키보드가 가린 높이
const probe = document.createElement('div');
probe.style.cssText = 'position:fixed;top:0;bottom:0;left:0;width:0;visibility:hidden;pointer-events:none';
document.body.appendChild(probe);
const measure = () => {
frameId = 0;
const covered = probe.getBoundingClientRect().height - (viewport.height + viewport.offsetTop);
setInset(covered > 40 ? Math.floor(covered) : 0);
};
const update = () => {
if (!frameId) frameId = requestAnimationFrame(measure);
};
viewport.addEventListener('resize', update);
viewport.addEventListener('scroll', update);40px 이하는 툴바가 흔들리는 정도로 보고 무시하고, 소수점은 내림해서 배너와 키보드 사이에 틈이 생기지 않게 했습니다. visualViewport의 resize·scroll 이벤트는 requestAnimationFrame으로 묶어 프레임당 한 번만 잽니다. Android는 키보드가 열리면 WebView 자체가 줄어들어 이 값이 0으로 남습니다.
배너는 키보드 위로 올라갈 때 하단 Safe Area 여백을 뺍니다. 홈 인디케이터가 키보드에 가려지기 때문입니다. 위쪽 8px가 CTA와의 간격입니다.
/* index.css 일부 — 관련 속성만 남김 */
.global-banner-ad {
position: fixed;
bottom: 0;
padding-top: 8px;
padding-bottom: var(--toss-safe-area-bottom, 0px);
}
.global-banner-ad--above-keyboard {
padding-bottom: 0;
}// OnboardingScreen.tsx 일부 — 배너 바로 위에 CTA
const bannerHeight = useBannerStore((s) => s.reservedHeight);
const keyboardInset = useBannerStore((s) => s.keyboardInset);
const ctaBottom = bannerHeight + keyboardInset;
<FixedBottomCTA
containerStyle={ctaBottom > 0 ? { bottom: ctaBottom } : undefined}
hasSafeAreaPadding={bannerHeight === 0}
onClick={handleStart}
>
분석 시작하기
</FixedBottomCTA>CTA의 bottom에 키보드 높이까지 더하는 이유는 TDS 코드에 있었습니다. TDS 2.4.1의 하단 CTA는 iOS 키보드가 열리면 스스로 bottom을 옮기는데, containerStyle을 그 스타일 뒤에 합칩니다. bottom을 넘기면 TDS의 보정이 덮어써지는 것입니다. 또 TDS는 화면의 30% 넘게 가려지면 키보드가 열렸다고 보고 CTA 하단 패딩을 0으로 만듭니다. 배너 위 8px가 없으면 버튼이 배너에 붙습니다. CTA의 Safe Area 패딩은 배너가 없을 때만 켭니다.
이 배치는 10월 14일 나의 성분 분석기에 적용했고(592e2f3), 폰에서 확인한 뒤 배포했습니다. AI 손금 감정 보고서도 같은 날 모든 화면에 배너를 붙였습니다(151c3d4).
6. 적용 결과와 남은 문제
차트예측게임은 이 수정을 담은 번들로 10월 14일 검토를 요청했습니다. 여기까지 확인한 것은 테스트, 헤드리스 재현, 제출 번들의 CSS에 Android 규칙이 들어 있다는 사실입니다. 여러 Android 실기기에서 띠가 사라졌는지 직접 보는 일은 남아 있습니다.
손금 앱과 성분 분석기는 Android에서 env()만 빼고 브리지 값은 그대로 믿습니다. 그런데 차트예측게임을 띄운 기기에서는 브리지 값도 48px였습니다. 같은 기기라면 두 앱에도 띠가 남을 수 있습니다. 손금 앱 커밋에 이 위험을 미확인 항목으로 적어 두었지만, 화면 크기 판정은 아직 두 앱에 옮기지 못했습니다.
화면 크기 판정에도 가정이 있습니다. 판단이 서지 않거나 분할 화면처럼 화면 밖 높이를 설명할 수 없으면 0을 고르므로, 그런 상태에서 바 아래까지 깔리는 WebView라면 광고가 바에 가려질 수 있습니다. 이 판정은 3버튼 내비게이션 기기 한 대의 배치를 기준으로 만들었기 때문에, 제스처 내비게이션 기기도 실기기로 확인해야 합니다.
7. 같은 문제를 만나면 확인할 것
- 하단 여백의 출처를 전부 셉니다. 브리지 값, env(), 컴포넌트 자체 여백까지 셉니다.
max()로 묶여 있으면 하나를 0으로 만들어도 꺼지지 않습니다. - Android에서는 env(safe-area-inset-bottom)를 하단 여백에 넣지 않습니다. TDS도 그렇게 합니다.
- 브리지 값은 화면 크기와 맞춰 봅니다.
screen.height - innerHeight가 바 높이와 같으면 WebView는 이미 바 위에서 끝났습니다. - 데스크톱에서 재현합니다. CDP로 env()를, SDK 전역 상수로 브리지 값을 흉내 내면 기기 없이도 띠를 다시 만들 수 있습니다.
- QA 빌드에 원값 패널을 둡니다. 캡처 한 장으로 원인을 가를 수 있습니다.
- 키보드 위 배너는 키보드 → 배너 → 8px → CTA로 쌓습니다. CTA에
bottom을 넘길 때는 키보드 높이까지 더합니다. - 마지막은 실기기입니다. 3버튼과 제스처 내비게이션 기기를 둘 다 봅니다.
화면 맨 아래 48px는 작아 보여도 배너 바로 밑이라 금방 눈에 띕니다. 여백이 이상하면 값을 고치기 전에 그 여백을 정하는 출처가 몇 개인지부터 세어 보려고 합니다.
차트를 보고 다음 봉을 예측하는 게임은 iPhone 앱으로도 만들었습니다. 차트 예측 게임 소개 페이지에서 볼 수 있습니다.