React Native In-App Browser

[![npm (scoped)][npm_shield]][npm] ![license: mit][license_shield]

In-App browser support for React Native, using [Chrome Custom Tabs][chromecustomtabs]
on Android
and [Safari View Controller][sfsafariviewcontroller] on iOS.

Compatibility

⚠️Support has ended on October 1st 2020.

It is recommended migrating to [react-native-inappbrowser-reborn] for continued support and more features.

| React Native | Library | Status | End-of-Life |
| :---------------: | :---------------------------------------: | :--------: | :---------: |
| 0.60.0 - 0.62.x | [![npm (scoped)][npm_shield]][npm] | EOL | 2020-10-01 |
| 0.57.x - 0.59.x | [![npm v2 (scoped)][npm_2_shield]][npm_2] | EOL | 2020-01-03 |
| 0.57.x - 0.59.5 | [![npm v1 (scoped)][npm_1_shield]][npm_1] | EOL | 2019-06-09 |

Using Expo? Check out WebBrowser.

Installation

Install the package via Yarn or npm:

``sh
yarn add @matt-block/react-native-in-app-browser

or


npm install --save @matt-block/react-native-in-app-browser
`

Linking

$3

Packages are autolinked,
however an extra step for iOS projects is needed:

`sh
cd ios && pod install && cd ..
`

$3

Manually link the native module to your project:

`sh
react-native link @matt-block/react-native-in-app-browser
`

$3

In order for Xcode projects to build when using Swift-based libraries, your
main app project must contain Swift code and a bridging header. If your app
project does not contain any Swift code, add a single empty .swift file and an
empty bridging header to your app.

If your Xcode project already makes use of Swift code you can safely ignore this
note.

Usage

> ⚠️ Still using an older version ? Check out the migration guides.

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";


// Minimal setup.
InAppBrowser.open("https://www.wikipedia.org/").catch(error => {
console.log(error);
});


// With platform-specific optional settings.
InAppBrowser.open("https://www.wikipedia.org/", {
android: {
//...,
},
ios: {
//...,
},
}).catch(error => {
console.log(error);
});


// Using async/await.
async onClickHandler() {
try {
await InAppBrowser.open("https://www.wikipedia.org/");
} catch (error) {
console.log(error);
}
}
`

$3

Chrome Custom Tabs exposes methods to reduce the start time of a custom tab activity.

For information on how these work, check Custom Tabs - Example and Usage Optimization

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.warmup();
InAppBrowser.mayLaunchUrl("https://wikipedia.org");
`

$3

It is possible to manually dismiss the iOS in-app instance by calling the method close.

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.close();
`

This is not possible on Android since Chrome Custom Tabs do not expose such functionality and [Activity workarounds][customtabsmanualclose] would bring this package way out of scope.

Settings

The main method open accepts an object with settings objects for each
platform:

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

InAppBrowser.open("https://www.wikipedia.org/", {
android: {},
ios: {}
});
`

Settings can also be initialized separately with configure so that each open call won't need to specify them each time:

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

// Somewhere in your app initialization logic.
InAppBrowser.configure({
android: {},
ios: {}
});

// Other part of your code base.
// Previously initialized settings will apply.
InAppBrowser.open("https://www.wikipedia.org/");
`

Note that open will still accept settings as always but will effectively perform a merge between the initialized properties and the provided settings object (which will have priority over the initialized properties):

`javascript
import { InAppBrowser } from "@matt-block/react-native-in-app-browser";

// Somewhere in your app initialization logic.
InAppBrowser.configure({
android: {
toolbarColor: "red",
showTitle: true
}
});

// Other part of your code base.
// Merged settings for this call will result in:
//
// - toolbarColor: "blue",
// - showTitle: true
InAppBrowser.open("https://www.wikipedia.org/", {
android: {
toolbarColor: "blue"
}
});
`

The properties for each platform settings are described below.

$3

Each setting is optional. Furthermore, settings with invalid values will be
ignored and their default values will be used.

| Setting | Type | Default | Description |
| --------------------- | --------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| toolbarColor | string | undefined | The color to tint the background of the toolbar.
Provided color can be in any [@ctrl/tinycolor][tinycolor] supported format. |
| showTitle | boolean | false | Flag to toggle if the page title should be shown in the custom tab. |
| closeButtonIcon | string _(as resolved by importing an image file)_ | undefined | Custom close button icon.

Provided icon must be a .png, .jpg, or .gif file. |
| addDefaultShareMenu | boolean | false | Flag to toggle the default share menu. |

$3

Each setting is optional. Furthermore, settings with invalid values will be
ignored and their default values will be used. Also, settings that are not
supported by the iOS version at runtime will be ignored as well.

| Setting | Type | Default | Description |
| --------------------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| preferredBarTintColor | string | undefined | The color to tint the background of the navigation bar and the toolbar.
Provided color can be in any [@ctrl/tinycolor][tinycolor] supported format.

Available on: iOS >= 10.0. |
| preferredControlTintColor | string | undefined | The color to tint the control buttons on the navigation bar and the toolbar.
Provided color can be in any [@ctrl/tinycolor][tinycolor] supported format.

Available on: iOS >= 10.0. |
| barCollapsingEnabled | boolean | true | Available on: iOS >= 11.0. |
| dismissButtonStyle | string | undefined | Available on: iOS >= 11.0. |
| entersReaderIfAvailable | boolean | false | A value that specifies whether Safari should enter Reader mode, if it is available.

Available on: iOS >= 11.0. |




Example

An example project showcasing the various configurations can be found in the
example directory.
Simply clone this repository, navigate into example, install the dependencies
and run the app.

`sh
git clone https://github.com/matei-radu/react-native-in-app-browser.git
cd react-native-in-app-browser/example
yarn install
yarn start
yarn android # or yarn ios
``

License

Copyright (c) 2018-2020 Matei Bogdan Radu.

This source code is licensed under the MIT license found in the
[LICENSE][license] file in the root directory of this source tree.

[chromecustomtabs]: https://developer.chrome.com/multidevice/android/customtabs
[customtabsmanualclose]: https://stackoverflow.com/a/41596629/1887860
[sfsafariviewcontroller]: https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller
[license]: https://github.com/matei-radu/react-native-in-app-browser/blob/master/LICENSE
[license_shield]: https://img.shields.io/badge/license-MIT-blue.svg
[prettier_shield]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg
[prettier]: https://github.com/prettier/prettier
[npm]: https://www.npmjs.com/package/@matt-block/react-native-in-app-browser
[npm_shield]: https://img.shields.io/npm/v/@matt-block/react-native-in-app-browser/latest
[npm_2]: https://www.npmjs.com/package/@matt-block/react-native-in-app-browser/v/2.1.3
[npm_2_shield]: https://img.shields.io/npm/v/@matt-block/react-native-in-app-browser/legacy
[npm_1]: https://www.npmjs.com/package/@matt-block/react-native-in-app-browser/v/1.4.1
[npm_1_shield]: https://img.shields.io/badge/npm-v1.4.1-blue
[tinycolor]: https://github.com/TypeCtrl/tinycolor
[react-native-inappbrowser-reborn]: https://github.com/proyecto26/react-native-inappbrowser