용어집
Appify SDK 문서 전반에서 사용하는 용어를 정리합니다. 각 용어는 문서 내에서 일관된 의미로 사용됩니다.
브릿지 (Bridge)
웹과 네이티브 간 메시지를 중개하는 통신 계층입니다. window.ReactNativeWebView.postMessage()로 메시지를 전송하고, window.addEventListener('message', ...)로 응답을 수신합니다. SDK 메서드를 호출하면 내부적으로 브릿지가 동작합니다. 웹 코드에서 직접 사용하지 않습니다.
웹뷰 (WebView)
앱 내에서 웹 페이지를 표시하는 네이티브 컴포넌트입니다. React Native에서는 <WebView> 컴포넌트가 이 역할을 합니다. 웹 애플리케이션은 WebView 안에서 실행되며, WebView를 통해 네이티브 앱과 메시지를 주고받습니다.
메시지 키 (Message Key)
요청과 응답을 구분하는 고유 식별자입니다. 브릿지는 메시지를 전송할 때 메시지 키를 포함하고, 응답이 도착하면 같은 키로 대기 중인 Promise를 찾아 resolve합니다. 예를 들어 CAMERA_SCAN, GET_LOCATION 같은 문자열 상수입니다.
메시지 라우터 (MessageRouter)
메시지 키에 따라 핸들러를 호출하는 라우팅 시스템입니다. 네이티브 앱 내부에 위치하며, WebView에서 메시지가 도착하면 키를 기준으로 등록된 핸들러를 조회하고 실행합니다. 핸들러가 등록되어 있지 않은 키의 요청은 처리되지 않습니다.
핸들러 (Handler)
특정 메시지 키에 대응하는 네이티브 처리 함수입니다. MessageRouter에 미리 등록해 두며, 해당 키의 메시지가 도착하면 실행됩니다. 카메라 접근, 위치 조회, 푸시 토큰 발급 등 플랫폼별 기능이 핸들러로 구현됩니다.
구독 (Subscription)
이벤트를 지속적으로 수신하는 패턴입니다. subscribe() 또는 이벤트 등록 메서드를 통해 구독을 시작하면, 이벤트가 발생할 때마다 등록한 콜백이 실행됩니다. 더 이상 이벤트를 수신하지 않으려면 반환된 구독 객체의 unsubscribe()를 호출합니다. 컴포넌트 언마운트 시 반드시 해제해야 메모리 누수를 방지할 수 있습니다.
요청 큐 (Request Queue)
동일 키의 동시 요청을 순차 처리하는 대기열입니다. 같은 메시지 키에 대해 여러 요청이 동시에 들어오면, 브릿지는 첫 번째 요청을 전송하고 나머지를 큐에 보관합니다. 응답이 도착하면 다음 요청을 전송합니다. 이 동작은 자동으로 적용됩니다.
직렬화 (Serialization)
모든 요청을 전역 큐에서 하나씩 처리하는 모드입니다. 권한 요청처럼 사용자 상호작용이 필요한 메서드에 적용됩니다. 직렬화 모드에서는 메시지 키와 무관하게 진행 중인 요청이 완료된 뒤 다음 요청이 전송됩니다. 여러 권한을 동시에 요청해도 사용자에게 팝업이 한 번에 하나씩 표시됩니다.
초기화 (Initialize)
SDK 사용 전 네이티브와 설정을 동기화하는 과정입니다. appify.initialize()를 호출하면 SDK가 네이티브 앱과 핸드셰이크를 수행하고 필요한 설정을 받아옵니다. 초기화가 완료되기 전에는 SDK 메서드를 사용할 수 없습니다. 앱 진입점에서 한 번만 호출합니다.
FCM 토큰
Firebase Cloud Messaging에서 발급하는 기기 고유 푸시 식별자입니다. 서버에서 특정 기기로 푸시 알림을 보내려면 이 토큰이 필요합니다. appify.push.getToken()으로 조회합니다. 토큰은 앱 재설치, OS 업데이트 등의 상황에서 변경될 수 있습니다.
딥링크 (Deep Link)
앱의 특정 화면으로 직접 이동하는 URL 스킴입니다. 예를 들어 myapp://product/123 형태의 URL을 열면 앱이 실행되면서 해당 상품 화면으로 직접 이동합니다. appify.app.onDeepLink를 통해 딥링크 이벤트를 구독할 수 있습니다. URL Scheme은 네이티브 앱에 등록되어야 합니다.
SSR (Server-Side Rendering)
서버에서 HTML을 생성하는 렌더링 방식입니다. Next.js, Nuxt 등 SSR 프레임워크에서는 컴포넌트가 서버에서 먼저 실행됩니다. SDK는 window 객체가 없는 SSR 환경에서도 안전하게 동작하도록 설계되었으나, initialize() 및 모든 SDK 메서드는 클라이언트(브라우저) 환경에서만 호출해야 합니다. 서버 코드에서 호출하면 window is not defined 에러가 발생합니다.