@capgo/inappbrowser

Capacitor plugin in app browser with urlChangeEvent

Install

npm install @capgo/inappbrowser
npx cap sync

Usage

import { InAppBrowser } from '@capgo/inappbrowser'

InAppBrowser.open({ url: "YOUR_URL" });

Web platform is not supported. Use window.open instead.

Camera usage

Android

Add the following to your AndroidManifest.xml file:

    <uses-permission android:name="android.permission.CAMERA" />
		<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
		<uses-permission android:name="android.permission.RECORD_AUDIO"/>

Then the permission will be asked when the camera is used.

iOS

Add the following to your Info.plist file:

<key>NSCameraUsageDescription</key>
<string>We need access to the camera to record audio.</string>

Microphone usage

Android

Add the following to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Then the permission will be asked when the microphone is used.

iOS

Add the following to your Info.plist file:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to the microphone to record audio.</string>

API

• open(...)
• clearCookies(...)
• clearAllCookies()
• clearCache()
• getCookies(...)
• close()
• openWebView(...)
• executeScript(...)
• postMessage(...)
• setUrl(...)
• addListener('urlChangeEvent', ...)
• addListener('buttonNearDoneClick', ...)
• addListener('closeEvent', ...)
• addListener('confirmBtnClicked', ...)
• addListener('messageFromWebview', ...)
• addListener('browserPageLoaded', ...)
• addListener('pageLoadError', ...)
• removeAllListeners()
• reload()
• Interfaces
• Type Aliases
• Enums

open(...)

open(options: OpenOptions) => Promise<any>

Open url in a new window fullscreen

| Param | Type | | ------------- | --------------------------------------------------- | | options | OpenOptions |

Returns: Promise<any>

Since: 0.1.0

clearCookies(...)

clearCookies(options: ClearCookieOptions) => Promise<any>

Clear cookies of url

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | ClearCookieOptions |

Returns: Promise<any>

Since: 0.5.0

clearAllCookies()

clearAllCookies() => Promise<any>

Clear all cookies

Returns: Promise<any>

Since: 6.5.0

clearCache()

clearCache() => Promise<any>

Clear cache

Returns: Promise<any>

Since: 6.5.0

getCookies(...)

getCookies(options: GetCookieOptions) => Promise<Record<string, string>>

Get cookies for a specific URL.

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | -------------------------------------------------- | | options | GetCookieOptions | The options, including the URL to get cookies for. |

Returns: Promise<Record<string, string>>

close()

close() => Promise<any>

Close the webview.

Returns: Promise<any>

openWebView(...)

openWebView(options: OpenWebViewOptions) => Promise<any>

Open url in a new webview with toolbars, and enhanced capabilities, like camera access, file access, listen events, inject javascript, bi directional communication, etc.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | OpenWebViewOptions |

Returns: Promise<any>

Since: 0.1.0

executeScript(...)

executeScript({ code }: { code: string; }) => Promise<void>

Injects JavaScript code into the InAppBrowser window.

| Param | Type | | --------- | ------------------------------ | | __0 | { code: string; } |

postMessage(...)

postMessage(options: { detail: Record<string, any>; }) => Promise<void>

Sends an event to the webview. you can listen to this event with addListener("messageFromWebview", listenerFunc: (event: Record<string, any>) => void) detail is the data you want to send to the webview, it's a requirement of Capacitor we cannot send direct objects Your object has to be serializable to JSON, so no functions or other non-JSON-serializable types are allowed.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | { detail: Record<string, any>; } |

setUrl(...)

setUrl(options: { url: string; }) => Promise<any>

Sets the URL of the webview.

| Param | Type | | ------------- | ----------------------------- | | options | { url: string; } |

Returns: Promise<any>

addListener('urlChangeEvent', ...)

addListener(eventName: "urlChangeEvent", listenerFunc: UrlChangeListener) => Promise<PluginListenerHandle>

Listen for url change, only for openWebView

