In App Browser
Capacitor plugin in app browser
@capgo/inappbrowser
➡️ Get Instant updates for your App with Capgo 🚀
Fix your annoying bug now, Hire a Capacitor expert 💪
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
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
@capgo/inappbrowser Package Tutorial
The @capgo/inappbrowser package is a Capacitor plugin that allows you to open a URL in an in-app browser window. Here's a step-by-step guide on how to use this package:
Installation
To install the package, run the following command in your project's root directory:
npm install @capgo/inappbrowser
npx cap sync
Usage
Import the
InAppBrowserclass from the@capgo/inappbrowserpackage:import { InAppBrowser } from '@capgo/inappbrowser';Use the
InAppBrowser.openmethod to open a URL in a new fullscreen window:InAppBrowser.open("YOUR_URL");Replace
"YOUR_URL"with the URL you want to open.You can also use other methods provided by the
InAppBrowserclass:clearCookies: Clear all cookies.close: Close the in-app browser window.openWebView: Open a URL in a new webview with toolbars.setUrl: Set the URL of the in-app browser.
Refer to the API section below for more details on these methods.
API
The @capgo/inappbrowser package provides the following API methods:
open(options: OpenOptions): Open a URL in a new fullscreen window. Takes anOpenOptionsobject as a parameter.clearCookies(): Clear all cookies.close(): Close the in-app browser window.openWebView(options: OpenWebViewOptions): Open a URL in a new webview with toolbars. Takes anOpenWebViewOptionsobject as a parameter.setUrl(options: { url: string; }): Set the URL of the in-app browser. Takes an object with aurlproperty as a parameter.addListener('urlChangeEvent', listenerFunc: UrlChangeListener): Listen for URL change events. Takes aUrlChangeListenerfunction as a parameter.addListener('closeEvent', listenerFunc: UrlChangeListener): Listen for close events. Takes aUrlChangeListenerfunction as a parameter.addListener('confirmBtnClicked', listenerFunc: UrlChangeListener): Listen for confirm button click events. Takes aUrlChangeListenerfunction as a parameter.removeAllListeners(): Remove all event listeners.
For more information on the parameters and return values of these methods, refer to the package documentation.
And that's it! You've learned how to use the @capgo/inappbrowser package to open URLs in an in-app browser window in Capacitor. Happy coding!