메인 콘텐츠로 건너뛰기
이 문서는 고객사 모바일 앱에 LiveForm을 WebView로 연동하는 방법을 설명합니다. 대상 독자: 기존 iOS 또는 Android 앱에 LiveForm을 연동하는 고객사 모바일 엔지니어.

구현 목표

고객사 앱은 다음 흐름을 구현합니다.
  1. 고객사 서버 또는 앱에서 전달받은 pid로 LiveForm URL을 생성합니다.
  2. WebView를 열기 전에 LiveForm에 필요한 앱 권한을 확인합니다.
  3. LiveForm URL을 전체 화면 WebView로 엽니다.
  4. 카메라 촬영, 이미지 업로드, 쿠키, 외부 링크 이동이 동작하도록 WebView를 설정합니다.

지원 및 최소 사양

LiveForm은 HTTPS 기반 Web Application이므로 앱의 WebView가 최신 브라우저 기능, 카메라 권한, 파일 선택, cookie/storage를 정상 지원해야 합니다.
구분최소 사양권장 사양비고
iOSiOS 15 이상iOS 16 이상iOS 15 이상에서는 WKUIDelegate의 media capture permission callback으로 LiveForm host만 허용할 수 있습니다.
AndroidAndroid 9, API 28 이상Android 10, API 29 이상파일 선택과 카메라 capture 동작 안정성을 위해 Android System WebView 또는 Chrome 최신 버전 사용을 권장합니다.
Android WebView업데이트 가능한 Android System WebView 또는 Chrome최신 Android System WebView 또는 Chrome파일 선택, 카메라 capture, cookie/storage 동작이 WebView/Chrome 버전에 영향을 받을 수 있습니다.
React Nativereact-native-webview 13.x 이상최신 안정 버전네이티브 앱은 동일 기능을 WKWebView/Android WebView로 직접 구현하면 됩니다.
실기기 검수에서 확인해야 하는 범위:
  • Android 9(API 28) 이상에서 앱 설치, WebView 로딩, 파일 선택, 카메라 capture, cookie/storage를 포함한 전체 흐름을 확인합니다.
  • iOS 15 이상에서 WKWebView 파일 선택, 카메라 capture, cookie/storage를 포함한 전체 흐름을 확인합니다.
  • 최종 운영 판정은 실제 LiveForm URL에서 촬영, 업로드, 제출, returnUrl/deep link 이동까지 완료되는지 보고 내려야 합니다.

LiveForm URL

고객사 앱은 LiveForm 운영 host만 사용합니다. pid는 query parameter로 전달합니다.
https://form.argosidentity.com?pid={pid}
pid는 URL에 넣기 전에 반드시 URL encode 처리해야 합니다.
고객사 앱에서는 별도의 host나 form type path를 구분하지 않고, 전달받은 pid로만 LiveForm 세션을 구분합니다.

앱 권한

LiveForm은 WebView 내부에서 카메라와 이미지 업로드 기능을 사용합니다. 모바일 앱에서 WebView로 실행하는 경우, 브라우저가 처리하던 카메라와 파일 접근 권한을 고객사 앱이 먼저 확보해야 합니다.
WebView를 열기 전에 앱 레벨에서 카메라와 사진첩 또는 미디어 권한을 요청하고, 허용 상태를 확인하는 것은 필수입니다. 필수 권한이 허용되지 않은 상태에서는 LiveForm의 촬영 또는 이미지 업로드 흐름이 정상 동작하지 않을 수 있으므로 WebView를 열지 않아야 합니다.
Info.plist에 다음 usage description을 추가합니다.
<key>NSCameraUsageDescription</key>
<string>LiveForm 신분증 촬영을 위해 카메라 접근이 필요합니다.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>LiveForm 이미지 업로드를 위해 사진첩 접근이 필요합니다.</string>

필수 연동 흐름

사용자 액션
  └─ 고객사 앱에서 LiveForm 시작
      └─ pid 기반 LiveForm URL 생성

