웹뷰 브릿지 개선기: 버전 분기 지옥에서 벗어나기

들어가며

안녕하세요, 노머스 Android 개발자 양수진입니다. 웹뷰 환경에서는 웹과 네이티브 앱이 서로 통신하기 위한 브릿지(Bridge) 인터페이스가 필수적인데요, 기존 브릿지 체계를 운영하면서 여러 불편함과 구조적 한계를 느끼게 되었습니다.

이 글에서는 기존 브릿지 구조에서 어떤 문제가 있었는지 분석하고, 단일 브릿지 함수 + type 기반 분기 처리 방식으로 재설계한 과정을 공유하려 합니다.

1. 기존 구조의 문제점

개선 작업에 앞서, 기존 브릿지 체계에서 겪고 있던 문제점들을 정리했습니다.

1-1. 버전 분기 로직의 이중 산재

가장 크게 체감했던 문제는 버전 분기 로직이 여기저기 흩어져 있다는 것이었습니다. 웹에서 네이티브 커맨드를 호출할 때, checkAppVersion으로 앱 버전을 확인하는 로직이 호출부와 runCommand.ts 내부 두 곳에서 중복으로 존재했습니다.

if (checkAppVersion(VersionDict.MultiImage)) {
    return runCommand({ key: 'openEditPostFanFeed', postId, channelId, ... });
}
showVersionUpdateAlert(() => {
    if (checkAppVersion('1.29.0')) {
        runCommand({ key: 'openEditPostFanFeed', postId, channelId, ... });
        return;
    }
    // 1.29.0 미만: 웹 에디터 다이얼로그로 폴백
    showDialog(<FeedPostEditPage post={post} />);
});

// runCommand.ts 내부 — 같은 커맨드에 대해 버전별로 다른 파라미터를 전송
ios({ postId, channelId, boardId, hasMembership }) {
    if (checkAppVersion(VersionDict.MultiImage)) {      // 1.37.0+
        return postMessage({ data: JSON.stringify({ postId, channelId, boardId, hasMembership }) });
    }
    if (checkAppVersion(VersionDict.Board)) {            // 1.31.0+
        return postMessage({ data: JSON.stringify({ postId, channelId, boardId }) });
    }
    postMessage({ data: JSON.stringify({ postId, channelId }) });   // 그 이하
}

이런 식의 버전 분기가 여러 파일에 걸쳐 산재해 있었고, 하드코딩된 버전 문자열도 곳곳에 흩어져 있었습니다.

1-2. 근본 원인 — 에러 핸들링의 부재

그런데 왜 이렇게 버전 분기가 곳곳에 생겨난 걸까요? 근본 원인은 양 플랫폼 모두 웹에서 미지원 커맨드를 호출했을 때 에러를 반환하는 메커니즘이 없었기 때문입니다. 앱이 “이 커맨드는 모른다”고 알려줄 수 없으니, 웹에서 미리 버전을 확인해 방어할 수밖에 없었던 것이죠.

플랫폼별로 실패 양상도 달랐습니다.

Android: 커맨드별 개별 메서드 방식

Android는 커맨드마다 별도의 @JavascriptInterface 메서드로 정의하는 구조입니다.

internal class InAppBrowserJsInterface(...) : FrommAppJsInterface {
    @JavascriptInterface
    override fun openBrowser(url: String) {
        viewModel.action(InAppBrowserAction.OpenBrowser(url))
    }

    @JavascriptInterface
    override fun openEditPostFanFeed(data: String) {
        val jsonString = JSONObject(data)
        // ... 파싱 후 처리
    }

    // 각 커맨드마다 개별 메서드
    // 'newFeature' 같은 새 커맨드 메서드는 존재하지 않음
}

웹에서 미지원 커맨드를 호출하면, 해당 메서드가 네이티브에 존재하지 않으므로 웹뷰의 JavaScript에서 TypeError가 발생합니다. 네이티브 쪽에는 호출 자체가 도달하지 않아 아무 일도 일어나지 않고, 웹에서도 이를 catch하고 있지 않아 미지원인지 코드 버그인지 구분할 수 없었습니다.

이 문제를 인식하고 있었기에, 사용하지 않는 커맨드에 빈 메서드를 유지하는 방어 패턴도 존재했습니다.

