> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/react-native/webapp-integration/react-native-web-app-plugin-migration.md).

# Migration Guide

This guide explains how to migrate to the latest integration method of `@hackler/react-native-webview-plugin`.

{% hint style="info" %}
If you are using plugin 2.0.0, simply upgrade the plugin to 2.1.0 or later without code changes.\
Plugin 2.1.0 and above requires React Native 0.76.0 or later and `react-native-webview` 16.0.0 or later.
{% endhint %}

## Migration Steps

Refer to the tab that matches the integration method you are currently using.

{% tabs %}
{% tab title="Plugin 1.x" %}
This applies if you are integrating the bridge with `createHackleWebViewConfig()` and the `nativeConfig` prop.

{% stepper %}
{% step %}

### Update the React Native SDK to 4.0.0 or Later

Update `@hackler/react-native-sdk` to version 4.0.0 or later.
{% endstep %}

{% step %}

### Update the Plugin to 2.1.0 or Later

Update `@hackler/react-native-webview-plugin` to version 2.1.0 or later.
{% endstep %}

{% step %}

### Replace the `createHackleWebViewConfig` Call with `HackleWebViewBridge`

Remove the `createHackleWebViewConfig()` call and the `nativeConfig` prop, and wrap `WebView` with `HackleWebViewBridge`.

{% code title="Before (1.x)" %}

```tsx
import { createHackleWebViewConfig } from '@hackler/react-native-webview-plugin';

function MyWebView() {
  const hackleConfig = createHackleWebViewConfig({
    automaticScreenTracking: true,
    automaticEngagementTracking: true,
    automaticRouteTracking: true,
  });

  return (
    <WebView
      nativeConfig={hackleConfig}
      source={{ uri: currentUrl }}
    />
  );
}
```

{% endcode %}

{% code title="After (2.x)" %}

```tsx
import { HackleWebViewBridge } from '@hackler/react-native-webview-plugin';

function MyWebView() {
  return (
    <HackleWebViewBridge
      automaticScreenTracking
      automaticEngagementTracking
      automaticRouteTracking
    >
      <WebView source={{ uri: currentUrl }} />
    </HackleWebViewBridge>
  );
}
```

{% endcode %}

{% hint style="danger" %}
The child of `HackleWebViewBridge` must be exactly one `WebView`.
{% endhint %}

The option names and default values are the same as in 1.x. For options that need to be set to `false`, specify the value explicitly, like `automaticRouteTracking={false}`.
{% endstep %}

{% step %}

### Run a Clean Build and Verify the Integration

Make sure to run a clean build for the first build after updating the plugin.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Script method" %}
This applies if you are integrating with the `useHackleWebviewManager` hook and the JavaScript bridge code.

The [legacy WebApp integration method](https://docs.hackle.io/en/development-guide/react-native/webapp-integration/react-native-web-app-intergration-deprecated.md), which adds a bridge script to both the React Native and JavaScript code, has been deprecated. We recommend migrating to the plugin-based method.

{% hint style="info" %}
Key Changes

* On the React Native side, you can manage it conveniently by adding the webview plugin package.
* You no longer need to add a bridge script on the Javascript / React side.
* You can use the hooks provided by the Hackle SDK on the Javascript / React side without rewriting hooks.
  {% endhint %}

{% hint style="warning" %}
If you are using React Native SDK 3.x, install plugin 1.x. If you are using React Native SDK 4.x, install plugin 2.x.

You can migrate from the script method to the plugin method without upgrading the React Native SDK.
{% endhint %}

{% stepper %}
{% step %}

### Delete the Hackle-related Scripts and Code from React Native

Delete the previously provided `useHackleWebviewManager.ts`. It is recommended to delete it as conflicts may occur if you do not.

Also delete the Hackle-related code configured in the React Native WebView, listed below.

* `useHackleWebviewManager` hook
* `injectedJavaScriptBeforeContentLoaded` prop
* `onMessage` handler
  {% endstep %}

{% step %}

### Delete the JavaScript Bridge Code from the Web

Delete the previously provided JavaScript bridge code.

There is nothing else to do on the Web side other than deleting the bridge code. The website can keep using the Hackle JavaScript SDK as-is.
{% endstep %}

{% step %}

### Install the Plugin and Configure the Bridge

Refer to the [WebApp Integration](https://docs.hackle.io/en/development-guide/react-native/webapp-integration.md) guide to install the plugin that matches the React Native SDK version you are using and configure the bridge.

{% tabs %}
{% tab title="Plugin 2.x (React Native SDK 4.x)" %}
Wrap `WebView` with `HackleWebViewBridge`.

```tsx
import { WebView } from 'react-native-webview';
import { HackleWebViewBridge } from '@hackler/react-native-webview-plugin';

function MyWebView() {
  return (
    <HackleWebViewBridge>
      <WebView source={{ uri: currentUrl }} />
    </HackleWebViewBridge>
  );
}
```

{% endtab %}

{% tab title="Plugin 1.x (React Native SDK 3.x)" %}
Pass the config created with `createHackleWebViewConfig()` to the `nativeConfig` prop of `WebView`.

```tsx
import { WebView } from 'react-native-webview';
import { createHackleWebViewConfig } from '@hackler/react-native-webview-plugin';

function MyWebView() {
  const hackleConfig = createHackleWebViewConfig();

  return (
    <WebView
      nativeConfig={hackleConfig}
      source={{ uri: currentUrl }}
    />
  );
}
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Run a Clean Build and Verify the Integration

Make sure to run a clean build for the first build after installing the plugin.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Verifying the Migration Integration

After completing the above steps, access the Web from the React Native app and trigger an event.

Check the collected event in the Hackle Dashboard. If the SDK of the collected event is displayed as `react-native-sdk`, the integration is working correctly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/en/development-guide/react-native/webapp-integration/react-native-web-app-plugin-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
