nativescript-inappbrowser
Version:
InAppBrowser for NativeScript
391 lines (329 loc) • 20.7 kB
Markdown
<p align="center">
<a href="./LICENSE">
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" />
</a>
<a href="https://npmjs.org/package/nativescript-inappbrowser">
<img src="http://img.shields.io/npm/v/nativescript-inappbrowser.svg" alt="Current npm package version" />
</a>
<a href="https://travis-ci.org/proyecto26/nativescript-inappbrowser">
<img src="https://travis-ci.org/proyecto26/nativescript-inappbrowser.svg?branch=master" alt="Build Status" />
</a>
<a href="https://github.com/proyecto26/nativescript-inappbrowser/graphs/commit-activity">
<img src="https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg" alt="Maintenance" />
</a>
<a href="https://tidelift.com/subscription/pkg/npm-nativescript-inappbrowser?utm_source=npm-nativescript-inappbrowser&utm_medium=referral&utm_campaign=readme">
<img src="https://tidelift.com/badges/package/npm/nativescript-inappbrowser" alt="Tidelift Subscription" />
</a>
<a href="https://opencollective.com/proyecto26" alt="Financial Contributors on Open Collective">
<img src="https://opencollective.com/proyecto26/all/badge.svg?label=financial+contributors" />
</a>
<a href="https://npmjs.org/package/nativescript-inappbrowser">
<img src="http://img.shields.io/npm/dm/nativescript-inappbrowser.svg" alt="Downloads" />
</a>
<a href="https://npmjs.org/package/nativescript-inappbrowser">
<img src="http://img.shields.io/npm/dt/nativescript-inappbrowser.svg?label=total%20downloads" alt="Total downloads" />
</a>
<a href="https://twitter.com/intent/follow?screen_name=jdnichollsc">
<img src="https://img.shields.io/twitter/follow/jdnichollsc.svg?label=Follow%20@jdnichollsc" alt="Follow @jdnichollsc" />
</a>
</p>
<h1 align="center">InAppBrowser for NativeScript</h1>
<h3 align="center">Provides access to the system's web browser and supports handling redirects</h3>
<h4 align="center"><a href="https://developer.chrome.com/multidevice/android/customtabs#whatarethey">Chrome Custom Tabs</a> for Android & <a href="https://developer.apple.com/documentation/safariservices">SafariServices</a>/<a href="https://developer.apple.com/documentation/authenticationservices">AuthenticationServices</a> for iOS.</h4>
<p align="center">
<img width="400px" src="https://github.com/proyecto26/nativescript-inappbrowser/blob/develop/img/inappbrowser.png?raw=true">
</p>
## Who is using InAppBrowser?
Do you want to see this package in action? Check these awesome projects, yay! 🎉
- [Oxycar](https://oxycar.com) - Offers innovative ways to facilitate home-work journeys.
- [Pegus Digital](https://pegus.digital/) - Your innovation partner in digital product development.
Share your awesome project [here](https://github.com/proyecto26/nativescript-inappbrowser/issues/49)! ❤️
## Getting started
```javascript
ns plugin add nativescript-inappbrowser
```
### Manual installation
- **Android Platform with Android Support:**
Modify your **android/build.gradle** configuration:
```
buildscript {
ext {
buildToolsVersion = "28.0.3"
minSdkVersion = 16
compileSdkVersion = 28
targetSdkVersion = 28
// Only using Android Support libraries
supportLibVersion = "28.0.0"
}
```
- **Android Platform with AndroidX:**
Modify your **android/build.gradle** configuration:
```
buildscript {
ext {
buildToolsVersion = "28.0.3"
minSdkVersion = 16
compileSdkVersion = 28
targetSdkVersion = 28
// Remove 'supportLibVersion' property and put specific versions for AndroidX libraries
androidXBrowser = "1.0.0"
// Put here other AndroidX dependencies
}
```
## Usage
Methods | Action
------------- | ------
`open` | Opens the url with Safari in a modal on iOS using **SFSafariViewController**, and Chrome in a new custom tab on Android. On iOS, the modal Safari will not share cookies with the system Safari.
`close` | Dismisses the system's presented web browser.
`openAuth` | Opens the url with Safari in a modal on iOS using **SFAuthenticationSession/ASWebAuthenticationSession**, and Chrome in a new custom tab on Android. On iOS, the user will be asked whether to allow the app to authenticate using the given url **(OAuth flow with deep linking redirection)**.
`closeAuth` | Dismisses the current authentication session.
`isAvailable` | Detect if the device supports this plugin.
`onStart` | Initialize a bound background service so the application can communicate its intention to the browser. After the service is connected, the client can be used to Warms up the browser to make navigation faster and indicates that a given URL may be loaded in the future. - Android Only.
`warmup` | Warm up the browser process - Android Only.
`mayLaunchUrl` | Tells the browser of a likely future navigation to a URL. The most likely URL has to be specified first. Optionally, a list of other likely URLs can be provided. They are treated as less likely than the first one, and have to be sorted in decreasing priority order. These additional URLs may be ignored. All previous calls to this method will be deprioritized - Android Only.
### iOS Options
Property | Description
-------------- | ------
`dismissButtonStyle` (String) | The style of the dismiss button. [`done`/`close`/`cancel`]
`preferredBarTintColor` (String) | The color to tint the background of the navigation bar and the toolbar. [`white`/`#FFFFFF`]
`preferredControlTintColor` (String) | The color to tint the control buttons on the navigation bar and the toolbar. [`gray`/`#808080`]
`readerMode` (Boolean) | A value that specifies whether Safari should enter Reader mode, if it is available. [`true`/`false`]
`animated` (Boolean) | Animate the presentation. [`true`/`false`]
`modalPresentationStyle` (String) | The presentation style for modally presented view controllers. [`automatic`/`none`/`fullScreen`/`pageSheet`/`formSheet`/`currentContext`/`custom`/`overFullScreen`/`overCurrentContext`/`popover`]
`modalTransitionStyle` (String) | The transition style to use when presenting the view controller. [`coverVertical`/`flipHorizontal`/`crossDissolve`/`partialCurl`]
`modalEnabled` (Boolean) | Present the **SafariViewController** modally or as push instead. [`true`/`false`]
`enableBarCollapsing` (Boolean) | Determines whether the browser's tool bars will collapse or not. [`true`/`false`]
`ephemeralWebSession` (Boolean) | Prevent re-use cookies of previous session (openAuth only) [`true`/`false`]
`formSheetPreferredContentSize` (Object) | Custom size for iPad `formSheet` modals [`{width: 400, height: 500}`]
### Android Options
Property | Description
-------------- | ------
`showTitle` (Boolean) | Sets whether the title should be shown in the custom tab. [`true`/`false`]
`toolbarColor` (String) | Sets the toolbar color. [`gray`/`#808080`]
`secondaryToolbarColor` (String) | Sets the color of the secondary toolbar. [`white`/`#FFFFFF`]
`navigationBarColor` (String) | Sets the navigation bar color. [`gray`/`#808080`]
`navigationBarDividerColor` (String) | Sets the navigation bar divider color. [`white`/`#FFFFFF`]
`enableUrlBarHiding` (Boolean) | Enables the url bar to hide as the user scrolls down on the page. [`true`/`false`]
`enableDefaultShare` (Boolean) | Adds a default share item to the menu. [`true`/`false`]
`animations` (Object) | Sets the start and exit animations. [`{ startEnter, startExit, endEnter, endExit }`]
`headers` (Object) | The data are key/value pairs, they will be sent in the HTTP request headers for the provided url. [`{ 'Authorization': 'Bearer ...' }`]
`forceCloseOnRedirection` (Boolean) | Open Custom Tab in a new task to avoid issues redirecting back to app scheme. [`true`/`false`]
`hasBackButton` (Boolean) | Sets a back arrow instead of the default `X` icon to close the custom tab. [`true`/`false`]
`browserPackage` (String) | Package name of a browser to be used to handle Custom Tabs.
`showInRecents` (Boolean) | Determining whether browsed website should be shown as separate entry in Android recents/multitasking view. [`true`/`false`]
`includeReferrer` (Boolean) | Determining whether to include your package name as referrer for the website to track. [`true`/`false`]
### Demo
```ts
import { Utils, Dialogs } from '@nativescript/core';
import { InAppBrowser } from 'nativescript-inappbrowser';
...
openLink = async () => {
try {
const url = 'https://www.proyecto26.com'
if (await InAppBrowser.isAvailable()) {
const result = await InAppBrowser.open(url, {
// iOS Properties
dismissButtonStyle: 'cancel',
preferredBarTintColor: '#453AA4',
preferredControlTintColor: 'white',
readerMode: false,
animated: true,
modalPresentationStyle: 'fullScreen',
modalTransitionStyle: 'coverVertical',
modalEnabled: true,
enableBarCollapsing: false,
// Android Properties
showTitle: true,
toolbarColor: '#6200EE',
secondaryToolbarColor: 'black',
navigationBarColor: 'black',
navigationBarDividerColor: 'white',
enableUrlBarHiding: true,
enableDefaultShare: true,
forceCloseOnRedirection: false,
// Specify full animation resource identifier(package:anim/name)
// or only resource name(in case of animation bundled with app).
animations: {
startEnter: 'slide_in_right',
startExit: 'slide_out_left',
endEnter: 'slide_in_left',
endExit: 'slide_out_right'
},
headers: {
'my-custom-header': 'my custom header value'
},
hasBackButton: true,
browserPackage: '',
showInRecents: false
});
Dialogs.alert({
title: 'Response',
message: JSON.stringify(result),
okButtonText: 'Ok'
});
}
else {
Utils.openUrl(url);
}
}
catch(error) {
Dialogs.alert({
title: 'Error',
message: error.message,
okButtonText: 'Ok'
});
}
}
...
```
### Android Optimizations
On Android, you can warmup the in app browser client to make it launch siginificantly faster. To do so, add the following to your [Custom Android Activity](https://docs.nativescript.org/advanced-concepts.html#extending-android-activity).
```ts
import { InAppBrowser } from "nativescript-inappbrowser";
()
("org.nativescript.demo.MainActivity")
export class Activity extends androidx.appcompat.app.AppCompatActivity {
public onStart(): void {
// InAppBrowser initialization for CustomTabsServiceConnection
InAppBrowser.onStart();
}
}
```
You can further optimize performance and pre-render pages [by providing the urls that the user is likely to open](https://developer.chrome.com/docs/android/custom-tabs/best-practices/#pre-render-content).
```ts
constructor() {
super();
// Do not call this every time the component render
InAppBrowser.mayLaunchUrl(this._url, [
"https://twitter.com/NativeScript",
"https://github.com/NativeScript/NativeScript",
"https://openjsf.org"
]);
}
```
### Authentication Flow using Deep Linking
In order to redirect back to your application from a web browser, you must specify a unique URI to your app. To do this,
define your app scheme and replace `my-scheme` and `my-host` with your info.
- Enable deep linking (Android) - **[AndroidManifest.xml](https://github.com/proyecto26/nativescript-inappbrowser/blob/master/demo/app/App_Resources/Android/src/main/AndroidManifest.xml#L41)**
```
<activity
...
android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="my-scheme" android:host="my-host" android:pathPrefix="" />
</intent-filter>
</activity>
```
- Enable deep linking (iOS) - **[Info.plist](https://github.com/proyecto26/nativescript-inappbrowser/blob/master/demo/app/App_Resources/iOS/Info.plist#L21)**
```
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>my-scheme</string>
<key>CFBundleURLSchemes</key>
<array>
<string>my-scheme</string>
</array>
</dict>
</array>
```
- utilities.ts
```javascript
export const getDeepLink = (path = "") => {
const scheme = 'my-scheme';
const prefix = global.isAndroid ? `${scheme}://my-host/` : `${scheme}://`;
return prefix + path;
}
```
- home-page.ts
```ts
import { Utils, Dialogs } from '/core';
import { InAppBrowser } from 'nativescript-inappbrowser';
import { getDeepLink } from './utilities';
...
async onLogin() {
const deepLink = getDeepLink('callback')
const url = `https://my-auth-login-page.com?redirect_uri=${deepLink}`
try {
if (await InAppBrowser.isAvailable()) {
InAppBrowser.openAuth(url, deepLink, {
// iOS Properties
ephemeralWebSession: false,
// Android Properties
showTitle: false,
enableUrlBarHiding: true,
enableDefaultShare: false
}).then((response) => {
if (
response.type === 'success' &&
response.url
) {
Utils.openUrl(response.url)
}
})
} else Utils.openUrl(url)
} catch {
Utils.openUrl(url)
}
}
...
```
### StatusBar
The StatusBar will keep the last one provided in your app. So if the StatusBar is `dark-content` before you open the browser this will keep it.
### Authentication
Using in-app browser tabs (like SFAuthenticationSession/ASWebAuthenticationSession and Android Custom Tabs) where available. Embedded user-agents, known as web-views (like UIWebView and WKWebView), are explicitly not supported due to the usability and security reasons documented in [Section 8.12 of RFC 8252](https://tools.ietf.org/html/rfc8252#section-8.12).
## Credits 👍
* **React Native InAppBrowser:** [InAppBrowser for React Native](https://github.com/proyecto26/react-native-inappbrowser)
## Contributing ✨
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated** ❤️.
You can learn more about how you can contribute to this project in the [contribution guide](https://github.com/proyecto26/nativescript-inappbrowser/blob/develop/CONTRIBUTING.md).
## Contributors ✨
Please do contribute! Issues and pull requests are welcome.
### Code Contributors
This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/0)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/1)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/2)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/3)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/4)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/5)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/6)[](https://sourcerer.io/fame/jdnichollsc/proyecto26/nativescript-inappbrowser/links/7)
### Collaborators
<!-- COLLABORATORS-LIST:START - Do not remove or modify this section -->
| [<img alt="jdnichollsc" src="https://avatars3.githubusercontent.com/u/2154886?v=3" width="100" /><br /><sub><b>Juan Nicholls</b></sub>](https://github.com/jdnichollsc)<br />[✉](mailto:jdnichollsc@hotmail.com) | [<img alt="NathanaelA" src="https://avatars3.githubusercontent.com/u/850871?v=3" width="100" /><br /><sub><b>Nathanael Anderson</b></sub>](https://github.com/NathanaelA)<br />[✉](mailto:nathan@master-technology.com) |
| :---: | :---: |
<!-- COLLABORATORS-LIST:END -->
### Financial Contributors
Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/proyecto26/contribute)]
#### Individuals
<a href="https://opencollective.com/proyecto26"><img src="https://opencollective.com/proyecto26/individuals.svg?width=890"></a>
#### Organizations
Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/proyecto26/contribute)]
<a href="https://opencollective.com/proyecto26/organization/0/website"><img src="https://opencollective.com/proyecto26/organization/0/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/1/website"><img src="https://opencollective.com/proyecto26/organization/1/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/2/website"><img src="https://opencollective.com/proyecto26/organization/2/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/3/website"><img src="https://opencollective.com/proyecto26/organization/3/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/4/website"><img src="https://opencollective.com/proyecto26/organization/4/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/5/website"><img src="https://opencollective.com/proyecto26/organization/5/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/6/website"><img src="https://opencollective.com/proyecto26/organization/6/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/7/website"><img src="https://opencollective.com/proyecto26/organization/7/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/8/website"><img src="https://opencollective.com/proyecto26/organization/8/avatar.svg"></a>
<a href="https://opencollective.com/proyecto26/organization/9/website"><img src="https://opencollective.com/proyecto26/organization/9/avatar.svg"></a>
## Supporting 🍻
I believe in Unicorns 🦄
Support [me](http://www.paypal.me/jdnichollsc/2), if you do too.
Donate **Ethereum**, **ADA**, **BNB**, **SHIBA**, **USDT**, **DOGE**:
> Wallet address: 0x3F9fA8021B43ACe578C2352861Cf335449F33427
Please let us know your contributions! 🙏
## Enterprise 💼
Available as part of the Tidelift Subscription.
The maintainers of InAppBrowser for NativeScript and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-nativescript-inappbrowser?utm_source=npm-nativescript-inappbrowser&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
## Security contact information 🚨
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
## License ⚖️
This repository is available under the [MIT License](https://github.com/proyecto26/nativescript-inappbrowser/blob/develop/LICENSE).
## Happy coding 💯
Made with ❤️
<img width="150px" src="https://avatars0.githubusercontent.com/u/28855608?s=200&v=4" align="right">