복군의 뒷주머니

윈도우에서 클로드 코드(Claude Code)를 쓰다 보면 한글이 세 군데에서 각각 다르게 깨집니다.

// ① 터미널 출력
?????? ??? ???

// ② 파이썬 실행
UnicodeEncodeError: 'cp949' codec can't encode character '✓'

// ③ 만들어 준 PowerShell 스크립트 실행
+ Write-Output "?��?��"
              ~~~~~~
문자열에 종료 기호가 없습니다.

세 증상 모두 AI 도구의 버그가 아닙니다. 윈도우의 기본 문자 인코딩이 UTF-8이 아니라 CP949(euc-kr 계열)이기 때문에 생기는 오래된 문제이고, 도구가 한글을 많이 다루게 되면서 한꺼번에 드러난 것입니다.

깨지는 지점이 셋이므로, 고치는 곳도 셋입니다. 하나만 고치고 "왜 아직도 깨지지"를 반복하는 경우가 대부분입니다.

① 터미널 출력이 ?로 나올 때

콘솔의 코드페이지를 UTF-8(65001)로 바꿉니다. 임시로는 이 한 줄이면 됩니다.

chcp 65001

PowerShell이라면 출력·입력 인코딩까지 함께 지정하는 편이 확실합니다.

# PowerShell 프로필에 넣어두면 매번 적용된다
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

프로필 파일 위치는 이렇게 확인하고, 없으면 만들면 됩니다.

echo $PROFILE
# 없으면
New-Item -ItemType File -Path $PROFILE -Force

근본 해결 — 시스템 로캘을 UTF-8로

매번 설정하기 싫다면 윈도우 전체를 UTF-8로 돌릴 수 있습니다.

설정 → 시간 및 언어 → 언어 및 지역 → 시스템 로캘 변경 → "세계 언어 지원을 위한 Beta: 유니코드 UTF-8 사용" 체크 → 재부팅

② UnicodeEncodeError: 'cp949' — 파이썬

파이썬이 print()로 한글이나 특수문자(✓, →, 이모지)를 출력할 때 터집니다. 스크립트 안의 한글은 멀쩡한데 출력하는 순간 죽는 것이 특징입니다.

방법 A — 환경 변수 (가장 간단)

# 현재 세션만
$env:PYTHONIOENCODING = "utf-8"

# 영구 적용
[Environment]::SetEnvironmentVariable(
    "PYTHONIOENCODING", "utf-8", "User")

방법 B — 스크립트 자체가 스스로 해결하게 (권장)

다른 PC나 자동화(작업 스케줄러)에서도 돌아가야 한다면, 환경 변수에 기대지 말고 스크립트 상단에서 표준 출력을 UTF-8로 다시 감싸는 편이 안전합니다.

# -*- coding: utf-8 -*-
import sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")

파일 읽기·쓰기도 마찬가지

# ❌ 윈도우에서는 기본이 cp949 라 깨진다
open("data.txt").read()

# ✅ 항상 명시
open("data.txt", encoding="utf-8").read()
open("out.txt", "w", encoding="utf-8").write(text)

③ 스크립트가 실행조차 안 될 때 — BOM 문제

여기가 가장 안 알려져 있고, 가장 오래 헤매는 지점입니다. AI가 만들어 준 .ps1 파일을 실행했더니 문법 오류가 나고, 열어보면 코드는 멀쩡합니다.

Write-Output "발행 완료"
# → 문자열에 종료 기호가 없습니다.

Windows PowerShell 5.1은 BOM이 없는 파일을 CP949로 읽습니다. UTF-8로 저장된 한글이 CP949로 해석되면서 따옴표 짝이 깨진 것처럼 보이는 것입니다. 코드가 아니라 파일이 저장된 방식이 문제입니다.

# BOM 포함으로 다시 저장
$content = Get-Content .\script.ps1 -Raw -Encoding UTF8
[System.IO.File]::WriteAllText(
    "$PWD\script.ps1", $content,
    [System.Text.UTF8Encoding]::new($true))   # $true = BOM 포함

에디터에서라면 VS Code 오른쪽 아래 인코딩 표시를 눌러 Save with Encoding → UTF-8 with BOM을 고르면 됩니다.

Set-Content로 파일을 만들 때

# ❌ PowerShell 5.1의 Set-Content 기본값은 시스템 ANSI(CP949)
Set-Content out.txt $text

# ✅ 명시
Set-Content out.txt $text -Encoding utf8

AI 도구에 아예 규칙으로 박아두기

매번 "한글 안 깨지게 저장해 줘"라고 말하는 대신, 프로젝트 규칙 파일(CLAUDE.md 등)에 적어두면 계속 적용됩니다. 실제로 효과가 큰 부분입니다.

# 인코딩 규칙 (윈도우 환경)

- 모든 텍스트 파일은 UTF-8 로 저장한다.
- .ps1 파일은 반드시 UTF-8 **BOM 포함** 으로 저장한다.
  (BOM 이 없으면 PowerShell 5.1 이 CP949 로 읽어 파싱이 깨진다)
- 파이썬 스크립트는 상단에 표준 출력 UTF-8 래핑을 넣는다.
- open() 과 Set-Content 에는 인코딩을 항상 명시한다.

터미널에서 한글 입력이 이상할 때

출력이 아니라 입력 쪽 증상도 있습니다. 한글을 치는 도중 글자가 커서와 어긋나게 그려지거나, 문장 중간을 수정하면 조합이 흐트러지는 현상입니다.

이것은 코드페이지가 아니라 터미널의 IME 처리 문제라 설정으로 해결되지 않습니다. 대응은 두 가지입니다.

• 도구를 최신 버전으로 업데이트 — 한국어·중국어·일본어 조합 입력 처리는 개선이 이어지는 영역입니다.
• 긴 한글 프롬프트는 다른 곳에서 작성해 붙여넣기 — 조합 중 렌더링 문제라, 완성된 문자열을 붙여넣으면 영향을 받지 않습니다.

점검 순서

자주 묻는 질문

Q. chcp 65001을 했는데도 깨집니다.

깨지는 지점이 출력이 아니라 파일 저장일 가능성이 큽니다. 그 파일을 VS Code로 열어 오른쪽 아래 인코딩 표시를 확인하세요. CP949로 저장돼 있다면 코드페이지를 아무리 바꿔도 그대로입니다.

Q. 손으로 실행하면 되는데 작업 스케줄러에서만 깨집니다.

실행 계정이 달라 환경 변수가 적용되지 않은 것입니다. 환경 변수 대신 스크립트 자체가 인코딩을 지정하도록 바꾸면 실행 주체와 무관해집니다.

Q. UTF-8 BOM을 넣으면 다른 데서 문제 되지 않나요?

.ps1은 BOM이 있어야 안전하고, 반대로 셸 스크립트(.sh)·JSON·YAML은 BOM이 있으면 안 됩니다. 파일 종류에 따라 다르므로 일괄로 BOM을 붙이지 마세요.

Q. PowerShell 7을 쓰면 해결되나요?

많이 나아집니다. 기본 인코딩이 UTF-8이라 BOM 문제에서 자유롭습니다. 다만 윈도우에 기본 설치된 5.1도 함께 남아 있으므로, 스크립트가 어느 쪽으로 실행되는지는 여전히 확인해야 합니다.

Q. AI가 만든 코드의 한글 주석만 깨집니다.

파일 저장 인코딩 문제입니다. 소스 파일을 UTF-8로 저장하고, 자바 계열이라면 컴파일 옵션에 -encoding UTF-8이 들어가 있는지도 확인하세요.

정리

윈도우에서 한글이 깨질 때 가장 먼저 할 일은 고치는 게 아니라 어디서 깨졌는지 가르는 것입니다. 화면에서 깨진 것인지, 파일에 잘못 저장된 것인지, 파일은 멀쩡한데 읽는 쪽이 잘못 해석한 것인지에 따라 답이 완전히 다릅니다.

그리고 한 번 고쳤으면 규칙으로 남기세요. 인코딩 문제는 잊을 만하면 다른 얼굴로 돌아오고, 그때마다 같은 시간을 다시 씁니다.

앱 안 웹뷰에서 "구글로 로그인"을 눌렀더니 로그인 화면 대신 이 문구가 뜹니다.

403. That's an error.

Error: disallowed_useragent

You can't sign in from this screen because
this app doesn't comply with Google's secure browsers policy.

모바일 크롬에서 같은 페이지를 열면 잘 됩니다. 앱 안에서만 막힙니다. 카카오·네이버 로그인은 되는데 구글만 안 되는 것도 흔한 조합입니다.

원인 — 구글이 내장 웹뷰의 로그인을 정책으로 막았다

버그가 아니라 의도된 차단입니다. 구글은 2021년 9월 말부터 앱에 내장된 웹뷰(embedded WebView)에서의 OAuth 인증을 허용하지 않습니다. 이유는 보안입니다.

웹뷰는 앱이 그 안을 들여다볼 수 있습니다. 자바스크립트를 주입해 입력값을 읽거나, 화면을 캡처하거나, 쿠키를 꺼낼 수 있습니다. 즉 악의적인 앱이 진짜 구글 로그인 화면을 띄워놓고 아이디와 비밀번호를 그대로 가져갈 수 있다는 뜻입니다. 사용자는 주소창이 없어서 진짜인지 확인할 방법도 없습니다.