| Param | Type | | ------------------ | --------------------------------------------------------------- | | eventName | 'urlChangeEvent' | | listenerFunc | UrlChangeListener |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('buttonNearDoneClick', ...)

addListener(eventName: "buttonNearDoneClick", listenerFunc: ButtonNearListener) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | ----------------------------------------------------------------- | | eventName | 'buttonNearDoneClick' | | listenerFunc | ButtonNearListener |

Returns: Promise<PluginListenerHandle>

addListener('closeEvent', ...)

addListener(eventName: "closeEvent", listenerFunc: UrlChangeListener) => Promise<PluginListenerHandle>

Listen for close click only for openWebView

| Param | Type | | ------------------ | --------------------------------------------------------------- | | eventName | 'closeEvent' | | listenerFunc | UrlChangeListener |

Returns: Promise<PluginListenerHandle>

Since: 0.4.0

addListener('confirmBtnClicked', ...)

addListener(eventName: "confirmBtnClicked", listenerFunc: ConfirmBtnListener) => Promise<PluginListenerHandle>

Will be triggered when user clicks on confirm button when disclaimer is required, works only on iOS

| Param | Type | | ------------------ | ----------------------------------------------------------------- | | eventName | 'confirmBtnClicked' | | listenerFunc | ConfirmBtnListener |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('messageFromWebview', ...)

addListener(eventName: "messageFromWebview", listenerFunc: (event: { detail: Record<string, any>; }) => void) => Promise<PluginListenerHandle>

Will be triggered when event is sent from webview, to send an event to the webview use window.mobileApp.postMessage({ "detail": { "message": "myMessage" } }) detail is the data you want to send to the webview, it's a requirement of Capacitor we cannot send direct objects Your object has to be serializable to JSON, so no functions or other non-JSON-serializable types are allowed.

This method is inject at runtime in the webview

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------------- | | eventName | 'messageFromWebview' | | listenerFunc | (event: { detail: Record<string, any>; }) => void |

Returns: Promise<PluginListenerHandle>

addListener('browserPageLoaded', ...)

addListener(eventName: "browserPageLoaded", listenerFunc: () => void) => Promise<PluginListenerHandle>

Will be triggered when page is loaded

| Param | Type | | ------------------ | -------------------------------- | | eventName | 'browserPageLoaded' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

addListener('pageLoadError', ...)

addListener(eventName: "pageLoadError", listenerFunc: () => void) => Promise<PluginListenerHandle>

Will be triggered when page load error

| Param | Type | | ------------------ | ---------------------------- | | eventName | 'pageLoadError' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 1.0.0

reload()

reload() => Promise<any>

Reload the current web page.

Returns: Promise<any>

Since: 1.0.0

Interfaces

OpenOptions

| Prop | Type | Description | Since | | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----- | | url | string | Target URL to load. | 0.1.0 | | headers | Headers | Headers to send with the request. | 0.1.0 | | credentials | Credentials | Credentials to send with the request and all subsequent requests for the same host. | 6.1.0 | | isPresentAfterPageLoad | boolean | if true, the browser will be presented after the page is loaded, if false, the browser will be presented immediately. | 0.1.0 | | preventDeeplink | boolean | | |

Headers

Credentials

| Prop | Type | | -------------- | ------------------- | | username | string | | password | string |

ClearCookieOptions

| Prop | Type | | --------- | ------------------- | | url | string |

HttpCookie

| Prop | Type | Description | | ----------- | ------------------- | ------------------------ | | url | string | The URL of the cookie. | | key | string | The key of the cookie. | | value | string | The value of the cookie. |

GetCookieOptions

| Prop | Type | | --------------------- | -------------------- | | url | string | | includeHttpOnly | boolean |

OpenWebViewOptions

