웹뷰 브릿지 완벽 가이드: 네이티브-웹 통신의 모든 것

📤 웹 → 네이티브: "사진 찍기 기능 실행해줘!"
📥 네이티브 → 웹: "사진 찍었어, 이미지 URL 보낼게"

// 웹 코드 (당신이 작성)
const bridge = useBridge({ debug: true }) // 브릿지 초기화 (React hook 예시)

async function showToast() {
  await bridge.showToast('저장되었습니다!')
}

// 사용자가 '닫기' 버튼 클릭
async function closeWebView() {
  await bridge.closeWebView()
  // 네이티브 앱이 웹뷰를 닫고 이전 화면으로 돌아감
}

// 레거시 방식: URL Scheme으로 네이티브 호출
function callNative(action: string, params: object) {
  const query = encodeURIComponent(JSON.stringify(params))
  window.location.href = `myapp://${action}?data=${query}`
}

// 사용 예시
callNative('openCamera', { mode: 'photo' })

// Android에서 URL Scheme 처리
webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
        if (url.startsWith("myapp://")) {
            // URL 파싱 후 해당 기능 실행
            handleBridgeCall(url)
            return true
        }
        return false
    }
}

// Android (Kotlin) - 위험한 코드
webView.webViewClient = object : WebViewClient() {
    override fun onPageFinished(view: WebView, url: String) {
        // ❌ 페이지 로드 완료 직후 바로 JS 실행
        webView.evaluateJavascript("initUserData($userData)", null)
    }
}

시간 →
────────────────────────────────────────────────────────────────
네이티브: [웹뷰 로드] ─── [onPageFinished] ─── [JS 실행!] ─── 💥 에러
                                │
웹:       [HTML 파싱] ────────────────── [JS 번들 로드] ─── [브릿지 초기화]
                                              │
                          브릿지가 아직 없음!

// ❌ 위험한 코드: 앱이 준비됐는지 확인하지 않음
useEffect(() => {
  // 컴포넌트 마운트 직후 바로 브릿지 호출
  bridge.getUserInfo().then(setUser)
}, [])

시간 →
─────────────────────────────────────────────────────────
웹:      [로드 시작] ─── [DOM Ready] ─── [브릿지 호출!] ─── [응답 없음...😢]
                              │
네이티브: [로드 시작] ────────────────── [브릿지 준비 완료] ─── (호출 놓침)
                                              │
                              웹이 너무 빨리 호출함!

// ⚠️ 나쁜 예: 임의의 시간 대기
useEffect(() => {
  setTimeout(() => {
    bridge.getUserInfo().then(setUser)
  }, 500) // "500ms면 충분하겠지..."
}, [])

1단계: 웹이 "나 준비됐어!" 신호 전송
     ↓
2단계: 네이티브가 메시지 수신
     ↓
3단계: 네이티브가 디바이스 정보와 함께 "나도 준비됐어!" 응답
     ↓
4단계: 웹이 응답 받고 통신 준비 완료 ✅

// React에서 사용하는 경우 (가상의 useBridge hook)
function App() {
  const bridge = useBridge({ debug: true })

  if (!bridge.isReady) {
    return <div>네이티브 앱과 연결 중...</div>
  }

  // ✅ 이제 안전하게 브릿지 사용 가능!
  return (
    <div>
      <h1>웹뷰 앱</h1>
      <button onClick={() => bridge.showToast('Hello!')}>
        토스트 표시
      </button>
    </div>
  )
}

{
  "id": "msg_1703123456789_abc123",
  "type": "action",
  "payload": {
    "action": "showToast",
    "params": {
      "message": "안녕하세요!"
    }
  },
  "timestamp": 1703123456789
}

// ✅ 좋은 예: async/await로 응답 대기
async function openCamera() {
  try {
    const result = await bridge.requestAction({
      action: 'camera',
      params: { mode: 'photo' },
    })

    console.log('사진 URL:', result.imageUrl)
  } catch (error) {
    console.error('카메라 실패:', error)
  }
}

// ❌ 나쁜 예: 응답을 기다리지 않음
function openCamera() {
  bridge.requestAction({ action: 'camera' })
  // 응답이 오기 전에 다음 코드 실행됨 (위험!)
}

useEffect(() => {
  // 위치 변경 이벤트 리스너 등록
  const handler = (payload) => {
    console.log('새 위치:', payload.latitude, payload.longitude)
  }

  bridge.on('locationChanged', handler)

  // ✅ 컴포넌트 언마운트 시 리스너 제거 (메모리 누수 방지!)
  return () => {
    bridge.off('locationChanged', handler)
  }
}, [])