먼저 — 하면 안 되는 우회 두 가지

정답은 하나입니다. 로그인 구간만 웹뷰 밖으로 꺼내는 것입니다.

해결 — 로그인만 Custom Tabs로 연다

Chrome Custom Tabs는 앱 안에 떠 있는 진짜 브라우저입니다. 앱은 그 안을 볼 수 없고, 사용자는 주소창으로 도메인을 확인할 수 있으며, 크롬에 로그인돼 있으면 계정 선택만으로 끝납니다. 구글이 요구하는 조건을 모두 만족합니다.

1단계 — 의존성

// build.gradle.kts
implementation("androidx.browser:browser:1.8.0")

2단계 — 로그인 URL만 가로채서 Custom Tabs로 넘긴다

웹뷰는 그대로 두고, 구글 인증 주소로 이동하려는 순간에만 끼어들면 됩니다.

webView.webViewClient = object : WebViewClient() {

    override fun shouldOverrideUrlLoading(
        view: WebView, request: WebResourceRequest
    ): Boolean {
        val url = request.url.toString()

        if (isOAuthUrl(url)) {
            openInCustomTab(view.context, url)
            return true          // 웹뷰는 열지 않는다
        }
        return false
    }

    private fun isOAuthUrl(url: String): Boolean =
        url.startsWith("https://accounts.google.com/") ||
        url.startsWith("https://appleid.apple.com/auth/authorize")
}

private fun openInCustomTab(context: Context, url: String) {
    CustomTabsIntent.Builder()
        .setShowTitle(true)
        .build()
        .launchUrl(context, Uri.parse(url))
}

3단계 — 로그인 끝나고 앱으로 돌아오게 만든다

여기서 대부분 막힙니다. Custom Tabs로 로그인은 됐는데 브라우저에 머물러 있고 앱으로 안 돌아옵니다. 인증이 끝난 뒤 서버가 보내는 리다이렉트 주소를 앱이 받을 수 있는 주소로 만들어야 합니다.

<!-- AndroidManifest.xml -->
<activity
    android:name=".AuthCallbackActivity"
    android:exported="true"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 서버가 최종적으로 리다이렉트할 주소 -->
        <data android:scheme="myapp" android:host="auth" />
    </intent-filter>
</activity>

class AuthCallbackActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // myapp://auth?token=... 형태로 돌아온다
        val token = intent?.data?.getQueryParameter("token")

        if (token != null) {
            // 세션 저장 후 원래 화면으로 복귀
            SessionStore.save(token)
            startActivity(Intent(this, MainActivity::class.java).apply {
                flags = Intent.FLAG_ACTIVITY_CLEAR_TOP
            })
        }
        finish()
    }
}

4단계 — 돌아온 세션을 웹뷰가 알게 한다

Custom Tabs와 웹뷰는 쿠키 저장소가 다릅니다. 브라우저에서 로그인했다고 웹뷰가 로그인 상태가 되지는 않습니다. 그래서 돌려받은 토큰을 웹뷰 쪽에 심어줘야 합니다.

// 토큰을 쿼리로 넘겨 서버가 웹뷰 세션을 만들게 하거나
webView.loadUrl("https://example.com/app/enter?token=$token")

// 서버가 쿠키 기반이라면 직접 주입
CookieManager.getInstance().apply {
    setAcceptCookie(true)
    setCookie("https://example.com", "session=$token; Path=/; Secure; HttpOnly")
    flush()          // ★ 빼먹으면 앱 재시작 시 로그인이 풀린다
}

다른 선택지 — 아예 네이티브 로그인으로

웹뷰 껍데기 앱이 아니라 네이티브 화면이 있는 앱이라면, 웹 OAuth 대신 안드로이드 네이티브 로그인을 쓰는 편이 사용자 경험이 훨씬 낫습니다. 계정 선택 시트가 바로 뜨고 브라우저를 거치지 않습니다.

점검 순서

자주 묻는 질문

Q. User-Agent를 바꿨더니 되던데요?

지금은 통과할 수 있습니다. 문제는 그것이 정책 위반이라 언제든 다시 막힌다는 점입니다. 그때는 이미 출시된 앱의 로그인이 통째로 죽고, 스토어 업데이트가 반영될 때까지 사용자는 들어오지 못합니다. 실제로 이 방식으로 버티다 한 번에 무너지는 사례가 반복돼 왔습니다.

Q. 카카오·네이버 로그인은 웹뷰에서 잘 되는데요?

각 서비스의 정책이 다릅니다. 다만 국내 서비스들도 자체 SDK나 앱 전환 방식을 권장하는 방향으로 가고 있습니다. 구글만 예외적으로 엄격한 것이지, 웹뷰 안에서 남의 계정 로그인을 처리하는 구조 자체가 권장되지 않습니다.

Q. Custom Tabs를 열었더니 브라우저 앱으로 완전히 튀어나갑니다.

CustomTabsIntent가 아니라 일반 ACTION_VIEW 인텐트로 열고 있을 가능성이 큽니다. 또는 기기에 Custom Tabs를 지원하는 브라우저가 없어 폴백된 경우입니다. 후자는 정상 동작이며, 앱 복귀는 앱 스킴 콜백이 처리합니다.

Q. 로그인은 되는데 앱으로 안 돌아옵니다.

3단계의 앱 스킴 설정 문제입니다. BROWSABLE 카테고리 누락, 스킴 오타, 서버가 보내는 최종 리다이렉트 주소 불일치 중 하나입니다. 브라우저 주소창에 myapp://auth를 직접 쳐서 앱이 뜨는지부터 확인하면 빠릅니다.

Q. 앱을 껐다 켜면 로그인이 풀립니다.

쿠키를 주입한 뒤 CookieManager.flush()를 호출하지 않아서입니다. 웹뷰 쿠키는 메모리에 있다가 flush 시점에 디스크로 내려갑니다.

정리

disallowed_useragent는 고칠 수 있는 오류가 아니라 지켜야 할 규칙입니다. 앱이 들여다볼 수 있는 화면에서는 남의 계정 로그인을 받지 말라는 것이고, 그 요구는 앞으로 더 강해질 방향이지 느슨해질 방향이 아닙니다.

따라서 로그인 구간만 Custom Tabs로 꺼내고, 인증이 끝나면 앱 스킴으로 돌아와 세션을 웹뷰에 심는 것이 정공법입니다. 작업량은 반나절이면 충분하고, User-Agent를 바꾸며 버티는 방식보다 훨씬 오래갑니다.

앱 안 웹뷰가 흰 화면이거나 회색 오류 페이지를 띄우고, 로그캣에 이렇게 찍힙니다.

net::ERR_CACHE_MISS

같은 주소를 모바일 크롬으로 열면 멀쩡합니다. 검색하면 "인터넷 권한을 추가하세요"라는 답이 가장 먼저 나오는데, 권한이 이미 있는데도 나는 경우가 절반은 됩니다. 이름 그대로 "캐시에서 못 찾았다"는 뜻이라 원인이 세 갈래로 갈리기 때문입니다.

먼저 세 갈래 중 어디인지 가른다

이 구분을 먼저 하지 않고 코드를 고치면, 남의 답을 그대로 붙여넣어 놓고 "왜 안 되지"를 반복하게 됩니다.

원인 ① INTERNET 권한 — 가장 흔하고 가장 허무하다

웹뷰는 네트워크를 못 쓰면 캐시에서 찾으려 하고, 캐시도 없으니 ERR_CACHE_MISS를 냅니다. "인터넷이 없다"가 아니라 "캐시에 없다"로 나오는 탓에 원인이 잘 안 보입니다.

<!-- AndroidManifest.xml — <application> 바깥, 최상위에 -->
<uses-permission android:name="android.permission.INTERNET" />

원인 ② 캐시 모드 — LOAD_CACHE_ONLY가 범인

웹뷰의 캐시 정책은 네 가지입니다. 이 중 하나를 잘못 고르면 네트워크가 멀쩡해도 오류가 납니다.

오프라인 대응을 넣다가 LOAD_CACHE_ONLY로 고정해 둔 코드가 대표적인 사고 지점입니다. 캐시가 비어 있는 첫 실행에서 100% 실패합니다.

webView.settings.apply {
    javaScriptEnabled = true
    domStorageEnabled = true
    cacheMode = WebSettings.LOAD_DEFAULT   // ★ 특별한 이유 없으면 이것
}

네트워크 상태에 따라 갈라야 한다면, 고정하지 말고 그때그때 판단해야 합니다.

private fun currentCacheMode(context: Context): Int {
    val cm = context.getSystemService(ConnectivityManager::class.java)
    val caps = cm.getNetworkCapabilities(cm.activeNetwork)
    val online = caps?.hasCapability(
        NetworkCapabilities.NET_CAPABILITY_INTERNET) == true

    return if (online) WebSettings.LOAD_DEFAULT
           else WebSettings.LOAD_CACHE_ELSE_NETWORK
}

// 로드 직전에 적용
webView.settings.cacheMode = currentCacheMode(this)
webView.loadUrl(url)