WebView 진입 전
  ├─ 카메라 권한 확인
  ├─ 사진첩/미디어 권한 확인
  └─ 전체 화면 WebView 열기

WebView 내부
  ├─ JavaScript와 DOM storage 허용
  ├─ Cookie 허용
  ├─ inline media와 media capture 허용
  ├─ http/https/data/about URL은 WebView에서 처리
  └─ custom scheme은 외부 앱으로 전달
URL이 유효하지 않거나 필수 권한 확인이 끝나지 않았다면 WebView를 열지 않습니다.

WebView 설정

WebView는 JavaScript, storage, cookie, media playback, media capture를 허용해야 합니다.
React Native 앱에서 react-native-webview를 사용하는 경우, Android WebChromeClient와 iOS WKUIDelegate의 세부 구현은 라이브러리 native layer가 처리합니다. 앱 코드에서는 아래 WebView props를 설정하고, 실제 기기에서 Android/iOS 검수 체크리스트를 각각 확인해야 합니다.
import { Linking } from 'react-native';
import { WebView } from 'react-native-webview';

function openExternalUrl(url: string) {
  Linking.canOpenURL(url)
    .then((supported) => {
      if (supported) return Linking.openURL(url);
      return undefined;
    })
    .catch(() => undefined);
}

export function LiveFormWebView({ url }: { url: string }) {
  return (
    <WebView
      source={{ uri: url }}
      originWhitelist={['*']}
      javaScriptEnabled
      domStorageEnabled
      sharedCookiesEnabled
      thirdPartyCookiesEnabled
      allowsInlineMediaPlayback
      mediaPlaybackRequiresUserAction={false}
      mediaCapturePermissionGrantType="grantIfSameHostElsePrompt"
      allowsFullscreenVideo
      allowFileAccess
      mixedContentMode="compatibility"
      setSupportMultipleWindows={false}
      onOpenWindow={({ nativeEvent }) => {
        if (nativeEvent.targetUrl) openExternalUrl(nativeEvent.targetUrl);
      }}
      onShouldStartLoadWithRequest={({ url: nextUrl }) => {
        if (
          nextUrl === 'about:blank' ||
          nextUrl.startsWith('about:') ||
          nextUrl.startsWith('data:') ||
          nextUrl.startsWith('http://') ||
          nextUrl.startsWith('https://')
        ) {
          return true;
        }

        openExternalUrl(nextUrl);
        return false;
      }}
    />
  );
}
주요 설정 설명
설정이유
javaScriptEnabledLiveForm은 Web Application으로 실행됩니다.
domStorageEnabledLiveForm이 브라우저 storage를 사용할 수 있게 합니다.
sharedCookiesEnabled / thirdPartyCookiesEnabled일반 브라우저와 유사한 cookie 동작을 유지합니다.
allowsInlineMediaPlayback지원되는 환경에서 media UI가 WebView 내부에서 동작하도록 합니다.
mediaCapturePermissionGrantTypeLiveForm host에서 media capture 권한을 처리할 수 있게 합니다.
setSupportMultipleWindows={false}새 창 흐름을 앱이 제어하는 WebView 경로 안에 둡니다.
onShouldStartLoadWithRequest알 수 없는 custom scheme이 WebView를 깨지 않도록 외부 앱으로 전달합니다.

LiveForm URL 생성 유틸리티

const LIVE_FORM_ORIGIN = 'https://form.argosidentity.com';

export function buildLiveFormUrl(pid: string) {
  return `${LIVE_FORM_ORIGIN}?pid=${encodeURIComponent(pid.trim())}`;
}

권한 처리 예시 (Expo/React Native)

import * as ImagePicker from 'expo-image-picker';

export async function requestLiveFormPermissions() {
  const camera = await ImagePicker.requestCameraPermissionsAsync();
  const mediaLibrary = await ImagePicker.requestMediaLibraryPermissionsAsync();

  return {
    granted: camera.granted && mediaLibrary.granted,
    camera,
    mediaLibrary,
  };
}
권한이 거부되면:
  • WebView를 열지 않습니다.
  • LiveForm 촬영과 업로드에 카메라/사진첩 권한이 필요하다는 메시지를 보여줍니다.
  • 앱 설정 화면으로 이동할 수 있는 버튼을 제공합니다.

