Android WebView 커스텀 스킴 파라미터 검증 및 라우팅 구현 방법

이래저래 하이브리드 앱을 개발하고 운영하다 보면, 웹 화면에서 안드로이드 네이티브 기능을 꼭 호출해야 하는 상황이 생깁니다. 공유하기를 띄우거나, 외부 브라우저를 열거나, 기기 지도를 호출하는 기능들이 대표적이죠.

저의 경우 결과값을 웹으로 다시 리턴해 줄 필요가 없는 단순 단방향 호출에는 커스텀 스킴(myapp://action?key=value)을 자주 사용합니다. 구조가 단순해서 웹 쪽에서 호출하기 편하거든요.

하지만 이게 웹 개발자랑 앱 개발자 사이에 규칙을 제대로 안 잡아두면 나중에 코드가 지저분해지고 보안 구멍이 생기기 딱 좋습니다. 웹에서 주는 값을 검증 없이 그대로 Intent에 쑤셔 넣었다가 앱이 픽 터지거나 민감한 정보가 노출되는 경우가 많기 때문입니다. 실무에서 안전하게 쓸 수 있는 라우팅 구조와 파라미터 검증 코드를 정리해 둡니다.

1. 연동 방식 선택 기준 (내가 커스텀 스킴을 쓰는 이유)

웹과 앱을 연결하는 방법은 몇 가지가 있지만, 각자 장단점이 명확합니다. 상황에 맞게 골라 써야 나중에 고생을 안 합니다.

방식설명장점주의할 점 / 추천 상황
커스텀 스킴특정 URL 형식을 앱이 가로채서 분기구조가 단순함결과 리턴이 필요 없는 단순 단방향 호출
JavaScript InterfaceJS에서 Android 메서드를 직접 호출양방향 연동 가능노출 메서드가 많아지면 보안 검토 필수
postMessage메시지 기반으로 웹/앱 통신구조화하기 좋음OS 버전별 동작 확인 필요
서버 API웹/앱이 서버를 통해 상태를 공유결합도가 낮음실시간 네이티브 제어에는 부적합

저의 경우, "공유창 열기", "외부 브라우저 토스"처럼 호출만 하고 끝나는 기능에는 무조건 커스텀 스킴으로 구조를 단순하게 가져갑니다.

2. 핵심 구현 코드 (Java)

자꾸 까먹어서 나중에 바로 복사해 쓰려고 남겨두는 베이스 코드입니다. 실무 프로젝트에 적용할 때는 서비스 규칙에 맞게 스킴명(myapp)이나 호스트(native), 액션 목록만 수정해서 사용하시면 됩니다. 최신 안드로이드 컴포넌트 기준에 맞춰 OnBackPressedDispatcher 구조를 함께 적용해 뒀습니다.

Java
public class MainActivity extends AppCompatActivity {
    private static final String APP_SCHEME = "myapp";
    private static final String NATIVE_HOST = "native";

    private WebView webView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        webView = findViewById(R.id.webView);
        webView.getSettings().setJavaScriptEnabled(true);
        webView.getSettings().setDomStorageEnabled(true);

        // 웹뷰 클라이언트에서 스킴 가로채기
        webView.setWebViewClient(new WebViewClient() {
            @Override
            public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
                Uri uri = request.getUrl();
                if (isNativeScheme(uri)) {
                    handleNativeAction(uri);
                    return true; // 앱에서 직접 처리했으므로 웹뷰 로딩 중단
                }
                return false; // 일반 웹 페이지는 그대로 진행
            }
        });
    }

    // 우리 앱 전용 커스텀 스킴 규칙인지 확인
    private boolean isNativeScheme(Uri uri) {
        return APP_SCHEME.equals(uri.getScheme())
                && NATIVE_HOST.equals(uri.getHost());
    }

    // 요청받은 액션 분기 처리
    private void handleNativeAction(Uri uri) {
        String action = uri.getPath() == null ? "" : uri.getPath().replace("/", "");

        switch (action) {
            case "share":
                share(uri.getQueryParameter("title"), uri.getQueryParameter("url"));
                break;
            case "open-browser":
                openBrowser(uri.getQueryParameter("url"));
                break;
            case "bookmark":
                saveBookmark(uri.getQueryParameter("contentId"));
                break;
            default:
                Toast.makeText(this, "지원하지 않는 기능입니다.", Toast.LENGTH_SHORT).show();
                break;
        }
    }

    // 1. 공유하기 기능 처리
    private void share(String title, String url) {
        if (isBlank(title) || !isHttpsUrl(url)) return; // 파라미터 검증 필수

        Intent intent = new Intent(Intent.ACTION_SEND);
        intent.setType("text/plain");
        intent.putExtra(Intent.EXTRA_TEXT, title + "\n" + url);
        startActivity(Intent.createChooser(intent, "공유하기"));
    }

    // 2. 외부 브라우저 호출
    private void openBrowser(String url) {
        if (!isHttpsUrl(url)) return; // 허용되지 않은 스킴이나 주소 차단
        startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(url)));
    }

    // 3. 로컬 즐겨찾기 저장 처리
    private void saveBookmark(String contentId) {
        // 정규식을 이용해 비정상적인 파라미터(SQL 인젝션 등) 방어
        if (isBlank(contentId) || !contentId.matches("^[0-9A-Za-z_-]{1,40}$")) return;
        
        // 여기에 로컬 DB 저장 로직이나 서버 API 연동 진행
        Toast.makeText(this, "즐겨찾기에 추가했습니다.", Toast.LENGTH_SHORT).show();
    }

    // HTTPS URL 패턴 기본 검증
    private boolean isHttpsUrl(String value) {
        if (isBlank(value)) return false;
        Uri uri = Uri.parse(value);
        return "https".equals(uri.getScheme());
    }

    private boolean isBlank(String value) {
        return value == null || value.trim().isEmpty();
    }
}