같이 볼 것 — 네트워크 로드 차단 플래그

setBlockNetworkLoads(true)를 켜 두면 캐시 모드와 무관하게 통신이 막혀 같은 오류가 납니다. 오프라인 진입 시 켜고 복귀할 때 끄는 것을 빼먹은 코드가 흔합니다.

webView.settings.blockNetworkLoads = false   // 온라인 복귀 시 반드시 해제
// blockNetworkImage 도 같은 방식으로 관리

원인 ③ POST 뒤로가기 — 캐시가 없는 게 정상인 경우

로그인·검색·주문처럼 POST로 이동한 페이지는 웹뷰가 캐시에 담지 않습니다. 그래서 뒤로가기나 새로고침으로 그 페이지를 다시 그리려 하면 가져올 캐시가 없어서 ERR_CACHE_MISS가 납니다. 이 경우는 설정 실수가 아니라 구조의 문제입니다.

세 가지 대응이 있고, 상황에 따라 고르면 됩니다.

대응 A — 서버가 POST 뒤에 리다이렉트하게 한다 (권장)

POST 처리 후 결과 페이지로 302 리다이렉트하면(PRG 패턴), 히스토리에 남는 것은 GET이라 뒤로가기가 깨지지 않습니다. 웹 쪽을 고칠 수 있다면 이게 가장 깔끔합니다.

대응 B — 뒤로가기를 앱이 직접 처리한다

// 히스토리 항목이 POST였다면 뒤로가기 대신 새로 로드
webView.setOnKeyListener { _, keyCode, event ->
    if (keyCode == KeyEvent.KEYCODE_BACK && event.action == KeyEvent.ACTION_UP) {
        if (webView.canGoBack()) {
            webView.goBack()
        } else {
            finish()
        }
        true
    } else false
}

그래도 깨지는 화면이 있다면, 해당 URL만 기억해 두었다가 GET으로 다시 로드하는 편이 확실합니다.

대응 C — 오류를 잡아 한 번 재시도

사용자에게 회색 오류 페이지를 보여주지 않기 위한 안전망입니다.

webView.webViewClient = object : WebViewClient() {

    private var retried = false

    override fun onReceivedError(
        view: WebView, request: WebResourceRequest, error: WebResourceError
    ) {
        // 메인 프레임의 캐시 미스만 재시도 (이미지·광고 실패는 무시)
        if (!request.isForMainFrame) return
        if (error.errorCode != ERROR_UNKNOWN &&
            error.description?.contains("CACHE_MISS") != true) return

        if (!retried) {
            retried = true
            view.settings.cacheMode = WebSettings.LOAD_NO_CACHE
            view.loadUrl(request.url.toString())
        }
    }
}

"매번 LOAD_NO_CACHE로 하면 되지 않나요"

증상은 사라집니다. 대신 모든 요청이 네트워크로 나갑니다. 이미지와 CSS까지 매번 다시 받으므로 화면 전환이 눈에 띄게 느려지고 데이터도 더 씁니다. 원인 ①·③이 진짜 이유였다면, 문제를 덮은 채 성능만 잃는 선택입니다.

임시 확인용으로는 유용합니다. LOAD_NO_CACHE로 바꿨을 때 바로 해결되면 원인 ②, 그래도 안 되면 원인 ①일 가능성이 큽니다. 진단 도구로 쓰고 되돌리세요.

Flutter · React Native일 때

점검 순서

자주 묻는 질문

Q. 권한도 있고 캐시 모드도 기본값인데 계속 납니다.

실패하는 시점을 보세요. 버튼을 누른 직후나 뒤로가기에서만 난다면 POST 히스토리 문제라 설정으로는 안 풀립니다. 서버 쪽 리다이렉트(PRG) 또는 앱에서의 재로드로 접근해야 합니다.

Q. 크롬에서는 되는데 웹뷰에서만 납니다.

정상입니다. 크롬은 자체 캐시와 네트워크 스택 설정을 쓰고, 웹뷰는 앱이 지정한 설정을 씁니다. 비교 대상이 아니라 서버가 살아 있다는 확인용으로만 쓰세요.

Q. 에뮬레이터에서만 납니다.

에뮬레이터의 네트워크가 끊겨 있거나 프록시 설정이 남아 있는 경우가 많습니다. 브라우저 앱으로 아무 사이트나 열어 네트워크 자체를 먼저 확인하세요.

Q. 재시도 코드를 넣었더니 화면이 계속 깜빡입니다.

재시도 플래그가 없어 무한 루프에 빠진 것입니다. 한 번만 재시도하도록 막고, 성공 시(onPageFinished) 플래그를 초기화하세요.

정리

ERR_CACHE_MISS는 "캐시에서 못 찾았고, 네트워크로도 못 갔다"는 신호입니다. 그래서 답이 하나가 아닙니다. 권한이 없어서 네트워크로 못 간 것인지, 캐시 모드가 네트워크를 막은 것인지, 애초에 캐시가 있을 수 없는 POST 페이지인지를 먼저 가르는 것이 해결의 전부입니다.

가장 빠른 진단은 앱 데이터를 지우고 첫 실행에서 재현해 보는 것입니다. 그때 모든 페이지가 실패하면 권한, 특정 화면만 실패하면 캐시 모드, 버튼을 누른 뒤에만 실패하면 POST입니다.

어느 날 아침 애드몹에서 메일이 왔습니다. 무효 활동으로 계정이 30일 정지되었고, 그 기간 광고는 한 건도 게재되지 않는다는 내용이었습니다. 며칠 뒤에는 애드센스까지 같은 사유로 멈췄습니다. 게시자 코드가 같기 때문에 앱에서 난 문제가 웹 수익까지 끊어버린 것입니다.

제일 먼저 든 생각은 "내가 눌렀나"였습니다. 아닙니다. 개발 중에는 테스트 광고 단위만 씁니다. 그다음은 "에뮬레이터인가"였고, 이것도 아니었습니다. 며칠에 걸쳐 애드몹 리포트를 기기별·시간별로 쪼개 보고 나서야 진짜 범인을 찾았습니다.

앱을 올릴 때마다 구글이 돌리는 자동 검사 로봇이 제 배너를 눌렀습니다.

실측 — 한 시간에 34번, CTR 106%

애드몹 리포트를 기기 모델 차원으로 나눠 보면 범인이 바로 드러납니다. 정지 이틀 전 오후 두 시대에, 제 앱 하나에서 이런 숫자가 찍혀 있었습니다.

이 기기는 누구인가

OnePlus 8 Pro / Android 11 조합은 구글이 앱 바이너리를 검사할 때 쓰는 자동화 기기입니다. 앱을 업로드하면 구글은 실제 기기에서 앱을 설치하고 실행해 크래시·정책 위반을 확인합니다. 그 로봇이 화면을 훑다가 배너를 반복해서 탭한 것입니다.

여기서 제가 한 번 크게 틀렸습니다. 처음에는 이것을 "Play 사전 출시 보고서"라고 단정하고 그 위에 대책을 쌓았습니다. 틀렸습니다.

정리하면 이렇습니다. 배포가 곧 자동 검사이고, 자동 검사가 곧 무효 클릭입니다. 가드 없이 실광고가 들어간 빌드를 올리는 행위 자체가 위험을 만듭니다.

흔히 하는 오해 두 가지

오해 1 — "에뮬레이터 때문이다"

아닙니다. 애드몹은 에뮬레이터를 알아서 테스트 기기로 취급합니다. 제 계정도 90일 실측에서 에뮬레이터 노출이 0이었습니다. 반면 심사 로봇은 실기기라서 그 필터에 걸리지 않습니다.

오해 2 — "구글 IP라서 알아서 걸러준다"

웹에 이런 글이 많지만, 제 계정 정지가 그 반증입니다. 걸러줬다면 애초에 클릭 34건이 리포트에 집계되지 않았을 것입니다.

막는 방법 — 로봇에게는 광고를 요청하지 않는다

정책을 우회하는 이야기가 아닙니다. 방향은 정반대로, 구글이 요구하는 "무효 활동 방지"를 개발자가 코드로 이행하는 것입니다. 테스트 환경에 실광고를 띄우지 않는 것과 같은 원칙입니다.

제가 쓰는 가드는 세 겹입니다. 한 겹만으로는 새는 구멍이 있었습니다.

object AdGuard {

    /** 광고를 로드해도 되는 환경인가 */
    fun adsAllowed(context: Context): Boolean {
        if (isTestLab(context)) return false      // 1겹
        if (isReviewDevice()) return false        // 2겹
        return true
    }

    // 1겹 — Firebase Test Lab 계열 자동화
    private fun isTestLab(context: Context): Boolean =
        "true" == Settings.System.getString(
            context.contentResolver, "firebase.test.lab")

    // 2겹 — 심사 자동 검사 기기 모델
    private fun isReviewDevice(): Boolean =
        Build.MODEL == "OnePlus8Pro"
}

그리고 광고를 로드하는 모든 지점에서 이 함수를 통과해야만 요청이 나가도록 배선합니다. 지점 하나라도 빠지면 그 자리에서 다시 터집니다.