@JavascriptInterface
override fun refreshHome() {
    //do nothing, 웹에서 아직 refreshHome 호출을 제거하지 않아 웹쪽 오류 발생하지 않도록
}

웹에서 호출하는 메서드가 없으면 JavaScript 에러가 발생하므로, 앱에서 빈 메서드를 유지해야 했습니다. 이는 앱/웹 간 배포 순서에 암묵적인 의존을 만드는 결과를 낳았습니다. 또한 웹에서 사용하지 않는 커맨드일지라도, 그것이 삭제된 것이 모바일 개발자가 인지하기는 어려워 방치된 부분도 있었습니다.

iOS: 단일 진입점 + switch → default: break

iOS는 WKScriptMessageHandlerWithReply 프로토콜을 사용하고 있었습니다. 웹에서 postMessage를 호출하면 JavaScript Promise가 반환되고, iOS가 replyHandler를 호출하면 그 Promise가 resolve/reject되는 구조입니다.

switch command {
case "isNotificationEnable":
    checkNotificationPermission { isEnabled in
        replyHandler(isEnabled, nil) // Promise resolve
    }
case "openBrowser":
    UIApplication.shared.open(url)
    // replyHandler 호출 안 함 → Promise pending
default:
    break
    // 미지원 커맨드도 replyHandler 호출 안 함 → Promise pending
}

값을 반환하는 일부 커맨드만 replyHandler를 호출하고 있었고, 나머지 커맨드와 미지원 커맨드는 replyHandler를 호출하지 않아 Promise가 영원히 pending 상태에 빠졌습니다. 현재는 대부분의 커맨드에서 await하지 않아 당장 문제가 되진 않았지만, 웹에서 미지원 여부를 알 방법이 전혀 없는 상태였습니다.

결국, 앱이 미지원 type에 대해 에러를 반환할 수 있다면 웹의 버전 분기 로직을 제거하고 일관된 업데이트 팝업 처리가 가능해집니다. 그래서 이 에러 핸들링 부재를 가장 먼저 해결하기로 했습니다.

2. 단일 브릿지 함수로의 전환

기존에는 커맨드마다 개별 함수/메서드로 분리되어 있던 구조를, 하나의 진입점(sendBridge)에서 type 필드 값에 따라 적절한 커맨드를 실행하는 방식으로 전환했습니다.

데이터 형식 정의

먼저 웹과 네이티브가 주고받을 JSON 형식을 정의했습니다.

요청 (Web → Native)

{
  "type": "openBrowser",
  "payload": {
    "url": "https://example.com"
  }
}

• type (필수): 실행할 커맨드 이름
• payload (선택): 커맨드에 필요한 파라미터 객체

응답 (Native → Web)

성공 시:

{
  "success": true,
  "data": { "enabled": true } // optional
}

실패 시:

{
  "success": false,
  "error": { "code": "UNKNOWN_TYPE" }
}

success 필드로 성공/실패를 명확하게 구분하고, 실패 시에는 에러 코드를 함께 반환합니다. 에러 코드는 세 가지로 구분됩니다.

코드	의미
UNKNOWN_TYPE	앱이 해당 type 자체를 모르는 경우
UNSUPPORTED_TYPE	앱은 알지만 현재 화면에서 처리하지 못하는 type인 경우
INVALID_PARAMS	JSON 파싱 실패 또는 필수 파라미터 누락

웹 측 구현

이 데이터 형식을 바탕으로, 웹에서는 sendBridge라는 단일 함수를 통해 모든 네이티브 호출을 수행합니다.

interface BridgeCommandMap {
    openBrowser: (params: { url: string }) => void;
    ...
}


async function sendBridge<T extends keyof BridgeCommandMap>(
    type: T,
    ...args: Parameters<BridgeCommandMap[T]> extends []
        ? []
        : [payload: Parameters<BridgeCommandMap[T]>[0]]
): Promise<BridgeCommandReturnType<T>>

BridgeCommandMap 인터페이스에 모든 커맨드의 파라미터와 반환 타입을 정의하였고, sendBridge 메서드를 호출 할 때에는 type safe하게 커맨드를 호출할 수 있도록 강제했습니다.

// 파라미터 없는 커맨드
await sendBridge('pageLoadFinished');

// 파라미터 있는 커맨드
await sendBridge('openBrowser', { url: 'https://example.com' });

