본문으로 건너뛰기
Unveilydocs

Bridge 개요

네이티브 Bridge가 동작하는 방식

Bridge란?

Unveily Bridge는 웹(JavaScript) ↔ 네이티브 간 통신 인터페이스입니다.

웹페이지에서 window.unveilyBridge를 통해 카메라, GPS, 생체인증 등 네이티브 기능을 호출하고, 결과를 콜백으로 받습니다. 기본 기능은 Swift·Kotlin을 직접 작성하지 않고도 쓸 수 있고, 원하면 Kotlin·Swift로 직접 확장할 수도 있습니다.

주입되는 전역 객체는 소문자 window.unveilyBridge 하나뿐입니다. (window.UnveilyBridge 같은 대문자 객체는 존재하지 않습니다.)

기본 구조

대부분의 비동기 메서드는 콜백 함수명을 문자열로 전달받습니다. 네이티브는 여러분이 window에 정의한 그 이름의 전역 함수를 호출하며, 결과는 하나의 JSON 객체 인자로 전달됩니다.

// 웹 → 네이티브: 기능 호출 (콜백 함수명을 문자열로 전달)
window.unveilyBridge.qr.scan("onQRResult");

// 결과는 전역 콜백 함수로 전달됩니다 (단일 JSON 객체 인자)
function onQRResult(result) {
  const { text, format, type } = result;
  console.log("스캔 결과:", text);   // 디코딩된 값
  console.log("포맷:", format);       // 예: "QR_CODE", "EAN_13"
}

네이티브에서 웹으로 이벤트를 보낼 때는 이름이 정해진 전역 콜백 함수를 호출합니다. unveily-event 같은 제네릭 CustomEvent는 존재하지 않습니다. 필요한 이벤트에 대해 아래처럼 전역 함수를 직접 정의하세요.

// 네이티브 → 웹: 네이티브가 이름이 정해진 전역 함수를 호출합니다
window.onFCMReceived = function (title, body, dataJson) {
  // 푸시 알림 수신
};
window.onDeepLinkReceived = function (url) {
  // 딥링크 수신
};
window.onPaymentResult = function (success, message) {
  // 결제 결과 수신
};

준비 완료 시점 — unveilyGlueReady

window.unveilyBridge는 페이지 로드 전에 등록되지만, 일부 네임스페이스(내비게이션 모듈 등)는 글루 스크립트가 주입된 뒤에 생성됩니다. React·Vue 등 SPA에서 마운트 시점에 네임스페이스 메서드를 호출한다면, 먼저 unveilyGlueReady 이벤트를 기다리세요.

window.addEventListener('unveilyGlueReady', () => {
  window.unveilyBridge.bottomTabs.setConfig({ items: [/* ... */] });
}, { once: true });

사용자 동작 호출은 대기 불필요

버튼 클릭 등 사용자 조작으로 브릿지를 호출하는 경우에는 unveilyGlueReady를 기다릴 필요가 없습니다 — 그 시점에는 글루가 항상 준비되어 있습니다.

플랜 / 모듈 확인

현재 라이선스 플랜은 app.getInfo()로 읽습니다. (window.unveilyBridge.plan이나 hasFeature() 같은 API는 존재하지 않습니다.)

// 현재 라이선스 티어 확인
window.unveilyBridge.app.getInfo("onAppInfo");

function onAppInfo(info) {
  console.log(info.tier);      // "basic" | "standard" | "pro"
  console.log(info.platform);  // "android" | "ios"

  if (info.tier !== "basic") {
    showBiometricButton();     // 생체 인증은 Standard 이상
  }
}

내비게이션 모듈(bottomTabs, sideDrawer, topDownMenu, accessibility)의 활성화 여부는 modules.isEnabled()로 동기 확인합니다.

// 모듈 활성화 여부 확인 (동기 boolean)
if (window.unveilyBridge.modules.isEnabled("sideDrawer")) {
  // sideDrawer 사용 가능
}

// 활성화된 모듈 목록 (배열)
const enabled = window.unveilyBridge.modules.getEnabledModules();

전체 기능 목록

Basic 이상

기능문서
QR / 바코드 스캔qr-scan
푸시 알림 (FCM)push-notifications
카메라 / 갤러리camera-gallery
위치 (GPS)location
딥링크deeplink
오프라인 모드offline-mode
데이터 저장소storage
앱 정보app-info
소셜 로그인 (Google, Apple)social-login-bridge
내비게이션 UI (하단 탭, 상단 메뉴, 하단 시트)navigation
접근성 (패널, TTS/STT/Haptic)accessibility

Standard 이상

기능문서
생체 인증biometric
사이드 드로어navigation
소셜 로그인 (Kakao / Naver / Line)social-login-bridge

Pro

기능문서
인앱 결제 (Google Play & App Store)iap
소셜 로그인 (Meta)social-login-bridge

플랫폼 지원 현황

Android와 iOS 모두 **동일한 기능 수준(패리티)**으로 지원됩니다. iOS 글루는 Android JS API를 그대로 반영하므로, 동일한 코드가 양쪽에서 동작합니다.

플랫폼상태
Android 7.0+ (API 24+)✓ 지원
iOS✓ 지원

On this page