// 배너
if (AdGuard.adsAllowed(this)) {
    adView.loadAd(AdRequest.Builder().build())
} else {
    adView.visibility = View.GONE   // 자리도 비운다
}

// 전면 · 보상형도 동일하게
if (AdGuard.adsAllowed(this)) {
    InterstitialAd.load(this, unitId, request, callback)
}

3겹 — 클릭 패턴 자체를 본다

모델명은 언젠가 바뀔 수 있습니다. 그래서 기기 정보와 무관하게 비정상적인 클릭 리듬이면 그 세션의 광고를 내리는 겹을 하나 더 뒀습니다.

// 같은 세션에서 광고 클릭이 짧은 간격으로 반복되면
// 이후 광고 요청을 그 세션 동안 중단한다
private val clickTimes = ArrayDeque<Long>()

fun onAdClicked() {
    val now = SystemClock.elapsedRealtime()
    clickTimes.addLast(now)
    while (clickTimes.isNotEmpty() && now - clickTimes.first() > 60_000) {
        clickTimes.removeFirst()
    }
    if (clickTimes.size >= 3) blockedForSession = true
}

같이 점검해야 할 것들

정지된 뒤에 할 수 있는 것

솔직히 많지 않습니다. 30일 정지는 해제 신청으로 앞당겨지지 않았습니다. 다만 두 가지는 했습니다.

• 무효 활동 신고 양식 제출 — 게시자 스스로 비정상 트래픽을 신고하는 창구가 있습니다. 원인 분석과 조치 내용을 함께 적었습니다.
• 가드를 넣은 빌드를 전 앱에 배포 — 정지 기간에도 배포는 됩니다. 해제 시점에 이미 막혀 있는 상태로 맞이하는 것이 목적입니다.

자주 묻는 질문

Q. 정말 제가 클릭한 게 아니라고 확신할 수 있나요?

기기 모델 차원으로 나눠 보면 확인됩니다. 제 손에 없는 모델에서, 한 시간에, CTR 100%가 넘게 발생했다면 사람의 사용 패턴이 아닙니다. 애드몹 리포트에서 기기 모델을 축으로 놓고 보는 것이 첫 단계입니다.

Q. 사전 출시 보고서를 끄면 해결되나요?

안 됩니다. 사전 출시 보고서는 비공개 테스트 트랙에서만 생성되는데, 그 트랙이 없는 앱에도 이 검사는 옵니다. 별개의 심사 절차이고 콘솔에서 끌 수 없습니다.

Q. 앱 광고 문제인데 왜 애드센스까지 멈추나요?

애드몹과 애드센스가 같은 게시자 코드를 공유하기 때문입니다. 앱과 웹을 함께 운영한다면, 앱 쪽 사고 하나가 웹 수익까지 끊는다는 점을 감안해야 합니다.

Q. 모델명으로 막는 게 정책 위반은 아닌가요?

무효 클릭을 줄이는 방향입니다. 구글은 게시자에게 무효 활동을 방지할 책임을 요구하고, 자동화 환경에는 실광고 대신 테스트 광고를 쓰도록 안내합니다. 심사 로봇에 광고를 요청하지 않는 것은 그 연장선입니다. 반대로 사람 사용자에게만 광고를 감추는 식의 조작은 당연히 안 됩니다.

Q. 광고가 안 나올 때의 오류 코드는 어디서 보나요?

그것은 이 글과 다른 문제입니다. 로드 자체가 실패하는 경우(NO_FILL 등)는 오류 코드별로 원인이 갈립니다.

정리

무효 클릭이라고 하면 대부분 "내가 눌렀나", "누가 악의적으로 눌렀나"를 먼저 떠올립니다. 저는 배포 과정 자체가 클릭원이었습니다. 앱을 올릴 때마다 검사 로봇이 실행되고, 그 로봇이 배너를 누릅니다.

대책은 단순합니다. 자동화 환경에는 광고를 요청하지 않는 것, 그리고 그 판단을 모든 광고 로드 지점에 예외 없이 배선하는 것입니다. 앱을 여러 개 운영한다면 한 개라도 빠지면 소용이 없습니다. 계정은 앱 단위가 아니라 게시자 단위로 정지되기 때문입니다.

가장 잡기 어려운 버그는 내 손에서 재현되지 않는 버그입니다. 제 폰에서도, 에뮬레이터에서도, 실기기 서너 대에서도 멀쩡한 앱이 구글에 올리기만 하면 심사 단계에서 "시작 후 즉시 종료"로 잡혔습니다.

원인은 광고 동의창(UMP)이었습니다. 정확히는 그 동의창이 제 폰에서는 아예 뜨지 않는다는 사실이었습니다.

증상

재현이 안 되니 로그도 못 봅니다. "테스트 기기가 이상한 거겠지" 하고 넘기기 딱 좋은 형태입니다. 그러다 그 빌드가 그대로 출시됩니다.

왜 내 폰에서는 재현되지 않았나

UMP(User Messaging Platform)는 개인정보 처리 동의를 받아야 하는 지역에서만 동의 폼을 띄웁니다. 유럽 경제 지역(EEA)·영국 등이 대상이고, 한국에서 실행하면 폼이 뜰 이유가 없습니다.

즉 제 폰에서는 동의창을 띄우는 코드 경로 자체가 실행된 적이 없었습니다. 문제가 없었던 게 아니라, 문제가 있는 코드를 한 번도 지나간 적이 없었던 것입니다.

진짜 원인 — 초기화 순서

동의창은 앱이 처음 뜨는 순간, 화면이 아직 자리를 잡기 전에 액티비티 위에 올라옵니다. 그래서 동의 폼 요청을 화면 설정보다 먼저 부르면 창이 붙는 시점이 어긋납니다.

제 경우 enableEdgeToEdge()보다 동의 초기화를 앞에 뒀던 것이 문제였습니다. 이 호출은 창이 시스템 바 영역까지 그리도록 window 설정을 바꾸는 작업인데, 그 전에 동의 폼이 같은 창에 붙으려 하면 앱이 시작 단계에서 무너졌습니다.

// ❌ 죽는다 — 내 폰에서는 폼이 안 떠서 티가 안 난다
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        gatherConsentAndInitAds()     // ← 여기서 폼이 뜨는 지역이면 사고
        enableEdgeToEdge()
        setContent { MyApp() }
    }
}

// ✅ 화면 설정을 먼저 끝내고 나서 동의를 요청한다
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()            // ← window 설정이 먼저
        super.onCreate(savedInstanceState)

        setContent { MyApp() }

        gatherConsentAndInitAds()     // ← 화면이 준비된 뒤
    }
}

동의 요청 코드 — 전체 흐름

UMP는 "정보 갱신 → 필요하면 폼 표시 → 광고 초기화" 3단계입니다. 각 단계에서 흔히 빠뜨리는 것을 함께 적었습니다.

private var adsInitialized = AtomicBoolean(false)

fun gatherConsentAndInitAds(activity: Activity) {
    val params = ConsentRequestParameters.Builder().build()
    val info = UserMessagingPlatform.getConsentInformation(activity)

    info.requestConsentInfoUpdate(activity, params,
        {
            // 폼이 필요하면 띄우고, 아니면 즉시 콜백
            UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { error ->
                if (error != null) {
                    Log.w("Consent", "${error.errorCode}: ${error.message}")
                }
                // ★ 실패해도 진행한다 — 여기서 멈추면 광고가 영영 안 붙는다
                if (info.canRequestAds()) initAds(activity)
            }
        },
        { error ->
            Log.w("Consent", "update 실패 ${error.errorCode}: ${error.message}")
            // 네트워크 실패 등 — 이전에 저장된 동의 상태로 판단
            if (info.canRequestAds()) initAds(activity)
        }
    )
}

private fun initAds(context: Context) {
    if (!adsInitialized.compareAndSet(false, true)) return   // 중복 초기화 방지
    MobileAds.initialize(context)
}

핵심 — 지역을 강제해서 직접 재현하기

이 문제의 진짜 해법은 코드 수정이 아니라 재현 방법을 갖는 것입니다. UMP는 디버그 설정으로 지역을 EEA로 강제할 수 있습니다. 이걸 모르면 영원히 자기 손에서 확인할 수 없습니다.