// 반환값 있는 커맨드
const isEnabled = await sendBridge('isNotificationEnable');

플랫폼별로 네이티브와의 통신 방식이 다르지만, sendBridge가 이를 내부적으로 추상화합니다.

sendBridge 호출
    │
    ├─ window.webkit?.messageHandlers?.Fromm → iOS
    │       postMessage({ command: 'sendBridge', data: JSON.stringify({ type, payload }) })
    │
    ├─ window.Fromm → Android
    │       window.Fromm.sendBridge(JSON.stringify({ type, payload }))
    │
    └─ 둘 다 없음 → 개발/브라우저 환경
            console.log 출력 후 undefined 반환

응답이 실패인 경우 BridgeError를 throw하므로, 호출부에서 에러를 핸들링할 수 있습니다. 구버전 앱에서 업데이트 팝업 노출이 필요한 경우, 웹에서는 버전 체크 할 필요 없이UNKNOWN_TYPE으로 error code가 반환되는 것을 보고 노출하기만 하면 됩니다.

try {
    await sendBridge('download', { url: '...', type: 'image' });
} catch (e) {
    if (e instanceof BridgeError && e.code === 'UNKNOWN_TYPE') {
        showUpdatePopup(); // 구버전 앱 업데이트 팝업 노출
    }
}

3. Android 구현

Android에서는 sendBridge라는 단일 @JavascriptInterface 메서드만 노출하고, 내부적으로 아래 그림의 흐름으로 처리합니다.

웹뷰 (JSON)
  │
  ▼
BridgeCommandParser
  │  JSON을 타입 안전한 커맨드 객체로 변환
  │
  ├─ 파싱 실패 → BridgeResponse.Error (INVALID_PARAMS / UNKNOWN_TYPE)
  │
  ▼
BridgeCommand (sealed interface)
  │  앱이 인식하는 모든 브릿지 명령의 공통 타입
  │
  ├─ BridgeHandler1 ── 모든 커맨드 처리
  ├─ BridgeHandler2 ── 일부 커맨드만 처리, 나머지는 UNSUPPORTED_TYPE
  │
  ▼
BridgeResponse
  │  처리 결과를 toJson()으로 직렬화하여 웹에 반환
  ▼
웹뷰

BridgeCommand — 커맨드 정의

웹에서 네이티브로 요청할 수 있는 모든 명령을 sealed interface로 정의합니다. Parser는 JSON을 이 타입으로 변환하고, Handler는 이 타입을 받아 처리합니다.

sealed interface BridgeCommand {
    
    data class OpenBrowser(val url: String) : BridgeCommand
    data class OpenInAppBrowser(val url: String) : BridgeCommand
    ...
}

BridgeCommandParser — Json 파싱

웹에서 보낸 JSON 문자열을 BridgeCommand로 변환합니다. 파서는 JSON이 유효한 커맨드인지만 판단하고, 해당 웹뷰가 그 커맨드를 지원하는지는 관여하지 않습니다.

• type을 인식하지 못하면 → UNKNOWN_TYPE
• JSON 형식이 잘못되었거나 필수 필드가 누락되면 → INVALID_PARAMS
• 정상 파싱 → BridgeCommand 객체 생성

BridgeHandler — 웹뷰 단위의 커맨드 동작 정의

파싱된 BridgeCommand를 실제로 실행하는 주체입니다. 여기서 고려한 점은, 네이티브 웹뷰 클래스마다 구현하는 커맨드 범위가 다르다는 점입니다. 피드, 라이브, 미디어 등 모든 기능을 제공하는 웹뷰 클래스가 있는 반면, 설정·공지사항 등 단순 콘텐츠를 표시하는 공용 웹뷰 클래스가 존재합니다. 예를 들어 download는 파서가 정상적으로 파싱하지만, 해당 커맨드를 구현하지 않은 웹뷰 클래스의 핸들러에서는 UNSUPPORTED_TYPE을 반환합니다. 이처럼 동일한 커맨드라도 어느 웹뷰 클래스에서 실행되느냐에 따라 결과가 달라질 수 있어 UNSUPPORTED_TYPE 타입이 생겨난 것입니다.

