Vega WebView Component Reference

This page lists the API properties and methods that Vega WebView currently supports. As noted in the overview section, Vega WebView is a Vega port of react-native-webview, and it currently only supports a limited set of APIs. To set up to use WebView, see Overview of Vega Web Apps.

Props

source

Loads the given URI with optional headers. The source object has the following sub properties.

uri (string): The URI to load on the WebView.
headers (object): Additional HTTP headers to send with the request.

Here is an example.

<WebView
    source ={{
        uri: "http://amazon.com/",
        headers: { "custom-app-header": "react-native-webview-app", "custom-app-header2": "VALUE2" }}}/>

onLoad

After WebView loads the web page, it calls onLoad. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoad={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When you call the onLoad function pass the following properties:

url(str) - loaded URL in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.

onLoadStart

When WebView starts loading resources, it calls onLoadStart. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoadStart={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When calling onLoadStart pass the following properties.

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.

onError

When the WebView fails to load the API calls onError. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onError={(event) => {
    console.log('url: ', event.nativeEvent.url)
  }}/>

When calling the onError function pass the following properties.

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.
code(int)  - error code.
description(str) - error description.

onHttpError

When WebView fails to load it throws an onHttpError HTTP status error and the API calls the onHttpError function. Any statusCodes >= 400 is an HTTP status error. The isMainFrame flag identifies whether an error occurred when loading the main page, or a dependent resource. This will be true for main frame and false for subresources or iframes.

Type	Required
function	No

Here is an example.

<WebView
  source={{ uri: 'https://example.com' }}
  onHttpError={(event) => {
    console.log('url: ', event.nativeEvent.url)
    console.log("HttpError statusCode, description, isMainFrame: ",
                  event.nativeEvent.statusCode,
                  event.nativeEvent.description,
                  event.nativeEvent.isMainFrame );
  }}/>

When calling the onHttpError function pass the following properties.

url
canGoBack
canGoForward
statusCode
description
isMainFrame

onCloseWindow

This function notifies the host app to close the given WebView and remove it from the view system. Since any WebView interaction after this call might result in unexpected behavior, the host app should destroy the WebView instance after receiving this call. There is no default functionality for this method.

Type	Required
function	No

Here is an example.

import React, { BackHandler } from 'react-native';
<WebView
  source={{ uri : 'https://example.com/' }}
  onCloseWindow={
    () => { // Handle the close event raised from the loaded webpage BackHandler.exitApp() }
   } />

onMessage

Invoked when the WebView JS calls ReactNativeWebView.postMessage. It accepts one argument and is available to the event object. The data must be a string. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onMessage={(event) => {
    console.log("data: ", event.nativeEvent.data);
  }}/>

onShouldStartLoadWithRequest

onShouldStartLoadWithRequest allows custom handling of any WebView requests. A return of true continues loading the request, and false stops loading. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onShouldStartLoadWithRequest={(request) => {
        return request.url.startsWith('https://amazon.com');
  }}/>

This onShouldStartLoadWithRequest object can contain the following properties.

url(str) - loaded url in the WebView.
canGoBack(bool) - WebView has history to go back.
canGoForward(bool) - WebView has history to go forward.
lockIdentifier(int) - lock identifier number for JS and native sync.

onClientCertAuthentication (optional)

This optional function enables a host app to manage client certificate authentication requests.

Parameters

This gives you the details of the authentication request.

  request (Type: ClientCertAuthenticationRequest)

This callback object has a function to handle authentication.

  callback (Type: ClientCertAuthenticationCallback)

Callback Functions

This function handles the client certificate authentication when the certificate is in PKCS#12 format.

    handleWithPkcs12(certificateData: Pkcs12CertificateData)

This function cancels the client certificate authentication process.

    cancel()

The default behavior is to cancel the request without a client certificate. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  onClientCertAuthentication={(request, callback) => {

      // To handle with authentication:
      callback.handleWithPkcs12({
            certificate: "base64-certificate",
            password: "certificate-password",
      });

      // To decline the request:
      callback.cancel();
  }}/>

The request object contains the following properties:

hostName - The server’s host name.
portNumber - The port number for the request.

onSslError (optional)

This optional function notifies the host app that an SSL error occurred when it was loading a resource. The host app must call either SslErrorHandler.cancel() or SslErrorHandler.proceed(). By default, it rejects when an SSL error occurs when loading the URL. Users can call the proceed() or cancel() methods to respond to future SSL errors. By default one of these functions cancels the resource loading process. WebView calls this function only for recoverable SSL certificate errors, such as untrusted certifier, certificate expiration, or self-signed. For non-recoverable errors, such as when the server fails the client, WebView calls onError(WebView, WebResourceRequest, WebResourceError) with the ERROR_FAILED_SSL_HANDSHAKE (-11) argument. Here is an example.

const handleSSLError = (sslError: SslErrorData , callback: OnSslErrorCallback) => {
    console.log("WebViewClient: ", sslError.url, sslError.code, sslError.description);
    // so keeping some delay, assuming it might take sometimes to load the resource, and user to select.
    setTimeout(() => {
    // to accept the SSL error.
    callback.proceed();
    // to reject the SSL error
    // callback.cancel();
    }, 5000);
}
  <WebView
      source={{ uri: 'https://self-signed.badssl.com/' }}
      onSslError={(sslError: SslErrorData , callback: OnSslErrorCallback) => {
      HandleSSLError(sslError, sslErrorHandler);
  }}/>

SslErrorData objects

The SslErrorData object contains the following properties:

url
code
description

The OnSslErrorCallback object contains the following methods:

proceed() allows an SSL error.
cancel() Rejects an SSL error.

javaScriptEnabled

A Boolean value to enable or disable JavaScript in WebView. The default value is true. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  javaScriptEnabled={true}/>

allowJavaScriptInBackground

A boolean value to enable JavaScript when the WebView app is in the background. The default is false. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  allowJavaScriptInBackground={true}/>

domStorageEnabled

A Boolean value to enable or disable DOM Storage (local web storage) in WebView. The default is false. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  domStorageEnabled={true}/>

userAgent

Sets user-Agent for WebView. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  userAgent={"custom-user-agent"}/>

mixedContentMode

Specifies mixed content mode for the WebView. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  mixedContentMode = {'always'}
  }/>

Possible values for mixedContentMode are the following.

Never (default), which uses MIXED_CONTENT_NEVER_ALLOW WebView doesn’t allow a secure origin to load content from an insecure origin. Consider this mode because it is the most secure.
Always, which uses MIXED_CONTENT_ALWAYS_ALLOW. WebView allows a secure origin to load content from any other origin, even if that origin is insecure. Amazon doesn’t recommend this because it is the least secure.
Compatibility, which uses MIXED_CONTENT_COMPATIBILITY_MODE. WebView attempts to be compatible with the approach used by a modern web browser with regard to mixed content. WebView might allow some insecure content from a secure origin and when other types of content are blocked. The types of content that WebView allows or blocks might change release to release and are not explicitly defined. This mode is intended for apps that don’t control their own rendered content but require some reasonable security. For the highest security, use MIXED_CONTENT_NEVER_ALLOW.

allowFileAccess

A Boolean value to enable or disable access to the file system using file:// URI’s. The default value is false. Here is an example.

<WebView
  source={{ uri: 'file:///<Path to file>' }}
  allowFileAccess = {true}/>

allowSystemKeyEvents

A boolean that determines whether web app listens for special system key events like the Back button (keyCode: 27) in the Web JavaScript layer. This functionality helps web app developers who want to keep their business logic fully on the website instead of relying on the app code. The app can have its own back handlers, when allowSystemKeyEvents is true, and the event will be propagated based on the order components register their back handler (WebView/Application handlers). This will make sure that system key events are handled appropriately for the WebView content while providing application-level control. Key considerations:

Once WebView receives the back key event, it always consumes the event. It does not propagate to other remaining back handlers (if any), even if the app’s JavaScript does not consume the key event.
In multiple WebView scenario(s), only the last created WebView instance gets back key events.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  allowSystemKeyEvents={true}/>

mediaPlaybackRequiresUserAction

A Boolean value to determine whether HTML5 audio and video requires a user to gesture before it starts playing. The default value is true. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  mediaPlaybackRequiresUserAction = {false}/>

thirdPartyCookiesEnabled

A Boolean value to enable or disable developer cookies in WebView. The default is false. Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  thirdPartyCookiesEnabled={false}/>

allowsDefaultMediaControl

Allows the VegaMediaControl events to be automatically bridged to the active WebView media session. This allows seamless integration of voice commands for the WebView. For more details, see Vega Media Controls Overview.

true enables the default media transport controls for the WebView media session, such as play, pause, seek forward, seek backward.
false disables the default media transport controls.

Considerations:

This setting affects all media content types including advertisements and live streams.
For granular control over media content, see Overriding default media control handlers.

Here is an example.

<WebView
  source={{ uri: 'https://amazon.com' }}
  allowsDefaultMediaControl={true}/>

injectedJavaScriptBeforeContentLoaded

Set injectedJavaScriptBeforeContentLoaded to inject JavaScript into a web page after the document element is created, but before other subresources finish loading. This is useful to inject anything into the window, localStorage, or document prior to web code execution. Here’s an example:

const INJECTED_JAVASCRIPT = `
  (function() {
    window.onload = function() {
      window.ReactNativeWebView.postMessage('window.onload occurred');
      return true;
    };
    return true;
  })();
`;

<WebView
  source={{ uri: 'https://reactnative.dev' }}
  injectedJavaScriptBeforeContentLoaded={INJECTED_JAVASCRIPT}
  onMessage={(event) => {
    console.log('Received message:', event.nativeEvent.data);
  }}
/>

Methods

injectJavaScript

injectJavaScript evaluates the JavaScript string in WebView. Here is an example.

const webRef = useRef(null);
webRef.current.injectJavaScript('alert("Hello world")');

<WebView
  source={{ uri: 'https://amazon.com' }}
  ref={webRef}/>

stopLoading

This stops loading the current page. Here is an example.

const webRef = useRef(null);
<WebView
  source={{ uri: 'https://amazon.com' }}
  onLoadStart={(event) => {
    webRef.current.stopLoading();
  }}
  ref={webRef}/>

clearCache(bool)

Clears the resource cache. The cache is per app, so clearCache clears the cache for all WebView parts of the same app. If the argument is true, it includes disk files. If the argument is false, it clears only the RAM cache. Here is an example.

const webRef = useRef(null);

<WebView
  source={{ uri: 'https://amazon.com' }}
  ref={webRef}
  onLoad={(event) => {
    webRef.current.clearCache(true);
  }}/>

goBack()

Goes back one page in the WebView history. If there are no items in the history, this function performs no operations (no-op), and returns. Here is an example.

const webRef = useRef(null);

<View style={{ flex: 1 }}>
  <Button
    title="GoBack"
    onPress={() => { if (webRef.current) { webRef.current.goBack(); }}}
  />
  <WebView
    source={{ uri: 'https://amazon.com' }}
    ref={webRef}
  />
</View>

goForward()

Goes forward one page in the WebView history. If there are no items in the history to go forward, this function performs no operations (no-op), and returns. Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
   <Button
     title="Go Forward"
     onPress={() => { if (webRef.current) { webRef.current.goForward(); } }}
   />
   <WebView
     source={{ uri: 'https://example.com' }}
     ref={webRef}
   />
 </View>

clearHistory()

Clears the internal back/forward history for the WebView instance. Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
   <Button
     title="Clear History"
     onPress={() => { if (webRef.current) { webRef.current.clearHistory(); } }}
   />
   <WebView
     source={{ uri: 'https://example.com' }}
     ref={webRef}
   />
 </View>

dispatchTouchEvent(event: TouchEvent)

Dispatches a touch event to the specified target web element. It allows you to programmatically raise touch events such as touchstart and touchend.

Parameters

event: A TouchEvent object representing dispatched touch. This object contains information about the type of touch event (type) and an array of touch points associated with the event (touches). Here is an example.

  const webRef = useRef(null);

  <View style={{ flex: 1 }}>
    <Button
        title="Trigger Touch"
        onPress={() =>{
          const touches: Touch[] = [ { clientX: 100, clientY: 200 }];
          // Create a new TouchEvent object
          const touchStartEvent = new TouchEvent("touchstart", { touches });
          webRef.current && webRef.current.dispatchTouchEvent(touchStartEvent)
          // Create a new TouchEvent object
          const touchEndEvent = new TouchEvent("touchend", { touches });
          webRef.current && webRef.current.dispatchTouchEvent(touchEndEvent)}
        }
    />
    <WebView
      source={{ uri: 'https://amazon.com' }}
      ref={webRef}
    />
  </View>

scrollBy(offsetX: number, offsetY: number)

Scrolls the content of the WebView by the specified offset values. This method allows you to programmatically scroll the content of the WebView by a specified horizontal (offsetX) and vertical (offsetY) offset.

Parameters

offsetX: A number representing the horizontal offset by which to scroll the content. A positive value scrolls the content to the right. A negative value scrolls it to the left.
offsetY: A number representing the vertical offset by which to scroll the content. A positive value scrolls the content downwards. A negative value scrolls it upwards.

Here is an example.

  const webRef = useRef(null);

  <View style={{ flex: 1 }}>
    <Button
      title="Scroll Down"
      onPress={() => { if (webRef.current) { webRef.current.scrollBy(0, 100); } }}
    />
    <WebView
      source={{ uri: 'https://amazon.com' }}
      ref={webRef}
    />
  </View>

getVisualViewportInfo()

Retrieves information about the visual viewport of the WebView.

Returns

An object containing information about the visual viewport, including:

height: The height of the visual viewport.
width: The width of the visual viewport.
offsetTop: The offset from the top of the visual viewport to the top of the content.
offsetLeft: The offset from the left of the visual viewport to the left of the content.

Here is an example.

  const webRef = useRef(null);

  const handleWebViewLoad = (event: WebViewNavigationEvent) => {
      console.log(" getVisualViewportInfo: ", webRef.current.getVisualViewportInfo());
  };

  <View style={{ flex: 1 }}>
    <WebView
      source={{ uri: 'https://example.com' }}
      onLoad = {handleWebViewLoad}
      ref={webRef}
    />
  </View>

getContentSizeInfo()

Retrieves information about the size of the content within the WebView.

Returns

An object containing information about the content size, including:

scrollWidth: The total width of the content.
scrollHeight: The total height of the content.

Here is an example.

  const webRef = useRef(null);

  const handleWebViewLoad = (event: WebViewNavigationEvent) => {
      console.log(" getContentSizeInfo: ", webRef.current.getContentSizeInfo());
  };

  <View style={{ flex: 1 }}>
    <WebView
      source={{ uri: 'https://example.com' }}
      onLoad = {handleWebViewLoad}
      ref={webRef}
    />
  </View>

reload()

This method reloads the current page of the WebView instance. Here is an example.

 const webRef = useRef(null);

 <View style={{ flex: 1 }}>
  <Button
    title="Reload"
    onPress={() => { if (webRef.current) { webRef.current.reload(); } }}
  />
  <WebView
    source={{ uri: 'https://example.com' }}
    ref={webRef}
  />
 </View>

​Props

​source

​onLoad

​onLoadStart

​onError

​onHttpError

​onCloseWindow

​onMessage

​onShouldStartLoadWithRequest

​onClientCertAuthentication (optional)

​Parameters

​Callback Functions

​onSslError (optional)

​SslErrorData objects

​javaScriptEnabled

​allowJavaScriptInBackground

​domStorageEnabled

​userAgent

​mixedContentMode

​allowFileAccess

​allowSystemKeyEvents

​mediaPlaybackRequiresUserAction

​thirdPartyCookiesEnabled

​allowsDefaultMediaControl

​injectedJavaScriptBeforeContentLoaded

​Methods

​injectJavaScript

​stopLoading

​clearCache(bool)

​goBack()

​goForward()

​clearHistory()

​dispatchTouchEvent(event: TouchEvent)

​Parameters

​scrollBy(offsetX: number, offsetY: number)

​Parameters

​getVisualViewportInfo()

​Returns

​getContentSizeInfo()

​Returns

​reload()

​Related topics

Props

source

onLoad

onLoadStart

onError

onHttpError

onCloseWindow

onMessage

onShouldStartLoadWithRequest

onClientCertAuthentication (optional)

Parameters

Callback Functions

onSslError (optional)

SslErrorData objects

javaScriptEnabled

allowJavaScriptInBackground

domStorageEnabled

userAgent

mixedContentMode

allowFileAccess

allowSystemKeyEvents

mediaPlaybackRequiresUserAction

thirdPartyCookiesEnabled

allowsDefaultMediaControl

injectedJavaScriptBeforeContentLoaded

Methods

injectJavaScript

stopLoading

clearCache(bool)

goBack()

goForward()

clearHistory()

dispatchTouchEvent(event: TouchEvent)

Parameters

scrollBy(offsetX: number, offsetY: number)

Parameters

getVisualViewportInfo()

Returns

getContentSizeInfo()

Returns

reload()

Related topics