// ⚠ 디버그 빌드에서만
val debugSettings = ConsentDebugSettings.Builder(activity)
    .setDebugGeography(
        ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("여기에 로그캣에 찍힌 해시 ID")
    .build()

val params = ConsentRequestParameters.Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

테스트 기기 해시 ID는 앱을 한 번 실행하면 로그캣에 찍힙니다. Use new ConsentDebugSettings.Builder().addTestDeviceHashedId(...) 형태의 안내 로그를 찾으면 됩니다.

// 테스트를 반복할 때는 저장된 동의 상태를 지운다
UserMessagingPlatform.getConsentInformation(activity).reset()

재현 안 되는 크래시를 잡는 일반적인 순서

화면이 잘리는 문제라면 — 다른 글

자주 묻는 질문

Q. 한국 서비스만 할 건데 UMP를 꼭 넣어야 하나요?

앱 스토어는 국가를 가리지 않고 노출되고, 광고 정책상 대상 지역 사용자가 들어오면 동의 처리가 필요합니다. 그리고 넣는 것 자체보다 넣고 나서 그 경로를 한 번도 테스트하지 않는 것이 더 위험합니다.

Q. 동의창이 아예 안 뜹니다. 잘못된 건가요?

대상 지역이 아니면 안 뜨는 것이 정상입니다. 확인하려면 디버그 지역을 EEA로 강제하고 reset() 후 다시 실행하세요.

Q. 동의를 거부하면 광고를 못 붙이나요?

맞춤 광고를 못 붙이는 것이고, canRequestAds()가 참이면 비맞춤 광고는 가능합니다. 이 값을 보고 분기해야지, 동의 여부를 직접 해석하려 들면 어긋납니다.

Q. 검사 기기에서만 죽는데 그냥 무시하면 안 되나요?

그 검사를 통과하지 못하면 배포가 막히거나 정책 문제로 이어집니다. 더 중요한 건, 검사 기기에서 죽는다는 것은 대상 지역의 실제 사용자에게도 똑같이 죽는다는 뜻이라는 점입니다.

Q. 동의 초기화를 Application에서 하면 안 되나요?

동의 폼은 액티비티가 있어야 띄울 수 있습니다. Application에서는 폼을 띄울 수 없으므로, 광고 SDK 초기화와 동의 요청 시점을 분리해 설계해야 합니다.

정리

"내 폰에서는 되는데"는 대부분 내 폰에서는 그 코드가 실행되지 않았다는 뜻입니다. 광고 동의창처럼 지역에 따라 갈리는 코드는 국내에서 아무리 테스트해도 한 번도 지나가지 않습니다.

대응은 두 가지입니다. 첫째, 창 설정을 먼저, 팝업을 나중에 부르는 순서를 지킬 것. 둘째, 디버그 지역 강제로 그 경로를 직접 밟아볼 것. 두 번째가 훨씬 중요합니다. 재현할 수 있으면 고치는 건 십 분이면 끝나기 때문입니다.

코드는 하나도 안 건드리고 targetSdk만 35로 올렸습니다. 그런데 안드로이드 15 기기에서 앱을 켜니 제목이 상태바에 파묻혀 있고, 화면 맨 아래 버튼은 내비게이션 바에 가려 눌리지 않습니다. 구형 기기에서는 멀쩡합니다.

버그가 아니라 안드로이드 15의 강제 사항입니다.

무슨 일이 일어난 건가

targetSdk = 35인 앱이 안드로이드 15에서 실행되면, OS가 edge-to-edge를 강제로 적용합니다. 앱 화면이 상태바와 내비게이션 바 아래까지 확장되어 그려지고, 시스템 바는 투명해집니다.

의도는 좋습니다. 화면을 끝까지 쓰는 요즘 디자인이 기본이 되는 것이죠. 문제는 앱이 그 사실을 모르면 중요한 UI가 시스템 바 밑에 깔린다는 점입니다.

급하다면 — 임시 opt-out (기한이 있다)

당장 배포해야 한다면 강제 적용을 끌 수 있습니다.

<!-- res/values/themes.xml -->
<style name="Theme.MyApp" parent="Theme.Material3.DayNight">
    <item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>
</style>

왜 유예 기간이 짧은가 — Play의 타깃 API 요구

구글 플레이는 매년 타깃 API 하한을 올립니다. 2026년 기준으로 정리하면 이렇습니다.

즉 앱을 계속 업데이트할 생각이라면 36으로 가야 하고, 36으로 가면 opt-out은 사라집니다. 인셋 처리를 미룰수록 나중에 한꺼번에 밀려옵니다.

제대로 고치기 — Compose

Compose에서는 enableEdgeToEdge()를 호출하고, 인셋을 필요한 컴포저블에만 먹이는 것이 기본입니다.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()        // super 앞뒤 어디든 되지만 setContent 전에
        super.onCreate(savedInstanceState)

        setContent { MyApp() }
    }
}

가장 간단한 방법은 Scaffold가 주는 패딩을 실제로 쓰는 것입니다. Material3의 Scaffold는 시스템 바 인셋을 계산해 innerPadding으로 넘겨줍니다. 이걸 무시하고 버리는 코드가 사고의 8할입니다.

@Composable
fun MyApp() {
    Scaffold(
        topBar = { TopAppBar(title = { Text("제목") }) }
    ) { innerPadding ->
        // ❌ innerPadding 을 안 쓰면 툴바 밑에 깔린다
        // LazyColumn { ... }

        // ✅ 반드시 적용
        LazyColumn(
            modifier = Modifier.padding(innerPadding)
        ) { /* ... */ }
    }
}

스크롤 화면은 padding이 아니라 contentPadding

리스트에 Modifier.padding()을 주면 스크롤 영역 자체가 줄어들어 콘텐츠가 시스템 바 밑으로 자연스럽게 흘러가는 느낌이 사라집니다. 리스트는 contentPadding을 써야 합니다.

LazyColumn(
    contentPadding = innerPadding      // 항목만 밀린다, 스크롤은 끝까지
) {
    items(list) { /* ... */ }
}

Scaffold를 안 쓰는 화면

Box(
    modifier = Modifier
        .fillMaxSize()
        .windowInsetsPadding(WindowInsets.safeDrawing)   // 시스템 바 + 컷아웃
) { /* ... */ }

// 아래쪽만 필요할 때
Modifier.windowInsetsPadding(
    WindowInsets.navigationBars.only(WindowInsetsSides.Bottom))

제대로 고치기 — View · XML

XML 레이아웃이라면 리스너로 인셋을 받아 패딩에 반영합니다.

override fun onCreate(savedInstanceState: Bundle?) {
    enableEdgeToEdge()
    super.onCreate(savedInstanceState)
    setContentView(binding.root)

    ViewCompat.setOnApplyWindowInsetsListener(binding.root) { view, windowInsets ->
        val bars = windowInsets.getInsets(
            WindowInsetsCompat.Type.systemBars()
                or WindowInsetsCompat.Type.displayCutout()
        )
        view.updatePadding(
            left = bars.left, top = bars.top,
            right = bars.right, bottom = bars.bottom
        )
        WindowInsetsCompat.CONSUMED
    }
}

키보드가 입력창을 가릴 때

edge-to-edge에서는 adjustResize만으로 부족한 경우가 많습니다. IME 인셋을 직접 반영하세요.

val ime = windowInsets.getInsets(WindowInsetsCompat.Type.ime())
view.updatePadding(bottom = maxOf(bars.bottom, ime.bottom))

상태바 아이콘이 안 보일 때

시스템 바가 투명해지면서 밝은 배경에 흰 아이콘이 겹쳐 시계가 안 보이는 일이 생깁니다. 아이콘 명암을 앱이 지정해야 합니다.

WindowCompat.getInsetsController(window, window.decorView).apply {
    isAppearanceLightStatusBars = true      // 밝은 배경 → 어두운 아이콘
    isAppearanceLightNavigationBars = true
}

앱이 아예 안 뜬다면 — 다른 문제다

점검 순서

자주 묻는 질문

Q. 내 폰에서는 멀쩡한데요?

기기의 OS 버전이 안드로이드 15 미만이면 강제 적용이 일어나지 않습니다. 15 이상 기기나 에뮬레이터에서 확인해야 합니다.

Q. opt-out을 계속 쓰면 안 되나요?

targetSdk 35인 동안만 됩니다. 36으로 올리면 이 속성은 무시되고, 앱 업데이트를 제출하려면 36으로 올려야 하는 시점이 정해져 있습니다. 결국 시간 문제입니다.

Q. Compose Material3를 쓰는데도 겹칩니다.

TopAppBar·BottomAppBar는 자체적으로 인셋을 처리하지만, Scaffold가 넘겨주는 innerPadding을 콘텐츠에 적용하는 것은 개발자 몫입니다. 이 패딩을 안 쓰면 본문이 바 밑으로 들어갑니다.

Q. Flutter · React Native도 같은 문제가 나나요?

납니다. 네이티브 컨테이너가 edge-to-edge로 바뀌기 때문입니다. React Native는 react-native-safe-area-context의 SafeAreaView로, Flutter는 SafeArea 위젯으로 대응하고, 프레임워크·플러그인 버전을 함께 올려야 하는 경우가 많습니다.

Q. 상태바를 그냥 불투명하게 칠하면 안 되나요?

배경색을 칠하는 방식은 안드로이드 15에서 더 이상 의도대로 동작하지 않습니다. 상단 바의 배경을 시스템 바 밑까지 확장하고, 그 안의 텍스트·아이콘만 인셋만큼 밀어내는 것이 권장 방식입니다.

정리

안드로이드 15의 edge-to-edge 강제는 "앱이 화면 전체를 그리게 하고, 시스템 바를 피하는 책임은 앱에 준다"는 변경입니다. 그래서 대응의 핵심도 하나입니다. 인셋을 받아서 실제로 반영하는 것.

windowOptOutEdgeToEdgeEnforcement는 급한 배포를 넘기는 용도로만 쓰세요. targetSdk 36에서는 통하지 않고, Play의 타깃 API 요구 때문에 36으로 올려야 하는 시점이 이미 정해져 있습니다. 미룰수록 한꺼번에 밀려옵니다.

