@capgo/capacitor-inappbrowser

관리형 WebView, 네이티브 UI 레이어링, 프라이빗 세션, 프록시, 다운로드, 팝업 및 앱 메시징을 지원하는 Capacitor용 네이티브 인앱 브라우저입니다.

개요

@capgo/capacitor-inappbrowser Capacitor 앱에 두 가지 브라우저 경로를 제공합니다: open() 시스템 브라우저 환경을 사용하거나, openWebView() 앱에서 크기 조절, 숨기기, 메시징, 스크립트 실행, 프록시 및 Ionic UI 레이어링이 가능한 관리형 네이티브 WebView를 사용하세요.

단순한 외부 브라우저 이상의 기능이 필요할 때 사용하세요: OAuth 및 결제 흐름, 임베디드 지원 포털, 결제 화면, 화상 통화, 문서 포털, 인터랙티브 웹 앱, 또는 라이브 웹 콘텐츠에 네이티브 컨트롤이 필요한 모든 경우에 적합합니다.

패키지 이름이 변경되었습니다.

주요 사용 사례

다음 기능을 통해 라이브 브라우저 페이지 위에 Ionic 또는 Capacitor UI를 표시하세요: toBack, sendToBack(), bringToFront(), transparentBackground, 그리고 dispatchInputEvent().
다음 기능을 사용하여 부분 화면 브라우저, 바텀 시트, PiP(Picture-in-Picture) 웹뷰를 구축하세요: width, height, x, y, 그리고 updateDimensions().
Android 및 iOS에서 사용자 정의 크기의 브라우저 프레임 외부의 Capacitor 앱을 탭할 수 있게 합니다.
Run checkout, login, support, or account-switching flows without persistent website storage using persistWebViewData: false 및 clearAllBrowsingData().
Keep multiple browser instances loaded with hidden, hide(), 그리고 show() 페이지 상태를 그대로 유지할 수 있습니다.
요청 프록시, 파일 upload, download, 팝업 제어, Google Pay 지원, _blank 링크 처리 및 앱-페이지 간 메시징이 필요한 고급 웹 앱을 임베드하세요.

핵심 기능

open - Android에서는 Chrome Custom Tabs에서 URL을 엽니다. SFSafariViewController iOS에서.
openWebView - 커스텀 툴바, 크기 조절, 네이티브 네비게이션, 메시징, 스크립팅, 프록시, download, 팝업 및 데이터 제어 기능이 포함된 관리형 네이티브 WebView를 엽니다.
sendToBack / bringToFront - 관리형 브라우저를 Capacitor 호스트 WebView 뒤 또는 위로 이동시킵니다.
dispatchInputEvent - 네이티브 앱 UI 뒤에 있는 브라우저로 클릭, 터치, 스크롤 이벤트를 전달합니다.
updateDimensions - 페이지를 다시 로드하지 않고 관리형 WebView의 크기와 위치를 변경합니다.
hide / show - 관리형 WebView의 로드 상태를 유지하면서 네이티브 화면 표시를 제거하거나 복구합니다.
postMessage / executeScript - Capacitor 앱과 관리형 페이지 내부에서 실행되는 JavaScript를 연결합니다.
clearAllBrowsingData / persistWebViewData - 쿠키, 캐시, 스토리지, IndexedDB 및 세션 지속성을 제어합니다.
handleDownloads, 프록시 규칙 및 팝업 이벤트를 지원합니다. 문서 포털, upload 흐름, 결제 페이지 및 임베디드 웹 앱에 적합합니다.

공개 API

