Android WebView에서 이미지나 스크립트가 안 나올 때 (Mixed Content, Cleartext Traffic 오류 해결)

Android WebView로 하이브리드 앱을 만들거나 기존 웹 서비스를 앱으로 감싸서 운영하다 보면 꼭 한 번씩 겪는 문제가 있습니다.

"PC나 모바일 브라우저에서는 잘 열리는데, 앱 WebView 안에서만 이미지나 스크립트가 안 보입니다." 하는 상황입니다.

저의 경우도 예전에 운영 서버와 테스트 서버를 오가며 세팅하다가 이 문제로 한참 헤맨 적이 있어서, 나중에도 참고하려고 깔끔하게 정리해 둡니다. 단순 화면 깨짐으로 넘기기에는 보안상 중요한 부분이라 제대로 짚고 넘어가야 합니다.

원인 및 차이점 간단 정리

원인은 크게 Mixed Content(혼합 콘텐츠)와 Cleartext Traffic(일반 텍스트 트래픽) 두 가지로 나뉩니다. 둘 다 HTTP 통신 보안 정책 때문에 발생하는 문제인데, 확인해야 하는 위치가 다릅니다.

  • Mixed Content: 메인 페이지는 https://로 안전하게 열렸는데, 그 안에서 불러오는 이미지, JS, CSS, 동영상 등의 주소가 http://로 되어 있는 경우입니다. WebView가 보안상 이 리소스 로드를 차단해 버립니다. (WebView 설정 영역)

  • Cleartext Traffic: 앱이 암호화되지 않은 생짜 http:// 통신 자체를 시도하는 것을 말합니다. Android 9 (API 28) 이상부터는 기본적으로 이 통신이 전부 차단됩니다. (Network Security Config, Manifest 영역)

가장 좋은 해결책은 당연히 모든 리소스를 HTTPS로 바꾸는 것입니다. 하지만 개발 중이거나 부득이한 예외 상황이 있다면 아래처럼 안전하게 도메인을 제한해서 풀어야 합니다.

안전한 WebView 설정 (Kotlin 코드)

화면이 깨진다고 해서 운영 앱의 WebView 설정을 MIXED_CONTENT_ALWAYS_ALLOW로 막 열어버리면 절대 안 됩니다. 중간에서 데이터가 변조될 위험이 크고 구글 플레이 심사에서도 거절 사유가 될 수 있습니다.

운영 앱에서는 MIXED_CONTENT_NEVER_ALLOW를 기본으로 두고, 아래처럼 안전하게 필요한 검증을 거치도록 세팅하는 것이 정답입니다.

Kotlin
class SecureMixedContentWebView(
    private val allowedHosts: Set<String>,
) {
    fun configure(webView: WebView) {
        webView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            // 운영 앱에서는 무조건 NEVER_ALLOW가 안전합니다.
            mixedContentMode = WebSettings.MIXED_CONTENT_NEVER_ALLOW
            allowFileAccess = false
            allowContentAccess = false
        }

        webView.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                view: WebView,
                request: WebResourceRequest,
            ): Boolean {
                val uri = request.url
                val scheme = uri.scheme ?: return true
                val host = uri.host ?: return true

                // 허용된 도메인의 HTTPS 주소만 WebView 내부에서 처리
                if (scheme == "https" && allowedHosts.contains(host)) {
                    return false
                }

                // HTTP 주소는 내부에서 열지 않고 차단하거나 외부 브라우저로 토스
                if (scheme == "http") {
                    Toast.makeText(
                        view.context,
                        "안전하지 않은 링크는 열 수 없습니다.",
                        Toast.LENGTH_SHORT,
                    ).show()
                    return true
                }

                openExternal(view.context, uri)
                return true
            }

            override fun onReceivedSslError(
                view: WebView,
                handler: SslErrorHandler,
                error: SslError,
            ) {
                // 주의: 당장 화면 띄우겠다고 handler.proceed() 쓰면 절대 안 됩니다.
                // 인증서 오류는 신뢰가 깨진 신호이므로 취소하는 게 맞습니다.
                handler.cancel()
            }
        }
    }

    private fun openExternal(context: Context, uri: Uri) {
        val intent = Intent(Intent.ACTION_VIEW, uri)
        if (intent.resolveActivity(context.packageManager) != null) {
            context.startActivity(intent)
        }
    }
}