ETF를 고를 때 총보수만 비교하는 경우가 많습니다. 그런데 연 0.01% 보수 차이보다 훨씬 큰 손실이 매매하는 순간에 발생할 수 있습니다. 괴리율 때문입니다.

괴리율과 추적오차는 이름이 비슷해 자주 섞여 쓰이지만 원인도 다르고 대응법도 다릅니다. 하나는 내가 피할 수 있는 것이고, 하나는 상품을 고를 때 봐야 하는 것입니다.

한 장으로 보는 차이

괴리율 — 지금 이 가격이 제값인가

ETF에는 두 개의 가격이 있습니다.

• NAV(순자산가치) — ETF가 담고 있는 자산의 실제 가치. 하루 한 번 계산됩니다.
• iNAV(실시간 추정 순자산가치) — 장중에 실시간으로 추정한 값
• 시장가격 — 지금 거래되는 값

괴리율은 이 둘의 차이입니다.

괴리율(%) = (시장가격 - NAV) ÷ NAV × 100

괴리율이 양수(+)면 제값보다 비싸게 거래되는 것이고, 음수(-)면 싸게 거래되는 것입니다. 비싸게 사서 싸게 파는 일이 반복되면, 지수가 올랐는데도 내 수익률은 시원치 않은 상황이 생깁니다.

왜 벌어지는가

ETF에는 LP(유동성공급자)가 붙어 있습니다. 시장가격이 iNAV에서 벌어지면 LP가 반대편 호가를 내서 좁혀 주는 역할을 합니다. 그래서 평소에는 괴리율이 거의 없습니다.

문제는 LP가 호가를 내지 않는 시간대가 있다는 것입니다.

★ LP 호가가 없는 시간 — 이때 사면 손해 본다

LP는 아래 시간대에 호가 제출 의무가 없습니다.

실천 원칙은 단순합니다.

• 장 시작 5분과 마감 10분을 피해 09:05 이후 - 15:20 이전에 매매한다
• 시장가 대신 지정가로 주문한다 (거래량이 적은 ETF일수록 중요)
• 주문 전 iNAV와 현재가를 비교한다

거래소가 정한 관리 기준

LP는 종가 기준 괴리율을 일정 수준 안에서 관리할 의무가 있고, 이 기준은 강화되는 추세입니다.

해외 자산 기준이 더 느슨한 데는 이유가 있습니다.

해외 ETF의 괴리율이 큰 이유

국내에 상장된 미국 지수 ETF는 한국 장중에 미국 시장이 닫혀 있습니다. 기초자산의 실시간 가격이 없는 상태에서 거래되는 것이죠. 그래서 시장의 기대가 가격에 먼저 반영되면서 괴리가 벌어지기 쉽습니다.

미국 시장이 급등락한 다음 날 아침, 국내 상장 미국 ETF가 제값보다 비싸게 시작하는 경우를 흔히 볼 수 있는데 대부분 이 때문입니다. 이런 날 장 시작 직후에 시장가로 사면 그 프리미엄을 그대로 부담하게 됩니다.

추적오차 — 이 상품이 지수를 잘 따라가는가

추적오차는 ETF가 기초지수를 얼마나 정확히 따라가는지를 나타냅니다. 매매 타이밍과 무관하게 상품 자체의 품질입니다.

주요 원인은 이렇습니다.

같은 지수를 추종하는 ETF가 여러 개일 때, 총보수가 조금 더 싼데 추적오차가 큰 상품이 있습니다. 이 경우 보수 차이보다 추적오차 손실이 클 수 있으니 둘을 같이 봐야 합니다.

어디서 확인하나

1. 운용사 홈페이지 — 상품 페이지에 NAV, 괴리율, 추적오차가 공시됩니다. 가장 정확합니다.
2. KRX 정보데이터시스템 — 전 종목의 괴리율·추적오차를 한자리에서 비교할 수 있습니다.
3. HTS·MTS — 현재가 화면에서 iNAV를 표시해 줍니다. 주문 직전에 현재가와 비교하세요.

자주 묻는 질문

Q. 괴리율이 크면 무조건 나쁜 상품인가요?

아닙니다. 괴리율은 순간의 가격 상태라서 상품의 품질과 직접 연결되지 않습니다. 다만 괴리율이 상시로 큰 종목은 거래량이 부족하다는 신호이므로 피하는 편이 낫습니다.

Q. 추적오차가 0인 ETF도 있나요?

없습니다. 총보수가 매일 차감되기 때문에 구조적으로 지수보다 조금씩 뒤처집니다. 중요한 건 0인지가 아니라 같은 지수를 추종하는 다른 상품과 비교했을 때 어느 쪽이 작은가입니다.

Q. 장 시작하자마자 사면 정말 손해인가요?

항상 그런 건 아니지만 불리해질 확률이 높습니다. 09:00부터 09:05까지는 LP 호가 의무가 없어 가격이 제값에서 벌어져 있을 수 있습니다. 급하지 않다면 09:05 이후를 권합니다.

Q. 적립식으로 매달 사는데도 신경 써야 하나요?

오히려 더 중요합니다. 매달 반복되면 누적되기 때문입니다. 자동 매수를 쓴다면 체결 시간이 언제로 설정되는지 확인해 보세요. 장 시작 직후로 잡혀 있다면 조정할 만합니다.

정리

괴리율은 내가 피할 수 있고, 추적오차는 고를 때 걸러야 합니다.

• 매매는 09:05 이후 - 15:20 이전, 지정가로
• 거래량이 적은 ETF일수록 괴리율에 민감하게
• 해외 지수 ETF는 급등락 다음 날 아침 프리미엄을 조심
• 상품을 고를 때는 총보수만 보지 말고 거래량과 추적오차를 함께

연 0.01%의 보수 차이를 따지는 것보다, 매수 버튼을 5분 늦게 누르는 편이 더 큰 차이를 만드는 경우가 많습니다.

윈도우 업데이트가 설치 도중에 실패하고 계속 같은 걸 다시 시도하는 상황이 있습니다. 재부팅을 해도, 며칠을 기다려도 똑같은 오류 코드가 반복되죠.

여기서 중요한 건 오류 코드마다 원인이 완전히 다르다는 점입니다. 어떤 건 디스크 공간 문제고, 어떤 건 서비스가 꺼진 것이고, 어떤 건 숨겨진 복구 파티션이 작아서 생깁니다. 코드를 무시하고 아무 해결법이나 따라 하면 시간만 버립니다.

먼저 — 공통 점검 5단계

어떤 코드든 아래 다섯 가지로 해결되는 경우가 많습니다. 순서대로 진행하세요. 전부 되돌릴 수 있는 안전한 작업입니다.

1) 업데이트 문제 해결사

설정 → 시스템 → 문제 해결 → 기타 문제 해결사 → Windows Update 에서 실행합니다. 가장 먼저 해볼 일이고, 실제로 여기서 끝나는 경우가 꽤 있습니다.

2) 디스크 여유 공간 확보

업데이트는 압축을 풀 공간이 필요합니다. C 드라이브 여유 공간이 10GB 미만이면 이것부터 해결하세요. 설정 → 시스템 → 저장 공간에서 임시 파일을 정리하면 됩니다.

3) 시스템 파일 검사

명령 프롬프트를 관리자 권한으로 열고 차례로 실행합니다.

sfc /scannow

DISM /Online /Cleanup-Image /RestoreHealth

sfc가 손상된 시스템 파일을 고치고, DISM은 윈도우 이미지 자체를 복구합니다. sfc가 "복구할 수 없다"고 하면 DISM을 먼저 돌린 뒤 sfc를 다시 실행하세요. 각각 10분 이상 걸릴 수 있습니다.

4) 업데이트 캐시 초기화

받다 만 파일이 꼬여 있으면 계속 같은 지점에서 실패합니다. 캐시 폴더를 비우면 처음부터 다시 받습니다.

net stop wuauserv
net stop bits

ren C:\Windows\SoftwareDistribution SoftwareDistribution.old
ren C:\Windows\System32\catroot2 catroot2.old

net start wuauserv
net start bits

5) 관련 서비스 확인

services.msc를 실행해 아래 서비스가 켜져 있는지 봅니다.

오류 코드별 대처

0x80070643 — 복구 파티션 공간 부족

원래는 설치 실패 전반에 쓰이는 코드지만, 최근 이 코드로 보안 업데이트만 반복 실패한다면 원인이 꽤 특정됩니다. 윈도우 설치 시 만들어진 숨겨진 복구 파티션(WinRE)이 너무 작아서 업데이트를 적용하지 못하는 경우입니다.

공통 5단계로는 해결되지 않습니다. 마이크로소프트가 안내하는 정식 해결법은 주 파티션을 줄여 복구 파티션 공간을 늘리는 작업인데, 이건 디스크 구조를 직접 건드립니다.

현재 복구 파티션 상태만 확인하고 싶다면, 관리자 명령 프롬프트에서 아래로 볼 수 있습니다. 조회만 하는 명령이라 안전합니다.

reagentc /info

여기서 Windows RE 상태가 Enabled인지, 어느 파티션에 있는지 확인할 수 있습니다.

0x800f0922 — 공간 부족 또는 연결 차단

원인이 세 갈래입니다. 위에서부터 확인하세요.