메서드	설명
`goBack`	가능한 경우 WebView의 히스토리를 뒤로 이동합니다.
`open`	새 창에서 전체 화면으로 URL을 엽니다. Android에서는 Chrome Custom Tabs를, iOS에서는 SFSafariViewController를 사용합니다.
`clearCookies`	다음 시점에 URL의 쿠키를 삭제합니다: `id` 열려 있는 모든 webview에 적용됩니다.
`clearAllCookies`	다음 시점에 모든 쿠키를 삭제합니다: `id` 열려 있는 모든 webview에 적용됩니다.
`clearCache`	다음 시점에 캐시를 삭제합니다: `id` 열려 있는 모든 webview에 적용됩니다.
`clearAllBrowsingData`	기본 스토어 및 관리되는 WebView에서 쿠키, 캐시, local storage, session storage, IndexedDB 및 기타 브라우징 데이터를 삭제합니다.
`getCookies`	특정 URL의 쿠키를 가져옵니다.
`close`	WebView를 닫습니다. 다음 시점에: `id` 인자가 생략되면 활성 WebView를 닫습니다.
`hide`	WebView를 닫지 않고 숨깁니다. 다시 표시하려면 show()를 사용하세요. 다음 시점에: `id` 활성 webview를 대상으로 합니다.
`show`	이전에 숨겨진 WebView를 다시 표시합니다. 다음 경우: `id` 활성 webview를 대상으로 합니다.
`sendToBack`	앱 UI가 브라우저 위에 나타날 수 있도록 네이티브 브라우저를 Capacitor 호스트 WebView 뒤로 이동시킵니다.
`bringToFront`	호스트 WebView 뒤에 있던 브라우저를 다시 앞으로 가져옵니다.
`dispatchInputEvent`	클릭, 터치 또는 스크롤 입력을 관리형 브라우저로 전달합니다. 좌표는 브라우저 뷰포트 기준입니다.
`openWebView`	툴바와 카메라 접근, 파일 접근, 이벤트 수신, JavaScript 주입, 양방향 통신 등 향상된 기능을 갖춘 새 WebView에서 URL을 엽니다.
`executeScript`	InAppBrowser 창에 JavaScript code를 주입합니다. 다음 경우: `id` 를 생략하면, 열려 있는 모든 webview에서 실행됩니다.
`postMessage`	WebView(인앱 브라우저)로 이벤트를 보냅니다. 페이지에서 다음과 같이 리스닝하세요. `window.addEventListener('messageFromNative', listenerFunc)`. `detail` payload는 JSON으로 직렬화할 수 있어야 합니다. 다음 경우: `id` 생략하면, 열려 있는 모든 webview로 브로드캐스트됩니다.
`takeScreenshot`	현재 webview viewport를 PNG 스크린샷으로 캡처합니다. `id` 활성 webview를 대상으로 합니다.
`setUrl`	webview의 URL을 설정합니다. `id` 활성 webview를 대상으로 합니다.
`addListener`	openWebView에서 URL 변경 이벤트를 감지합니다.
`addListener`	이벤트 리스닝: `buttonNearDoneClick`; 페이로드에 webview 정보가 포함됩니다. `id`.
`addListener`	openWebView에서 닫기 클릭 이벤트를 감지합니다.
`addListener`	면책 조항(disclaimer)이 필요한 경우 사용자가 확인 버튼을 누르면 트리거됩니다. openWebView의 shareDisclaimer 및 closeModal과 함께 작동합니다.
`addListener`	webview가 앱으로 이벤트를 보낼 때 발생합니다. `window.mobileApp.postMessage(...)` 페이지 내에서 사용하며, 페이로드는 JSON 직렬화가 가능해야 합니다.
`addListener`	API 플러그인, 네이티브 스크린샷 버튼, 또는 주입된 JavaScript 브릿지를 통해 스크린샷이 캡처될 때마다 트리거됩니다.
`addListener`	페이지 로드가 완료되면 트리거됩니다.
`addListener`	페이지 로드 중 오류가 발생하면 트리거됩니다.
`addListener`	네이티브 다운로드 처리를 통해 파일이 로컬에 저장된 후 트리거됩니다. 이를 활성화하려면 `handleDownloads: true` 웹뷰를 열 때 사용하세요.
`addListener`	네이티브 다운로드 처리에 실패하면 트리거됩니다. 이를 활성화하려면 `handleDownloads: true` 웹뷰를 열 때 사용하세요.
`addListener`	페이지에서 팝업이나 새 창을 열 때마다 트리거됩니다. 반환된 popup id를 `executeScript`, `postMessage`, `show`, `hide`, 그리고 `close`.
`addListener`	네이티브 런타임에서 위임한 프록시 요청을 수신합니다. 직접 호출하는 대신 `addProxyHandler()` 사용하는 것을 권장합니다.
`addListener`	관리되는 페이지에서 발생하는 JavaScript 콘솔 출력을 수신합니다. 이를 활성화하려면 `captureConsoleLogs: true` webview를 열 때.
`handleProxyRequest`	내부 메서드로, 다음에서 사용됩니다: `addProxyHandler()` 프록시 결정 사항을 native로 다시 보내려면 원본을 전달하세요. `phase` 수동 응답 시 `proxyRequest` 리스너.
`removeAllListeners`	이 플러그인의 모든 리스너를 제거합니다.
`reload`	현재 웹 페이지를 새로고침합니다.
`updateDimensions`	webview의 크기를 업데이트합니다. 런타임 중에 webview의 크기와 위치를 변경할 수 있습니다. `id` 활성 webview를 대상으로 합니다.
`setEnabledSafeTopMargin`	런타임 중에 webview의 상단 safe margin 활성화 여부를 설정합니다. `id` 생략하면 활성 웹뷰를 대상으로 합니다. Web에서는 이 메서드가 아무 동작도 하지 않으며 레이아웃 변경 없이 resolve됩니다.
`setEnabledSafeBottomMargin`	런타임 중에 webview의 하단 safe margin 활성화 여부를 설정합니다. `id` 생략하면 활성 웹뷰를 대상으로 합니다. Web에서는 이 메서드가 아무 동작도 하지 않으며 레이아웃 변경 없이 resolve됩니다.
`openSecureWindow`	보안 OAuth2 창을 엽니다. Web에서는 리다이렉트된 URL을 통해 반환하세요 `BroadcastChannel`; 모바일에서는 앱 설정에 커스텀 redirect URI를 등록하세요. 전체 HTML, Info.plist, AndroidManifest 예시는 시작하기 가이드를 참조하세요.

참조 값

인앱 브라우저 또는 WebView를 열 때 툴바 옵션과 함께 이 값들을 사용하세요.

값	사용자는 다음을 확인할 수 있습니다:
`activity`	닫기 및 공유 컨트롤이 있는 간단한 툴바입니다.
`compact`	닫기 컨트롤이 있는 간단한 툴바입니다.
`navigation`	뒤로 가기/앞으로 가기 컨트롤이 있는 전체 네비게이션 툴바.
`blank`	툴바 없음.

Source of Truth

이 레퍼런스는 다음에서 동기화됩니다. src/definitions.ts 에서 capacitor-inappbrowser.