function Header() {
  const bridge = useBridge() // 브릿지 초기화

  return (
    <header>
      {bridge.isInWebView ? (
        // 웹뷰 환경: 네이티브 닫기 버튼
        <button onClick={() => bridge.closeWebView()}>
          ← 뒤로 가기
        </button>
      ) : (
        // 일반 웹: 브라우저 뒤로 가기
        <button onClick={() => window.history.back()}>
          ← 뒤로 가기
        </button>
      )}
    </header>
  )
}

// ✅ 좋은 예
const API_URL = 'https://api.example.com'

// ❌ 나쁜 예
const API_URL = 'http://api.example.com' // 중간자 공격 위험!

// ✅ 좋은 예: 사용자 입력 검증
function shareContent(text: string, url?: string) {
  if (!text || text.length > 500) {
    throw new Error('텍스트는 1~500자여야 합니다')
  }

  if (url && !isValidUrl(url)) {
    throw new Error('유효하지 않은 URL입니다')
  }

  return bridge.share(text, url)
}

// ❌ 나쁜 예: 검증 없이 바로 전송
function shareContent(text: string, url?: string) {
  return bridge.share(text, url) // XSS 공격 가능!
}

// 네이티브 측에서 설정 (앱 개발자와 협의)
const ALLOWED_ORIGINS = ['https://example.com', 'https://www.example.com', 'https://m.example.com']

// ✅ 좋은 예: 필요한 액션만 노출
const allowedActions = ['showToast', 'closeWebView', 'share']

// ❌ 나쁜 예: 모든 기능 노출
// 파일 시스템, 연락처 등 민감한 기능까지 접근 가능 (위험!)

// 개발 환경에서는 항상 debug: true 설정!
const bridge = useBridge({
  debug: process.env.NODE_ENV === 'development',
})

[WebViewBridge] Initialized
[WebViewBridge] Starting handshake...
[WebViewBridge] Sent to native: {"type":"handshake",...}
[WebViewBridge] Received from native: {"type":"handshake",...}
[WebViewBridge] ✅ Handshake completed!
[WebViewBridge] Device info: {"platform":"android",...}

// ✅ 환경 체크 후 분기 처리
if (bridge.isInWebView) {
  await bridge.showToast('웹뷰에서 실행 중')
} else {
  alert('일반 브라우저에서 실행 중')
}

// 예시: API 명세서
interface BridgeActions {
  // 토스트 메시지 표시
  showToast: (message: string) => Promise<void>

  // 웹뷰 닫기
  closeWebView: () => Promise<void>

  // 카메라 열기
  openCamera: (options: CameraOptions) => Promise<{ imageUrl: string }>

  // 공유하기
  share: (text: string, url?: string) => Promise<void>
}

// 에러 코드 체계 합의
enum BridgeErrorCode {
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  NETWORK_ERROR = 'NETWORK_ERROR',
  INVALID_PARAMS = 'INVALID_PARAMS',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
}

// 예시: 브릿지 hook을 사용하는 React 컴포넌트
import { useState, useEffect } from 'react'

// 주의: useBridge는 가상의 hook입니다. 실제 구현은 앱 개발자와 협의하여 정의하세요.
function GalleryApp() {
  const bridge = useBridge({ debug: true })
  const [photos, setPhotos] = useState<string[]>([])

  // 1. Handshake 대기
  if (!bridge.isReady) {
    return <div>앱과 연결 중...</div>
  }

  // 2. 카메라로 사진 촬영
  const takePhoto = async () => {
    try {
      const result = await bridge.requestAction({
        action: 'camera',
        params: { mode: 'photo' }
      })

      setPhotos([...photos, result.imageUrl])
      await bridge.showToast('사진이 추가되었습니다')
    } catch (error) {
      console.error('카메라 에러:', error)
      await bridge.showToast('카메라 실행 실패')
    }
  }

  // 3. 사진 공유
  const sharePhoto = async (url: string) => {
    try {
      await bridge.share('내 사진을 공유합니다', url)
    } catch (error) {
      console.error('공유 에러:', error)
    }
  }

  return (
    <div>
      <h1>내 갤러리</h1>

      {/* 디바이스 정보 표시 */}
      {bridge.deviceInfo && (
        <p>
          플랫폼: {bridge.deviceInfo.platform}
          ({bridge.deviceInfo.osVersion})
        </p>
      )}

      {/* 사진 촬영 버튼 */}
      <button onClick={takePhoto}>📷 사진 찍기</button>

      {/* 사진 목록 */}
      <div>
        {photos.map((url, index) => (
          <div key={index}>
            <img src={url} alt={`사진 ${index + 1}`} />
            <button onClick={() => sharePhoto(url)}>공유</button>
          </div>
        ))}
      </div>
    </div>
  )
}