회사 노트북처럼 VPN을 상시 연결해 두는 환경에서 특히 자주 나옵니다. 의외로 이것만 꺼도 해결되는 경우가 많습니다.

0x80070422 — 업데이트 서비스가 꺼져 있음

가장 단순한 코드입니다. Windows Update 서비스가 사용 안 함으로 설정된 상태입니다. 업데이트를 미루려고 서비스를 꺼둔 뒤 잊어버린 경우가 대부분입니다.

services.msc → Windows Update → 시작 유형을 수동으로 바꾸고 시작하면 됩니다.

0x8007000d / 0x80073712 — 파일 손상

업데이트 파일이 깨졌다는 뜻입니다. 공통 3단계(sfc + DISM)와 4단계(캐시 초기화)를 둘 다 수행한 뒤 재시도하세요.

0x80240034 / 0x8024402c — 다운로드 실패

네트워크 쪽 문제입니다. DNS를 바꿔보거나, 회사·학교 네트워크라면 업데이트 서버가 차단됐을 수 있으니 다른 네트워크에서 시도해 보세요.

그래도 안 될 때 — 수동 설치

특정 업데이트 하나만 계속 실패한다면, 그 업데이트를 직접 받아 설치하는 방법이 있습니다.

1. 설정 → Windows Update → 업데이트 기록에서 실패한 항목의 KB 번호를 확인 (예: KB5034441)
2. Microsoft 업데이트 카탈로그에서 그 KB 번호로 검색
3. 내 시스템에 맞는 버전(대부분 x64) 파일을 받아 실행

수동 설치도 같은 오류로 실패한다면, 원인이 업데이트 전달 과정이 아니라 시스템 자체에 있다는 신호입니다. 그때는 공통 3단계로 돌아가세요.

점검 순서 요약

자주 묻는 질문

Q. 업데이트를 아예 안 하면 안 되나요?

기능 업데이트는 미뤄도 되지만 보안 업데이트는 미루지 않는 편이 좋습니다. 다만 특정 업데이트 하나가 계속 실패한다면, 다음 누적 업데이트에 포함되어 자연히 해결되기도 합니다. 무리해서 파티션을 건드리기 전에 한 달 정도 기다려 보는 것도 방법입니다.

Q. sfc /scannow가 "복구할 수 없는 파일이 있다"고 합니다.

DISM /Online /Cleanup-Image /RestoreHealth를 먼저 실행해 윈도우 이미지를 복구한 다음, sfc /scannow를 다시 돌리세요. 순서를 바꾸면 결과가 달라집니다.

Q. SoftwareDistribution 폴더를 지워도 되나요?

업데이트가 정상화된 뒤라면 .old로 이름을 바꿔둔 폴더는 지워도 됩니다. 다만 처음부터 삭제하지 말고 이름 변경으로 시작하세요. 문제가 생겨도 되돌릴 수 있습니다.

Q. 오류 코드가 매번 다르게 나옵니다.

디스크 불량이나 메모리 문제일 수 있습니다. chkdsk C: /f와 윈도우 메모리 진단 도구로 하드웨어 쪽을 먼저 확인해 보세요.

정리

윈도우 업데이트 오류는 코드를 먼저 확인하는 것이 절반입니다. 공통 5단계로 상당수가 해결되고, 남는 건 코드별 원인이 뚜렷합니다. 0x800f0922의 VPN이나 0x80070422의 꺼진 서비스처럼 허무할 만큼 단순한 원인인 경우도 많으니, 파티션을 건드리는 위험한 작업은 항상 마지막에 두세요.

웹뷰로 띄운 페이지에서 사진 첨부 버튼을 눌렀는데 아무 일도 일어나지 않습니다. 모바일 브라우저에서는 갤러리가 잘 열리는데 앱 안에서만 먹통입니다. 서류 제출, 프로필 사진, 리뷰 사진 첨부처럼 <input type="file">을 쓰는 화면에서 반드시 만나는 문제입니다.

증상은 보통 두 가지로 나뉩니다.

원인 — 웹뷰에는 파일 선택 화면이 없다

웹 페이지에서 파일 선택 요소를 누르면 안드로이드는 WebChromeClient.onShowFileChooser()를 호출합니다. 브라우저 앱은 이걸 내부에서 알아서 처리하지만, 우리가 만든 웹뷰는 이 함수를 구현해 주지 않으면 아무것도 하지 않습니다. 눌러도 반응이 없는 이유입니다.

기본 구현

결과를 받을 런처를 먼저 만들고, onShowFileChooser에서 파일 선택 화면을 띄웁니다.

private var filePathCallback: ValueCallback<Array<Uri>>? = null

private val fileChooserLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    // 공식 헬퍼가 단일·복수 선택을 알아서 파싱해 준다
    val uris = WebChromeClient.FileChooserParams
        .parseResult(result.resultCode, result.data)
    filePathCallback?.onReceiveValue(uris)
    filePathCallback = null          // ★ 반드시 비운다
}

webView.webChromeClient = object : WebChromeClient() {

    override fun onShowFileChooser(
        webView: WebView?,
        callback: ValueCallback<Array<Uri>>?,
        params: FileChooserParams?
    ): Boolean {
        // 이전 요청이 남아 있으면 정리하고 시작
        filePathCallback?.onReceiveValue(null)
        filePathCallback = callback

        return try {
            fileChooserLauncher.launch(params?.createIntent())
            true                     // 우리가 처리했다
        } catch (e: ActivityNotFoundException) {
            filePathCallback = null
            false                    // 처리 못 했다
        }
    }
}

가장 많이 겪는 함정

함정 1 — 한 번은 되는데 두 번째부터 안 열린다

압도적으로 흔한 증상이고, 원인은 하나입니다. 사용자가 파일 선택을 취소했거나 권한을 거부했을 때 콜백을 비워주지 않은 것입니다.

// ❌ 취소했을 때 아무것도 안 하면
//    안드로이드는 "아직 파일 선택 중"이라고 판단한다
//    → 다음부터 onShowFileChooser 가 아예 호출되지 않는다

// ✅ 어떤 경로로 끝나든 반드시 값을 돌려준다
filePathCallback?.onReceiveValue(null)
filePathCallback = null

취소, 권한 거부, 예외 발생 — 모든 종료 경로에서 onReceiveValue()를 호출해야 합니다. 위 기본 구현에서 런처 콜백과 onShowFileChooser 진입부 양쪽에 정리 코드를 넣은 이유입니다.

함정 2 — 카메라로 바로 찍기가 안 된다

createIntent()는 보통 갤러리·파일 선택만 띄웁니다. "사진 촬영"도 같이 주려면 카메라 인텐트를 합쳐야 합니다.

val galleryIntent = params?.createIntent()

val photoFile = File(cacheDir, "capture_${System.currentTimeMillis()}.jpg")
val photoUri = FileProvider.getUriForFile(
    this, "$packageName.fileprovider", photoFile)   // ★ FileProvider 필수
cameraImageUri = photoUri

val cameraIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE).apply {
    putExtra(MediaStore.EXTRA_OUTPUT, photoUri)
}

val chooser = Intent(Intent.ACTION_CHOOSER).apply {
    putExtra(Intent.EXTRA_INTENT, galleryIntent)
    putExtra(Intent.EXTRA_TITLE, "사진 첨부")
    putExtra(Intent.EXTRA_INITIAL_INTENTS, arrayOf(cameraIntent))
}
fileChooserLauncher.launch(chooser)

val uris = if (result.data == null && cameraImageUri != null) {
    arrayOf(cameraImageUri!!)                 // 카메라로 찍은 경우
} else {
    FileChooserParams.parseResult(result.resultCode, result.data)
}

함정 3 — 카메라 인텐트에서 앱이 죽는다 (FileUriExposedException)

Uri.fromFile()로 만든 file:// 주소를 다른 앱에 넘기면 FileUriExposedException이 발생합니다. 반드시 FileProvider를 거쳐야 합니다.

<!-- AndroidManifest.xml -->
<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

함정 4 — 안드로이드 13부터 권한 이름이 바뀌었다

READ_EXTERNAL_STORAGE만 선언해 두면 안드로이드 13(API 33) 이상에서 동작하지 않습니다.

함정 5 — 자바스크립트나 파일 접근 설정 누락

webView.settings.apply {
    javaScriptEnabled = true
    domStorageEnabled = true
    allowFileAccess = true
    javaScriptCanOpenWindowsAutomatically = true
    setSupportMultipleWindows(true)   // 첨부창을 새 창으로 여는 페이지 대응
}

점검 순서

자주 묻는 질문

Q. WebViewClient에 넣었는데 왜 호출이 안 되나요?

onShowFileChooser는 WebChromeClient의 함수입니다. 이름이 비슷해 자주 혼동되는 부분인데, webChromeClient 쪽에 설정해야 합니다.

Q. 처음 한 번만 되고 이후로 먹통입니다.

함정 1입니다. 사용자가 취소했을 때 onReceiveValue(null)을 호출하지 않으면 이전 요청이 끝나지 않은 상태로 남아 다음 호출이 무시됩니다.

Q. 여러 장을 한 번에 올리고 싶습니다.

