ark-webview v0.1.4

Introduction to React Native Ark WebView

React Native Ark WebView is a powerful, customizable component that allows developers to embed web content directly into their React Native applications. The Ark WebView component supports a wide range of features, including secure browsing, interaction with JavaScript code, offline content support, and platform-specific customization for Android and iOS.

Ark WebView is designed to seamlessly integrate web content within mobile applications, providing developers with a unified interface for interacting with web pages while maintaining native functionality. This makes it an ideal choice for hybrid applications, where part of the app's content or functionality is web-based, but it needs to be presented within a native environment.

Whether you want to show simple HTML content, embed an entire web application, or create complex web interactions with JavaScript, Ark WebView gives you the tools you need. The package is highly flexible, allowing you to customize the behavior for specific platform requirements, such as Android and iOS, and take full advantage of native features.

With this library, developers can:

• Embed websites or HTML content directly in their React Native apps.
• Communicate between the web content and the native side via messaging.
• Handle events, such as page loads, errors, or form submissions.
• Take advantage of various advanced features like custom caching mechanisms, offline access, and platform-specific configuration.

Ark WebView is particularly useful for cases where you need:

1. A consistent user experience across different platforms: The library makes it easy to develop once and ensure consistency across both iOS and Android platforms.
2. Offline access to web content: Preloading and caching mechanisms ensure that users can access content even when offline, leading to better user experiences in areas with poor network connectivity.
3. Seamless integration of web and native components: The WebView can easily interact with native components using JavaScript, which allows developers to have a bridge between web-based interfaces and native modules.

In the following sections, we will discuss how to set up Ark WebView, use its features, and explore the full capabilities of integrating web-based content into your React Native applications effectively.

Project Setup

To integrate Ark WebView into your React Native project, follow these steps:

Prerequisites

Ensure that you have the following installed on your development machine:

• Node.js: Ark WebView requires Node.js to manage dependencies via npm or yarn. Make sure you have Node.js version 14 or above installed.
• React Native CLI: Ark WebView works with both the React Native CLI and Expo, but for full native integration, using the React Native CLI is recommended.
• Android Studio (for Android development) and Xcode (for iOS development): These are required to build and run your application on their respective platforms.

Installation

You can install Ark WebView in your project by using npm or yarn.

Using npm

npm install ark-webview

Using yarn

yarn add ark-webview

After installing the package, you need to link it to your native code. For newer versions of React Native (0.60 and above), this process is handled automatically.

Linking for Older Versions of React Native (below 0.60)

If you're using a version of React Native below 0.60, you will need to link the library manually:

react-native link ark-webview

Additional Setup for iOS

For iOS, you'll also need to install the CocoaPods dependencies. Navigate to the ios folder in your project and run the following command:

cd ios
pod install

This will ensure that all required native dependencies are installed and linked properly.

Additional Setup for Android

For Android, ensure that the minimum SDK version is set to 24 in your android/build.gradle file:

ext {
    minSdkVersion = 24
}

Ark WebView requires AndroidX, so make sure your project is configured to use AndroidX. You can do this by adding the following to your gradle.properties file:

android.useAndroidX=true
android.enableJetifier=true

Once you have completed these setup steps, you can start using Ark WebView in your React Native application.

Usage

To use Ark WebView in your React Native application, simply import the component and use it in your JSX code. Below is a basic example of how to get started:

import React from 'react';
import { View, StyleSheet } from 'react-native';
import ArkWebView from 'ark-webview';