| Prop | Type | Description | Default | Since | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------ | | url | string | Target URL to load. | | 0.1.0 | | headers | Headers | Headers to send with the request. | | 0.1.0 | | credentials | Credentials | Credentials to send with the request and all subsequent requests for the same host. | | 6.1.0 | | shareDisclaimer | DisclaimerOptions | share options | | 0.1.0 | | toolbarType | ToolBarType | Toolbar type | ToolBarType.DEFAULT | 0.1.0 | | shareSubject | string | Share subject | | 0.1.0 | | title | string | Title of the browser | 'New Window' | 0.1.0 | | backgroundColor | BackgroundColor | Background color of the browser, only on IOS | BackgroundColor.BLACK | 0.1.0 | | activeNativeNavigationForWebview | boolean | If true, active the native navigation within the webview, Android only | false | | | disableGoBackOnNativeApplication | boolean | Disable the possibility to go back on native application, usefull to force user to stay on the webview, Android only | false | | | isPresentAfterPageLoad | boolean | Open url in a new window fullscreen isPresentAfterPageLoad: if true, the browser will be presented after the page is loaded, if false, the browser will be presented immediately. | false | 0.1.0 | | isInspectable | boolean | Whether the website in the webview is inspectable or not, ios only | false | | | isAnimated | boolean | Whether the webview opening is animated or not, ios only | true | | | showReloadButton | boolean | Shows a reload button that reloads the web page | false | 1.0.15 | | closeModal | boolean | CloseModal: if true a confirm will be displayed when user clicks on close button, if false the browser will be closed immediately. | false | 1.1.0 | | closeModalTitle | string | CloseModalTitle: title of the confirm when user clicks on close button, only on IOS | 'Close' | 1.1.0 | | closeModalDescription | string | CloseModalDescription: description of the confirm when user clicks on close button, only on IOS | 'Are you sure you want to close this window?' | 1.1.0 | | closeModalOk | string | CloseModalOk: text of the confirm button when user clicks on close button, only on IOS | 'Close' | 1.1.0 | | closeModalCancel | string | CloseModalCancel: text of the cancel button when user clicks on close button, only on IOS | 'Cancel' | 1.1.0 | | visibleTitle | boolean | visibleTitle: if true the website title would be shown else shown empty | true | 1.2.5 | | toolbarColor | string | toolbarColor: color of the toolbar in hex format | '#ffffff'' | 1.2.5 | | showArrow | boolean | showArrow: if true an arrow would be shown instead of cross for closing the window | false | 1.2.5 | | ignoreUntrustedSSLError | boolean | ignoreUntrustedSSLError: if true, the webview will ignore untrusted SSL errors allowing the user to view the website. | false | 6.1.0 | | preShowScript | String | preShowScript: if isPresentAfterPageLoad is true and this variable is set the plugin will inject a script before showing the browser. This script will be run in an async context. The plugin will wait for the script to finish (max 10 seconds) | | 6.6.0 | | proxyRequests | String | proxyRequests is a regex expression. Please see this pr for more info. (Android only) | | 6.9.0 | | buttonNearDone | { ios: { iconType: 'sf-symbol' | 'asset'; icon: String; }; android: { iconType: 'asset'; icon: String; width?: number; height?: number; }; } | buttonNearDone allows for a creation of a custom button. Please see buttonNearDone.md for more info. | | 6.7.0 |

DisclaimerOptions

| Prop | Type | | ---------------- | ------------------- | | title | string | | message | string | | confirmBtn | string | | cancelBtn | string |

String

Allows manipulation and formatting of text strings and determination and location of substrings within strings.

| Prop | Type | Description | | ------------ | ------------------- | ------------------------------------------------------------ | | length | number | Returns the length of a String object. |