internal class WebviewBridgeHandler(
    ...
) {
    fun handle(command: BridgeCommand): BridgeResponse = when (command) {

        is BridgeCommand.OpenBrowser -> {
            // 브라우저 열기 동작
            BridgeResponse.Success()
        }

        is BridgeCommand.OpenInAppBrowser -> {
            // 인앱 브라우저 열기 동작
            BridgeResponse.Success()
        }
        
        // BridgeCommand.Download 등 미지원 type의 경우
        else -> BridgeResponse.Error(BridgeErrorCode.UNSUPPORTED_TYPE)
}

BridgeResponse

모든 핸들러는 처리 결과를 BridgeResponse로 반환하며, toJson()을 통해 JSON 문자열로 직렬화하여 웹뷰에 전달합니다.

sealed class BridgeResponse {

    abstract fun toJson(): String

    data class Success(val data: Any? = null) : BridgeResponse() {
        override fun toJson(): String = JSONObject().apply {
            put("success", true)
            if (data != null) {
                when (data) {
                    is JSONObject -> put("data", data)
                    is JSONArray -> put("data", data)
                    is List<*> -> put("data", JSONArray(data))
                    is Map<*, *> -> put("data", JSONObject(data))
                    else -> put("data", data)
                }
            }
        }.toString()
    }

    data class Error(val code: BridgeErrorCode) : BridgeResponse() {
        override fun toJson(): String = JSONObject().apply {
            put("success", false)
            put(
                "error",
                JSONObject().apply {
                    put("code", code.value)
                },
            )
        }.toString()
    }
}

4. 개선 효과 정리

버전 분기 로직 제거

앱이 미지원 type에 대해 에러를 반환할 수 있게 되면서, 웹에 산재하던 checkAppVersion 분기 로직을 제거할 수 있었습니다. 매 업데이트 마다 버전을 체크할 필요 없이 미지원 시 일관된 업데이트 팝업 처리가 가능해졌습니다.

디버깅 용이성 향상

기존에는 미지원 커맨드 호출 시 아무런 응답 없이 실패했기 때문에, 문제가 발생해도 원인을 파악하기 어려웠습니다. 이제는 앱이 UNKNOWN_TYPE, UNSUPPORTED_TYPE, INVALID_PARAMS 등 구체적인 에러 코드를 반환하므로, 웹에서 어떤 이유로 실패했는지 바로 확인할 수 있어 디버깅이 훨씬 수월해졌습니다.

커맨드 변경에 유연한 구조

기존에는 커맨드에 파라미터가 추가되거나 삭제될 때, 웹에서 버전별로 다른 파라미터를 보내는 분기가 필요했습니다. 예를 들어 특정 커맨드에 새 파라미터가 추가되면, 해당 파라미터를 모르는 구버전 앱을 위해 버전별로 보내는 JSON을 달리해야 했습니다.

이제는 웹에서 항상 최신 파라미터를 포함한 JSON을 보내면 됩니다. 앱의 파서가 필수/선택 필드를 구분하여 처리하므로, 구버전 앱은 모르는 필드를 무시하고 신버전 앱은 새 필드를 활용합니다. 새 커맨드를 추가하는 경우에도 구버전 앱은 UNKNOWN_TYPE을 반환하므로, 웹에서 구버전 앱에 대한 버전 체크가 필요 없어졌습니다.

마무리하며

이번 작업에서는 Android 구현뿐만 아니라 웹 측 설계와 구현도 함께 맡았습니다. 평소에는 네이티브 관점에서만 브릿지를 바라봤는데, 웹의 입장이 되어보니 기존 구조의 불편함이 더 실감났습니다. 버전 분기를 왜 이렇게 많이 넣을 수밖에 없었는지, 에러 응답이 없다는 게 호출하는 쪽에서 얼마나 답답한 일인지 직접 겪어보니 확 와닿았습니다.

양쪽을 모두 고려한 덕분에 “앱이 모르는 커맨드에 대해 명확하게 에러를 반환한다”는 원칙을 자연스럽게 세울 수 있었고, 그 원칙 하나로 버전 분기 제거, 배포 순서 의존성 해소까지 이어질 수 있었습니다. 요청/응답 형식이 통일되고 에러 처리도 규격화되면서, 웹-네이티브 간 협업 과정에서의 커뮤니케이션 비용이 줄어드는 것 또한 기대하고 있습니다.