const App = () => {
  return (
    <View style={styles.container}>
      <ArkWebView source={{ uri: 'https://example.com' }} />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;

In the above example, the Ark WebView component is used to load a webpage (https://example.com). You can pass various props to customize its behavior.

The source prop is used to define the content to be loaded by the WebView. It accepts either a URI (for loading web pages) or static HTML content.

Ark WebView also provides multiple customization options, events, and features that we will explore in subsequent sections.

Properties

Ark WebView comes with a wide range of properties that allow you to customize its behavior and appearance. Here, we list the commonly used properties along with their descriptions:

source

The source prop defines the content that the WebView should load. It can either be a URL or a static HTML content.

• Type: object
• Required: Yes

Example values for source

• URI: Load content from a web URL.

  source={{ uri: 'https://example.com' }}

• HTML: Load static HTML content.

  source={{ html: '<h1>Hello World</h1>' }}

enableJavaScript

A boolean that controls whether JavaScript should be enabled in the WebView.

• Type: boolean
• Required: No
• Default: true

onLoadStart

A function that is called when the WebView starts loading a page.

• Type: function
• Required: No

onLoadEnd Event

A function that is called when the WebView finishes loading a page.

• Type: function
• Required: No

onMessage

A function that handles messages sent from the web content to the native side via window.ReactNativeWebView.postMessage().

• Type: function
• Required: No

These are just a few of the properties available in Ark WebView. There are many more properties that allow you to control caching, user interactions, and platform-specific settings. In the next section, we will discuss the events that Ark WebView can handle and how to use them effectively.

Events

Ark WebView provides several events that allow developers to interact with the WebView at various points in the loading lifecycle or based on user interactions. These events help developers capture important moments and handle specific tasks accordingly.

onLoadStart Event

Triggered when the WebView starts loading a new page. This event is useful for showing loading indicators or performing actions at the start of a navigation.

• Type: function
• Parameter: event - An event object containing information about the load.

onLoadEnd

Called when the WebView has finished loading. This can be used to hide loading indicators or perform tasks after the content has loaded.

• Type: function
• Parameter: event - An event object containing information about the load.

onError

Fires when the WebView encounters an error while loading. This can be used to display error messages or retry mechanisms.

• Type: function
• Parameter: event - An event object containing details about the error.

onMessage Event

This event is triggered when the web content sends a message to the native side using window.ReactNativeWebView.postMessage(). It is commonly used for communication between the web content and the native application.

• Type: function
• Parameter: event - An event object containing the message data.

onLoadProgress

Fires continuously as the page loads, providing information about the loading progress. This event can be used to create progress bars or loading indicators.

• Type: function
• Parameter: event - An event object containing the progress value (between 0 and 1).

onHttpError

Called when the WebView receives an HTTP error. This can be used to handle non-200 HTTP responses.

• Type: function
• Parameter: event - An event object containing details about the HTTP error.

onNavigationChange

Triggered whenever there is a change in the navigation, such as a link click or a form submission. This event is useful for monitoring navigation events within the WebView.

• Type: function
• Parameter: event - An event object containing details about the navigation change.

These events are crucial for managing the lifecycle of the WebView and ensuring that the user experience is smooth and responsive. In the next section, we will explore the methods provided by Ark WebView for interacting with the component programmatically.

Methods

Ark WebView provides several methods that allow developers to interact with the WebView programmatically. These methods are useful for performing actions such as navigating within the web content, injecting JavaScript, or controlling the WebView's behavior.

reload()

Reloads the current page being viewed in the WebView. This method can be used when you want to refresh the content or retry loading after an error.

webViewRef.current.reload();

goBack()

Navigates back in the WebView's history. If there is no back history, this method does nothing.

webViewRef.current.goBack();

goForward()

Navigates forward in the WebView's history if there is a forward history available.

webViewRef.current.goForward();

injectJavaScript(script)

Injects JavaScript code into the WebView. This is useful for interacting with the content in the WebView dynamically.

• Parameter: script - A string containing the JavaScript code to be executed.

webViewRef.current.injectJavaScript('alert("Hello from React Native!");');

postMessage(message)

Sends a message to the WebView's content. This method can be used to communicate with the JavaScript running inside the WebView.

• Parameter: message - A string containing the message to be sent.

webViewRef.current.postMessage('Hello from React Native!');

These methods provide powerful ways to interact with and control the WebView, enabling developers to create rich and dynamic experiences. In the next section, we will discuss the various parameters that can be used with Ark WebView to customize its behavior even further.

Parameters

Ark WebView provides several parameters that allow developers to customize the behavior of the WebView, manage its state, and ensure seamless interaction with both web and native content.

source Parameter

Defines the content that the WebView should load. It can be a URL or static HTML content.

• Type: object
• Required: Yes

Possible values for source

• URI: Load content from a web URL.

  source={{ uri: 'https://example.com' }}

• HTML: Load static HTML content.

  source={{ html: '<h1>Hello World</h1>' }}

javaScriptEnabled

Enables or disables JavaScript execution within the WebView.

• Type: boolean
• Required: No
• Default: true

startInLoadingState

Displays a loading indicator while the WebView is loading its content. This is particularly useful when the loading time may vary.

• Type: boolean
• Required: No
• Default: false

onLoadStart

Callback function that is called when the WebView starts to load a page. It can be used to show loading indicators.

• Type: function
• Parameter: event - An event object containing load details.

onLoadEnd

Callback function that is called when the WebView finishes loading a page. It can be used to hide loading indicators.

• Type: function
• Parameter: event - An event object containing load details.

onError

Handles any errors that occur during the page load. Useful for showing error messages or retry options.

• Type: function
• Parameter: event - An event object containing error details.

onMessage

Handles messages sent from the web page to the native side using window.ReactNativeWebView.postMessage(). This is useful for communication between the WebView and native code.

• Type: function
• Parameter: event - An event object containing the message data.

injectedJavaScript

Allows you to inject JavaScript code into the WebView when the document finishes loading.

• Type: string
• Required: No

Example:

injectedJavaScript={`
  document.body.style.backgroundColor = 'lightblue';
`}

scalesPageToFit

Determines whether the webpage content should be scaled to fit the WebView's viewport. Useful for adjusting the presentation of pages on different screen sizes.

• Type: boolean
• Required: No
• Default: true

onNavigationStateChange

Callback function that is triggered whenever there is a change in the navigation state of the WebView, such as a URL change. Useful for tracking user navigation.

• Type: function
• Parameter: event - An event object containing navigation state details.

domStorageEnabled

Enables or disables DOM storage within the WebView, allowing the use of web storage such as localStorage and sessionStorage. Useful for storing local data within the web content.

• Type: boolean
• Required: No
• Default: true

cacheEnabled

Controls whether the WebView should cache its content.

• Type: boolean
• Required: No
• Default: true

mediaPlaybackRequiresUserAction

Determines whether HTML5 media playback requires a user action (e.g., a button press). Useful for preventing automatic media playback.

• Type: boolean
• Required: No
• Default: true (Android), false (iOS)

These parameters provide a flexible way to customize how Ark WebView behaves and how it interacts with the web content. By adjusting these parameters, developers can fine-tune the WebView to meet the specific needs of their application.