| Method | Signature | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | toString | () => string | Returns a string representation of a string. | | charAt | (pos: number) => string | Returns the character at the specified index. | | charCodeAt | (index: number) => number | Returns the Unicode value of the character at the specified location. | | concat | (...strings: string[]) => string | Returns a string that contains the concatenation of two or more strings. | | indexOf | (searchString: string, position?: number | undefined) => number | Returns the position of the first occurrence of a substring. | | lastIndexOf | (searchString: string, position?: number | undefined) => number | Returns the last occurrence of a substring in the string. | | localeCompare | (that: string) => number | Determines whether two strings are equivalent in the current locale. | | match | (regexp: string | RegExp) => RegExpMatchArray | null | Matches a string with a regular expression, and returns an array containing the results of that search. | | replace | (searchValue: string | RegExp, replaceValue: string) => string | Replaces text in a string, using a regular expression or search string. | | replace | (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string) => string | Replaces text in a string, using a regular expression or search string. | | search | (regexp: string | RegExp) => number | Finds the first substring match in a regular expression search. | | slice | (start?: number | undefined, end?: number | undefined) => string | Returns a section of a string. | | split | (separator: string | RegExp, limit?: number | undefined) => string[] | Split a string into substrings using the specified separator and return them as an array. | | substring | (start: number, end?: number | undefined) => string | Returns the substring at the specified location within a String object. | | toLowerCase | () => string | Converts all the alphabetic characters in a string to lowercase. | | toLocaleLowerCase | (locales?: string | string[] | undefined) => string | Converts all alphabetic characters to lowercase, taking into account the host environment's current locale. | | toUpperCase | () => string | Converts all the alphabetic characters in a string to uppercase. | | toLocaleUpperCase | (locales?: string | string[] | undefined) => string | Returns a string where all alphabetic characters have been converted to uppercase, taking into account the host environment's current locale. | | trim | () => string | Removes the leading and trailing white space and line terminator characters from a string. | | substr | (from: number, length?: number | undefined) => string | Gets a substring beginning at the specified location and having the specified length. | | valueOf | () => string | Returns the primitive value of the specified object. |

RegExpMatchArray

| Prop | Type | | ----------- | ------------------- | | index | number | | input | string |

RegExp

| Prop | Type | Description | | ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | source | string | Returns a copy of the text of the regular expression pattern. Read-only. The regExp argument is a Regular expression object. It can be a variable name or a literal. | | global | boolean | Returns a Boolean value indicating the state of the global flag (g) used with a regular expression. Default is false. Read-only. | | ignoreCase | boolean | Returns a Boolean value indicating the state of the ignoreCase flag (i) used with a regular expression. Default is false. Read-only. | | multiline | boolean | Returns a Boolean value indicating the state of the multiline flag (m) used with a regular expression. Default is false. Read-only. | | lastIndex | number | |

| Method | Signature | Description | | ----------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | exec | (string: string) => RegExpExecArray | null | Executes a search on a string using a regular expression pattern, and returns an array containing the results of that search. | | test | (string: string) => boolean | Returns a Boolean value that indicates whether or not a pattern exists in a searched string. | | compile | () => this | |

RegExpExecArray

| Prop | Type | | ----------- | ------------------- | | index | number | | input | string |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

UrlEvent

| Prop | Type | Description | Since | | --------- | ------------------- | ------------------------- | ----- | | url | string | Emit when the url changes | 0.0.1 |

BtnEvent

| Prop | Type | Description | Since | | --------- | ------------------- | ------------------------------ | ----- | | url | string | Emit when a button is clicked. | 0.0.1 |

Type Aliases

ClearCookieOptions

Omit<HttpCookie, 'key' | 'value'>

Omit

Construct a type with the properties of T except for those in type K.

Pick<T, Exclude<keyof T, K>>

Pick

From T, pick a set of properties whose keys are in the union K

{ [P in K]: T[P]; }

Exclude

Exclude from T those types that are assignable to U

T extends U ? never : T

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

GetCookieOptions

Omit<HttpCookie, 'key' | 'value'>

UrlChangeListener

(state: UrlEvent): void

ButtonNearListener

(state: {}): void

ConfirmBtnListener

(state: BtnEvent): void

Enums

ToolBarType

| Members | Value | | ---------------- | ------------------------- | | ACTIVITY | "activity" | | NAVIGATION | "navigation" | | BLANK | "blank" | | DEFAULT | "" |

BackgroundColor

| Members | Value | | ----------- | -------------------- | | WHITE | "white" | | BLACK | "black" |

Credits

• WKWebViewController - for iOS
• CapBrowser - For the base in capacitor v2