웹 페이지 쪽에 <input type="file" multiple>이 있으면 createIntent()가 복수 선택 인텐트를 만들고, parseResult()가 배열로 돌려줍니다. 앱에서 따로 처리할 필요는 없습니다.

Q. 파일은 선택되는데 서버에 안 올라갑니다.

이 경우는 웹뷰가 아니라 웹 페이지 쪽 문제일 가능성이 큽니다. 같은 페이지를 크롬 브라우저에서 열어 업로드가 되는지 먼저 확인해 보세요. 브라우저에서도 안 되면 서버·프론트 쪽을 봐야 합니다.

정리

웹뷰 파일 업로드는 onShowFileChooser를 구현하면 대부분 해결됩니다. 문제는 "한 번은 되는데 그 다음부터 안 되는" 상태인데, 이건 거의 항상 콜백을 비워주지 않아서 생깁니다. 어떤 경로로 끝나든 onReceiveValue()를 반드시 호출한다는 원칙만 지키면 재현이 사라집니다.

앱 안에 웹뷰로 결제창을 띄웠는데, 카드사 앱으로 넘어가야 할 순간에 이런 화면이 뜹니다.

net::ERR_UNKNOWN_URL_SCHEME

모바일 웹 브라우저에서는 잘 되는데 앱 안 웹뷰에서만 터집니다. 국내 결제(이니시스·토스페이먼츠·KG·나이스), 본인인증(NICE·KCB), 카카오 로그인 연동에서 거의 예외 없이 만나는 오류입니다.

원인 — 웹뷰는 http/https만 안다

결제창이 카드사 앱을 부를 때 실제로 넘기는 주소는 이렇게 생겼습니다.

intent://pay?orderId=1234#Intent;scheme=kftc-bankpay;
  package=com.kftc.bankpay.android;
  S.browser_fallback_url=https%3A%2F%2F...;end;

// 또는 카드사 전용 스킴
ispmobile://...
kakaotalk://...
market://details?id=...

브라우저(크롬)는 이런 주소를 만나면 스스로 해당 앱을 실행해 줍니다. 반면 WebView는 그런 기능이 없습니다. http와 https 외의 스킴은 어떻게 처리할지 앱이 직접 알려주지 않으면 그냥 실패합니다. 그 실패가 ERR_UNKNOWN_URL_SCHEME입니다.

기본 해결 — shouldOverrideUrlLoading에서 가로채기

웹뷰가 주소를 열기 직전에 끼어들어, http/https가 아니면 우리가 직접 앱을 실행해 주면 됩니다.

webView.webViewClient = object : WebViewClient() {

    override fun shouldOverrideUrlLoading(
        view: WebView, request: WebResourceRequest
    ): Boolean {
        val url = request.url.toString()

        // http/https 는 웹뷰가 그대로 처리하게 둔다
        if (url.startsWith("http://") || url.startsWith("https://")) return false

        return handleAppScheme(view, url)
    }
}

핵심은 handleAppScheme()입니다. intent://는 파싱이 필요하고, 그 외 앱 스킴은 바로 열면 됩니다.

private fun handleAppScheme(view: WebView, url: String): Boolean {
    val context = view.context

    // 1) intent:// 가 아닌 일반 앱 스킴 (ispmobile:// 등)
    if (!url.startsWith("intent://")) {
        return try {
            context.startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url)))
            true
        } catch (e: ActivityNotFoundException) {
            false   // 처리 못 하면 웹뷰에 맡긴다
        }
    }

    // 2) intent:// 는 Intent 객체로 파싱
    val intent = try {
        Intent.parseUri(url, Intent.URI_INTENT_SCHEME)
    } catch (e: URISyntaxException) {
        return false
    }

    // 3) 바로 실행하고, 실패하면 그때 대응한다  ★ 이 순서가 중요
    try {
        context.startActivity(intent)
        return true
    } catch (e: ActivityNotFoundException) {
        // 앱이 안 깔려 있는 경우
    }

    // 4) 결제창이 알려준 폴백 주소가 있으면 그리로
    intent.getStringExtra("browser_fallback_url")?.let { fallback ->
        view.loadUrl(fallback)
        return true
    }

    // 5) 없으면 스토어로 유도
    intent.`package`?.let { pkg ->
        try {
            context.startActivity(
                Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$pkg")))
        } catch (e: ActivityNotFoundException) {
            context.startActivity(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://play.google.com/store/apps/details?id=$pkg")))
        }
        return true
    }

    return false
}

인텐트 처리를 넣었는데도 안 될 때

여기까지는 검색하면 흔히 나오는 내용입니다. 그런데도 계속 실패한다는 문의가 끊이지 않는데, 대부분 아래 다섯 가지 중 하나입니다.

함정 1 — resolveActivity()로 먼저 확인하는 코드 (Android 11 이상)

오래된 예제에는 이런 패턴이 많습니다.

// ❌ Android 11(API 30)부터 깨지는 코드
if (intent.resolveActivity(packageManager) != null) {
    startActivity(intent)
} else {
    // 앱이 없다고 판단 → 실제로는 깔려 있는데도 여기로 빠진다
}

Android 11부터 패키지 가시성(package visibility) 정책이 생겼습니다. resolveActivity()와 queryIntentActivities()는 이 제약을 받기 때문에, <queries> 선언이 없으면 실제로 설치된 앱도 "없다"고 답합니다. 카드사 앱이 분명히 깔려 있는데 스토어로 보내버리는 증상이 이것입니다.

<queries> 선언이 필요한 경우는 따로 있습니다. "이 카드사 앱이 깔려 있는지"를 화면에 표시해야 해서 조회가 꼭 필요하다면, 그때는 매니페스트에 선언해야 합니다.

<!-- AndroidManifest.xml — 조회가 정말 필요할 때만 -->
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="ispmobile" />
    </intent>
</queries>

함정 2 — 구버전 기기에서만 실패

shouldOverrideUrlLoading은 시그니처가 두 개입니다. WebResourceRequest를 받는 쪽은 API 24 이상에서만 호출됩니다. minSdk가 그보다 낮다면 구형 기기에서는 우리 코드가 아예 실행되지 않습니다.

// API 24 미만도 지원한다면 둘 다 오버라이드
@Deprecated("API 24 미만 대응용")
override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
    if (url.startsWith("http://") || url.startsWith("https://")) return false
    return handleAppScheme(view, url)
}

함정 3 — 결제창이 새 창으로 뜨는 경우

PG사 결제창은 target="_blank"나 window.open()으로 새 창을 여는 구조가 많습니다. 이때는 shouldOverrideUrlLoading이 호출되지 않고 아무 반응이 없습니다. 멀티 윈도우를 켜고 onCreateWindow를 처리해야 합니다.

webView.settings.apply {
    javaScriptEnabled = true
    domStorageEnabled = true
    javaScriptCanOpenWindowsAutomatically = true
    setSupportMultipleWindows(true)      // ★ 새 창 허용
}

함정 4 — 앱 스킴이 intent:// 형태가 아닌 경우

Intent.parseUri()는 intent:// 형식을 위한 함수입니다. ispmobile://, kakaotalk:// 같은 순수 커스텀 스킴에 그대로 쓰면 원하는 대로 동작하지 않을 수 있습니다. 위 코드에서 1번과 2번을 나눈 이유입니다.

함정 5 — Flutter · React Native는 원인이 다르다

점검 순서

자주 묻는 질문

Q. 모바일 웹에서는 되는데 왜 앱에서만 안 되나요?

브라우저는 intent://를 만나면 스스로 앱을 실행해 주지만, WebView에는 그 기능이 없습니다. 앱이 직접 처리해 주지 않으면 실패합니다.

Q. resolveActivity()를 빼도 정말 괜찮나요?

괜찮습니다. startActivity()는 패키지 가시성 제약을 받지 않아 앱이 설치돼 있으면 정상 실행되고, 없으면 ActivityNotFoundException이 발생합니다. 그 예외를 잡아 폴백을 태우는 것이 Android 공식 문서의 권장 방식입니다.

Q. 에뮬레이터에서 자꾸 스토어로 넘어갑니다.

정상 동작입니다. 에뮬레이터에는 카드사 앱이 설치돼 있지 않아 폴백 경로를 타는 것입니다. 결제 연동 테스트는 실기기로 하세요.

Q. 모든 스킴을 다 열어줘도 보안상 괜찮나요?

주의가 필요합니다. 외부에서 주입된 주소로 임의의 앱을 실행할 수 있으면 위험합니다. 결제·인증처럼 도메인이 정해진 흐름이라면, 신뢰하는 호스트에서 출발한 요청인지 확인한 뒤 처리하는 편이 안전합니다.

정리

ERR_UNKNOWN_URL_SCHEME은 웹뷰가 http/https 외의 주소를 처리할 방법을 모르기 때문에 나는 오류입니다. shouldOverrideUrlLoading에서 가로채 Intent.parseUri()로 앱을 실행하고, 실패하면 browser_fallback_url과 스토어로 이어지는 경로를 만들어 두면 해결됩니다.

그래도 안 된다면 사전 확인 코드(resolveActivity)와 새 창 설정을 먼저 의심하세요. 코드를 제대로 넣고도 못 고치는 사례의 대부분이 이 둘입니다.