WebBrowser

Installation

Usage

import React, { Component } from 'react';
import { Button, Text, View } from 'react-native';
import * as WebBrowser from 'expo-web-browser';

export default class App extends Component {
  state = {
    result: null,
  };

  render() {
    return (
      <View>
        <Button title="Open WebBrowser" onPress={this._handlePressButtonAsync} />
        <Text>{this.state.result && JSON.stringify(this.state.result)}</Text>
      </View>
    );
  }

  _handlePressButtonAsync = async () => {
    let result = await WebBrowser.openBrowserAsync('https://expo.io');
    this.setState({ result });
  };
}

Handling deep links from the WebBrowser

API

import * as WebBrowser from 'expo-web-browser';

WebBrowser.openBrowserAsync(url)

Arguments

• url (string) -- The url to open in the web browser.
• browserParams (object) (optional) -- A dictionary with following key-value pairs:
  • controlsColor (optional) (string) -- (iOS only) tint color for controls in SKSafariViewController in #AARRGGBB or #RRGGBB format.
  • dismissButtonStyle (optional) (string) -- (iOS only) The style of the dismiss button. Should be one of: done, close, or cancel.
  • enableBarCollapsing (optional) (boolean) -- a boolean determining whether the toolbar should be hiding when a user scrolls the website.
  • enableDefaultShare (optional) (boolean) -- (Android only) a boolean determining whether a default share item should be added to the menu.
  • browserPackage (optional) (string) -- (Android only). Package name of a browser to be used to handle Custom Tabs. List of available packages is to be queried by getCustomTabsSupportingBrowsers method.
  • readerMode (optional) (boolean) -- (iOS only) a boolean determining whether Safari should enter Reader mode, if it is available.
  • secondaryToolbarColor (optional) (string) -- (Android only) color of the secondary toolbar in either #AARRGGBB or #RRGGBB format.
  • showInRecents (optional) (boolean) -- (Android only) a boolean determining whether browsed website should be shown as separate entry in Android recents/multitasking view. Default: false
  • showTitle (optional) (boolean) -- (Android only) a boolean determining whether the browser should show the title of website on the toolbar.
  • toolbarColor (optional) (string) -- color of the toolbar in either #AARRGGBB or #RRGGBB format.
  Note that behavior customization options depend on the actual browser and its version. Some or all of the arguments may be ignored.

Returns

• If the user closed the web browser, the Promise resolves with { type: 'cancel' }.
• If the browser is closed using dismissBrowser , the Promise resolves with { type: 'dismiss' }.

WebBrowser.openAuthSessionAsync(url, redirectUrl)

🚨

This API can only be used in a secure environment (https). You can use expo start:web --https to test this. Otherwise an error with code ERR_WEB_BROWSER_CRYPTO will be thrown.

• Desktop: This will create a new web popup window in the browser that can be closed later using WebBrowser.maybeCompleteAuthSession().
• Mobile: This will open a new tab in the browser which can be closed using WebBrowser.maybeCompleteAuthSession().

• A crypto state will be created for verifying the redirect.
  • This means you need to run with expo start:web --https.
• The state will be added to the window's localstorage. This ensures that auth cannot complete unless it's done from a page running with the same origin as it was started. Ex: if openAuthSessionAsync is invoked on https://localhost:19006, then maybeCompleteAuthSession must be invoked on a page hosted from the origin https://localhost:19006. Using a different website, or even a different host like https://128.0.0.*:19006 for example will not work.
• A timer will be started to check for every 1000 milliseconds (1 second) to detect if the window has been closed by the user. If this happens then a promise will resolve with { type: 'dismiss' }.

Arguments

• url (string) -- The url to open in the web browser. This should be a login page.
• redirectUrl (string) -- optional: the url to deep link back into your app. By default, this will be Constants.linkingUrl
• browserParams (object) -- optional: an object with the same keys as openBrowserAsync's browserParams object. If there is no native AuthSession implementation available (which is the case on Android) these params will be used in the browser polyfill. If there is a native AuthSession implementation, these params will be ignored.

• If the user does not permit the application to authenticate with the given url, the Promise resolved with { type: 'cancel' }.
• If the user closed the web browser, the Promise resolves with { type: 'cancel' }.
• If the browser is closed using dismissBrowser, the Promise resolves with { type: 'dismiss' }.

Error Codes

• ERR_WEB_BROWSER_REDIRECT
• ERR_WEB_BROWSER_BLOCKED
• ERR_WEB_BROWSER_CRYPTO

WebBrowser.maybeCompleteAuthSession(options)

Arguments

• skipRedirectCheck (boolean) -- optional: Attempt to close the window without checking to see if the auth redirect matches the cached redirect URL.

• { type: 'failed' }:
  • Not supported on this platform: If the platform doesn't support this method (iOS, Android).
  • Cannot use expo-web-browser in a non-browser environment: If the code was executed in an SSR or node environment.
  • No auth session is currently in progress: (the cached state wasn't found in local storage). This can happen if the window redirects to an origin (website) that is different to the initial website origin. If this happens in development, it may be because the auth started on localhost and finished on your computer port (Ex: 128.0.0.*). This is controlled by the redirectUrl and returnUrl.
  • Current URL "<URL>" and original redirect URL "<URL>" do not match.: This can occur when the redirect URL doesn't match what was initial defined as the returnUrl. You can skip this test in development by passing { skipRedirectCheck: true } to the function.
• { type: 'success' }:
  • The parent window will attempt to close the child window immediately.

WebBrowser.warmUpAsync(browserPackage)

Arguments

• browserPackage (string) -- optional -- package of browser to be warmed up. If not set, preferred browser will be warmed.

Returns

WebBrowser.mayInitWithUrlAsync(url, package)

Arguments

• url (string) -- url of page that is likely to be loaded firts when opening browser
• package (string) -- optional -- package of browser to be informed. If not set, preferred browser will be used.

Returns

WebBrowser.coolDownAsync(browserPackage)

Arguments

• browserPackage (string) -- optional -- package of browser to be cooled. If not set, preferred browser will be used.

Returns

WebBrowser.dismissBrowser()

Returns

WebBrowser.getCustomTabsSupportingBrowsersAsync

Returns

• browserPackages (string[]) : All packages recognized by PackageManager as capable of handling Custom Tabs. Empty array means there is no supporting browsers on device.
• defaultBrowserPackage (string | null) : Default package chosen by user. Null if there is no such packages. Null usually means, that user will be prompted to choose from available packages.
• servicePackages (string[]) : All packages recognized by PackageManager as capable of handling Custom Tabs Service. This service is used by warmUpAsync, mayInitWithUrlAsync and coolDownAsync.
• preferredBrowserPackage (string | null) : Package preferred by CustomTabsClient to be used to handle Custom Tabs. It favors browser chosen by user as default, as long as it is present on both browserPackages and servicePackages lists. Only such browsers are considered as fully supporting Custom Tabs. It might be null when there is no such browser installed or when default browser is not in servicePackages list.

Error Codes

ERR_WEB_BROWSER_REDIRECT

ERR_WEB_BROWSER_BLOCKED

ERR_WEB_BROWSER_CRYPTO