로컬/테스트 서버 예외 처리 방법 (Network Security Config)

개발하다 보면 로컬 컴퓨터나 사내 테스트 서버(http://...)에 앱을 붙여야 할 때가 있습니다.

이때 귀찮다고 AndroidManifest.xml에 android:usesCleartextTraffic="true"를 넣어 앱 전체의 보안을 풀어버리는 실수를 자주 합니다. 이렇게 하면 안 되고, 딱 필요한 테스트 도메인만 지정해서 예외를 둬야 합니다.

우선 res/xml/network_security_config.xml 파일을 만들고 아래처럼 세팅합니다.

XML
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false" />

    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">insecure-dev.example.com</domain>
    </domain-config>
</network-security-config>

그다음 AndroidManifest.xml에 해당 설정을 연결해 줍니다. 여기서는 당연히 usesCleartextTraffic을 false로 잡거나 아예 지워주는 게 안전합니다.

XML
<application
    android:networkSecurityConfig="@xml/network_security_config"
    android:usesCleartextTraffic="false">
    </application>

이러면 운영 도메인은 안전하게 HTTPS로 돌리면서, 테스트 도메인만 예외로 HTTP 통신을 열어줄 수 있습니다. 더 안전하게 하려면 이 설정 파일 자체를 debug 소스 세트 폴더에만 넣어두고 release 빌드에서는 아예 빠지도록 분리하는 편이 좋습니다.

실무 적용 시 주의할 점 (체크리스트)

이래저래 서비스를 운영하다 보면 코드가 아니라 콘텐츠나 API 응답 때문에 문제가 생기는 경우가 많습니다. WebView 옵션을 건드리기 전에 아래 항목들을 먼저 체크해 보세요.

  • HTML 내부의 정적 리소스 URL 확인: 페이지 내부의 이미지, CSS, 스크립트 경로가 http://로 하드코딩 되어 있는지 검색해 봅니다. (CDN이나 정적 파일 서버 설정을 HTTPS로 바꾸는 게 근본적인 해결책입니다.)

  • API 응답 값 확인: 백엔드 API가 리턴해 주는 이미지 경로 파일 주소에 http://가 섞여 들어오지 않는지 확인합니다.

  • SSL 오류 발생 시 무조건 통과 금지: 인증서 만료나 사설 인증서 때문에 에러가 날 때 handler.proceed()로 대충 우회해 두면, 당장은 잘 작동하는 것처럼 보여도 중간자 공격(MitM)에 취약해집니다. 운영 앱에서는 무조건 서버 인증서 구성을 고쳐야 합니다.

  • 실제 도메인 노출 주의: 블로그나 깃허브에 예제 코드를 올리거나 로그를 남길 때는 내부 운영 서버 주소나 API 키가 쌩으로 노출되지 않도록 example.com 같은 예시 도메인으로 치환하는 버릇을 들여야 합니다.

마무리

결론적으로 WebView에서 화면이 깨지거나 리소스가 안 나올 때, 앱 설정을 낮춰서 편하게 우회하는 건 임시방편일 뿐입니다.

MIXED_CONTENT_NEVER_ALLOW와 cleartext 비허용을 뼈대로 잡고, HTTP로 나오는 소스들을 찾아서 HTTPS로 마이그레이션하는 방향으로 가야 운영 관점에서 뒤탈이 없습니다. 하이브리드 앱 개발할 때 자꾸 까먹는 포인트라 기록해 두니 필요할 때 참고하시기 바랍니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

안드로이드 화면 꺼짐 방지 FLAG_KEEP_SCREEN_ON 및 WakeLock 적용 방법

이래저래 시험 타이머나 운동 기록, 지도 내비게이션 같은 앱을 개발하다 보면 사용자가 화면을 가만히 쳐다보고 있어야 하는 상황이 자주 생깁니다. 이때 대충 구현하면 스마트폰 설정에라 맞춰진 화면 자동 꺼짐 시간 때문에 화면이 픽 꺼져버려서 사용자가 불편을 겪게 됩니다. 처음에는 그냥 "화면 안 꺼지게 백그라운드에서 계속 돌리면 되겠지" 하고 접근하기 쉬운데, 운영하다 보면 배터리가 광탈하거나 앱을 껐는데도 화면이 계속 켜져 있는 등 온갖 버그성 문제가 터지곤 합니다. 저의 경우도 타이머 앱을 만들 때 화면 유지와 백그라운드 상태 관리를 제대로 분리하지 못해 고생했던 기억이 있습니다. 자꾸 까먹기도 하고 나중에 프로젝트할 때 바로 복사해서 쓰려고 실무 기준으로 핵심만 정리해 둡니다. 헷갈리기 쉬운 핵심 개념: 화면 유지 vs CPU 작업 유지 가장 먼저 확인해야 할 점은 화면만 계속 켜둘 것인가 , 아니면 화면이 꺼져도 내부 CPU 연산(작업)을 계속 돌릴 것인가 를 명확히 구분하는 것입니다. 이걸 혼동하면 안 써도 되는 무거운 권한을 쓰거나 배터리 이슈가 발생합니다. 저의 경우 아래 표를 기준으로 상황에 맞게 기술을 선택해 적용하고 있습니다. 구분 목적 대표 방식 적합한 상황 주의할 점 화면 유지 현재 화면을 계속 보이게 함 FLAG_KEEP_SCREEN_ON 타이머, 영상, 지도 화면 화면을 벗어나면 해제 필수 CPU 작업 유지 화면이 꺼져도 작업 계속 실행 WakeLock , Foreground Service 녹음, 위치 추적, 긴 다운로드 배터리 소모 및 구글 정책 검토 예약/재시도 작업 조건 충족 시 백그라운드 실행 WorkManager 서버 데이터 동기화, 업로드 즉시 실행 보장 안 됨 상태 복구 앱 재진입 시 시간 재계산 저장 시각 + 현재 시각 비교 시험 타이머, 카운트다운 화면 유지와 별개로 설계 필요 단순히 타이머 숫자를 화면에 계속 보여줘야 하는 수준이라면 복잡하게 생각할 것 없이 FLAG_KEEP_SCREEN_ON 하나면...
자세한 내용 보기

안드로이드 백그라운드 타이머 구현 및 Foreground Service 알림 설계 정리

타이머 앱을 만들고 운영하다 보면 백그라운드 처리 때문에 골치 아픈 일이 많습니다. 화면이 켜져 있을 때는 잘 돌다가도, 사용자가 홈 버튼을 누르고 다른 앱을 보거나 화면을 꺼버리면 타이머가 멈추거나 종료 알림이 안 오는 현상이 발생하곤 합니다. 처음에는 무조건 Foreground Service로 다 돌리면 해결될 줄 알았는데, 실제 서비스를 운영해 보니 배터리 소모나 구글 플레이 정책 측면에서 고려할 게 한두 가지가 아니었습니다. 자꾸 까먹어서 나중에도 바로 보고 적용할 수 있도록 실무 기준으로 정리해 둡니다. 백그라운드 타이머 운영 시 자주 겪는 문제 보통 처음 구현할 때 아래와 같은 지점에서 막히거나 실수를 많이 합니다. 화면이 꺼지면 타이머가 같이 멈춰버리는 현상 앱을 백그라운드로 보낸 뒤 타이머 종료 알림이 먹통이 되는 상황 모든 카운트다운을 무조건 Foreground Service로 처리해서 배터리를 낭비하는 구조 상단 알림창에 일시정지, 재개, 종료 같은 제어 버튼이 없는 불편함 알림 채널 중요도를 너무 높여서 사용자에게 과도한 피로감을 주는 경우 PendingIntent 나 로그에 사용자 ID나 민감한 데이터를 그대로 남기는 보안 실수 백그라운드 타이머를 작업할 때는 "코드를 백그라운드에서 계속 실행한다"가 아니라, "사용자가 인지할 수 있는 지속된 작업과 종료 알림을 조합한다"로 접근하는 것이 운영상 훨씬 안전합니다. 핵심 개념: 계산은 상태로, 표시는 알림으로 분리 타이머의 남은 시간은 매초 줄어드는 루프 코드가 아니라, 시작 기준 시각과 현재 시각의 차이 로 계산하는 것이 정석입니다. Foreground Service는 시간을 계산하는 주체가 아니라, 백그라운드에서도 사용자에게 "타이머가 돌고 있다"는 것을 보여주고 제어할 수 있게 돕는 창구일 뿐입니다. 저의 경우 아래와 같이 역할을 나누어 구조를 잡았습니다. 구성 요소 역할 주의할 점 TimerSession 시작 시각, 전체 시간, 일...
자세한 내용 보기

관광 앱 다국어 데이터 모델 및 검색 색인 설계 (자꾸 까먹어서 정리)

관광 앱을 개발하거나 서비스를 운영하다 보면 외국인 여행자를 위해 다국어를 지원해야 하는 일이 꼭 생깁니다. 처음에는 단순히 앱 내 UI 문자열( strings.xml )만 번역하면 끝날 줄 알았는데, 실제 서비스를 돌려보니 장소명이나 지역명 같은 콘텐츠 데이터 처리 가 진짜 번역의 핵심이더군요. 특히 공공데이터를 가져와서 쓰다 보면 한국어만 달랑 있거나, 영문 표기 방식이 데이터 소스마다 제각각이라 데이터가 다 깨집니다. 저의 경우도 "제주시", "Jeju-si", "Jeju City"가 마구 뒤섞여서 검색도 안 되고 화면도 깨지는 삽질을 좀 했습니다. 나중에 또 같은 문제로 고생하지 않으려고 표시 이름, 내부 지역 코드 표준화, Fallback 처리, 그리고 검색 색인 구조까지 실무에서 바로 쓸 수 있게 정리해 둡니다. 1. 기본 개념: 표시 이름과 원본 이름 분리하기 공공데이터에서 가져온 원본 이름을 그대로 덮어써 버리면, 나중에 번역 데이터가 바뀌거나 원본 데이터가 업데이트될 때 매칭할 기준이 사라집니다. 원본 이름은 그대로 보존하고, UI 표시용과 로마자 표기를 별도로 분리해서 관리 해야 유지보수가 쉬워집니다. 항목 예시 용도 원본 이름 성산일출봉 공공데이터 원본 데이터 보존 (비교용) 한국어 표시명 성산일출봉 한국어 UI 표시 영어 표시명 Seongsan Ilchulbong 영어 UI 표시 로마자 표기 Seongsan Ilchulbong 외국어 검색 보조용 검색 키워드 sunrise peak, seongsan 검색 색인 확장용 출처명 공공데이터 제공 기관명 저작권 및 출처 표시 요구사항 대응 2. 데이터 모델 설계 예시 (Kotlin) 저의 경우, 이 문제를 해결하기 위해 아래처럼 장소 기본 정보와 번역 맵( Map<AppLanguage, String> )을 분리한 데이터 모델을 사용합니다. 외부 노출을 막기 위해 실제 API URL이나 내부 코드는 더미 값으로 대체한 구조입니다. Ko...
자세한 내용 보기