3. 기능별 파라미터 검증 기준

웹에서 넘겨주는 파라미터 값은 절대로 그대로 믿으면 안 됩니다. 변조되어 들어올 수 있다는 가정하에 앱 내부에서 필터링을 꼼꼼하게 거쳐야 합니다.

기능명웹에서 전달할 파라미터앱에서 필수로 검증할 사항주의사항
sharetitle, url빈 값 여부 체크, 공유 URL이 HTTPS인지 확인토큰이나 개인정보가 노출된 URL 차단
bookmarkcontentId문자열 길이 제한, 허용 문자 패턴(정규식) 검증내부 사용자 식별자를 가급적 직접 받지 말 것
open-browserurlHTTPS 스킴 확인, 서비스 내부 허용 도메인 체크세션 파라미터나 변조된 URL 토스 방지
maplat, lng위경도 값이 올바른 숫자 범위 형태인지 확인기기 내 지도 앱 설치 여부 사전 체크
login없음 (action만 호출)파라미터 없이 호출 후 앱 네이티브 로그인창 띄움절대로 Access Token을 URL에 실어 보내지 말 것

4. 운영하면서 직접 겪기 쉬운 실수 (주의할 점)

shouldOverrideUrlLoading 리턴 값을 헷갈리지 마세요.

앱 내부에서 커스텀 스킴을 가로채서 처리했다면 반드시 return true;를 줘서 웹뷰가 다음 동작을 진행하지 못하게 막아야 합니다. 반대로 일반 도메인 이동처럼 웹뷰가 계속 페이지를 로딩해야 하는 상황에는 return false;를 던져줘야 흐름이 끊기지 않습니다.

검증 없는 Intent.ACTION_VIEW 실행은 금물입니다.

웹에서 넘겨준 URL 주소를 그대로 Intent로 실행해 버리면 피싱 사이트로 유도되거나 알 수 없는 외부 스킴이 동작하여 보안 사고로 이어집니다. 최소한 안전한 서비스 도메인이거나 https 스킴을 만족하는지 필터링하는 로직을 넣어두셔야 합니다.

인증 토큰(Token)이나 중요 개인정보는 스킴 파라미터에 담지 마세요.

간혹 로그인 완료 후 토큰값을 URL 뒤에 쿼리 스트링으로 실어서 네이티브로 넘기려는 경우가 있습니다. URL은 안드로이드 Logcat이나 크래시 리포트, 기기 히스토리에 텍스트 그대로 남을 위험이 큽니다. 인증 정보나 중요 정보는 웹뷰 암호화 스토리지나 보안 브리지 흐름을 타고 넘어가야 안전합니다.

5. 실무 운영 체크리스트

  • [ ] 스킴 이름(myapp)과 호스트(native)를 화이트리스트로 고정하고 예외는 전부 무시하는가?

  • [ ] 처리 불가능하거나 정의되지 않은 액션이 들어왔을 때 앱이 크래시되지 않고 예외 처리(Toast 등)를 해주는가?

  • [ ] 외부로 토스하는 URL 파라미터에 민감한 세션값이나 개인정보가 포함되어 있지는 않은가?

  • [ ] 정규식을 활용해 ID나 숫자 파라미터의 포맷을 명확히 필터링하고 있는가?

  • [ ] 디버그 로그(Log.d)에 전체 스킴 URL을 가공 없이 그대로 노출시키지 않는가?

커스텀 스킴은 웹에서 앱 기능을 맘대로 주무르는 통로가 아니라, '미리 약속된 안전한 요청만 앱이 검증해서 실행해 주는 제한된 창구'라고 생각하고 접근해야 뒤탈이 없습니다. 기능이 하나씩 늘어날 때마다 웹 연동 문서와 안드로이드 스위치 문을 함께 업데이트하면서 동기화를 맞춰 운영하시기 바랍니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

안드로이드 화면 꺼짐 방지 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...
자세한 내용 보기