전체 화면 레이아웃

LiveForm은 가능한 많은 화면 영역을 사용하는 것이 좋습니다. 권장 사항:
  • WebView route에서는 native header를 숨깁니다.
  • notch와 home indicator를 피하기 위해 safe area를 적용합니다.
  • header를 숨긴 경우 작은 앱 레벨 뒤로가기 버튼을 제공합니다.
  • WebView를 card나 modal 안에 넣지 말고 화면을 직접 채우게 합니다.
┌──────────────────────────┐
│  back                    │
│ ┌──────────────────────┐ │
│ │                      │ │
│ │      LiveForm        │ │
│ │      WebView         │ │
│ │                      │ │
│ └──────────────────────┘ │
└──────────────────────────┘

검수 체크리스트

iOS와 Android에서 각각 확인합니다.
검수 방식고객사 앱은 제공된 예시 구현을 참고해 자체 WebView 화면을 구현한 뒤, 실제 LiveForm URL과 권한/기능 테스트 페이지를 분리해서 검수해야 합니다.
  • LiveForm URL 모드: LiveForm 운영 호스트에서 실제 제출 흐름을 확인합니다.
  • 권한/기능 테스트 페이지: WebView의 storage/cookie, fetch, 파일 입력, 카메라 capture 입력을 LiveForm 상태와 무관하게 한 번의 흐름으로 순차 확인합니다.
권한/기능 테스트 성공은 WebView 메커니즘이 동작한다는 뜻이지, 실제 LiveForm 제출 성공을 의미하지 않습니다. 최종 판정은 LiveForm URL 모드와 권한/기능 테스트 모드를 모두 보고 내려야 합니다.
URL 및 이동
  • https://form.argosidentity.com?pid={pid} 형식의 LiveForm URL이 열린다.
  • pid가 URL encode 처리되어 전달된다.
  • 외부 custom scheme은 외부 앱으로 열리거나 안전하게 실패한다.
권한
  • 첫 실행 시 WebView 진입 전에 카메라 권한을 확인한다.
  • 첫 실행 시 WebView 진입 전에 사진첩/미디어 권한을 확인한다.
  • 권한 거부 시 복구 가능한 메시지를 보여준다.
  • 설정 열기 버튼이 앱 설정 화면으로 이동한다.
WebView 동작
  • JavaScript가 활성화된 상태로 LiveForm이 로드된다.
  • 신분증 촬영 시 카메라 UI가 열린다.
  • 이미지 업로드 시 picker가 열린다.
  • Cookie와 storage가 일반 WebView navigation 동안 유지된다.
  • 페이지 로딩 중 loading state가 표시된다.
  • WebView load error 또는 HTTP error가 발생했을 때 사용자에게 복구 가능한 안내를 보여준다.

문제 해결

확인할 항목:
  • WebView를 열기 전에 앱 카메라 권한을 요청했고 허용되었는지
  • iOS NSCameraUsageDescription이 설정되어 있는지
  • Android android.permission.CAMERA가 설정되어 있는지
  • WebView에서 media capture 관련 설정이 활성화되어 있는지
인앱 브라우저(웹뷰) 환경에서 카메라 차단이 지속되는 경우, Android·웹뷰 카메라 문제 해결을 참고하세요.
확인할 항목:
  • 사진첩 또는 미디어 권한을 요청했고 허용되었는지
  • iOS NSPhotoLibraryUsageDescription이 설정되어 있는지
  • Android media 권한이 target SDK와 picker 구현에 맞게 설정되어 있는지
확인할 항목:
  • URL에 유효한 pid가 포함되어 있는지
  • 기기가 네트워크에 연결되어 있는지
  • JavaScript와 DOM storage가 활성화되어 있는지
  • WebView callback에서 HTTP/network error가 발생했는지