> 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/development-guide/react-native/webapp-integration.md).

# 웹앱 연동

{% hint style="info" %}
React Native SDK 3.28.0 버전 이상, JavaScript SDK 11.51.0 버전 이상에서 지원하는 기능입니다.

웹앱에 대해서는 [문서](/development-guide/faq/web-app-intergration.md)를 참고해주세요.
{% endhint %}

{% hint style="warning" %}
이미 웹앱 연동중이셨나요?

React Native와 Javascript 코드를 모두 수정하는 스크립트 방식을 사용중이셨거나, 플러그인 1.x에서 2.x로 올리시는 경우 [마이그레이션 가이드](/development-guide/react-native/webapp-integration/react-native-web-app-plugin-migration.md)를 참고해주세요.
{% endhint %}

`WebView`를 통해 자사 웹사이트를 랜더링하는 경우, 아래 설정을 통해 웹사이트에 포함된 핵클 JavaScript SDK를 웹사이트 코드 변경없이 핵클 React Native SDK 기능과 동일하게 사용할 수 있습니다.

웹앱 연동을 한 경우 웹뷰 내에서 발생하는 모든 이벤트는 React Native SDK를 통해 수집됩니다.

React Native SDK 연동을 완료한 뒤, 다음 단계를 진행하세요.

{% stepper %}
{% step %}

### 플러그인 추가

{% hint style="warning" %}
사용중인 React Native SDK 버전에 맞는 플러그인 버전을 설치해야 합니다.

* React Native SDK **4.x** → 플러그인 **2.x**
* React Native SDK **3.x** → 플러그인 **1.x**

플러그인 2.x는 React Native SDK 3.x에서 동작하지 않습니다.
{% endhint %}

<details>

<summary>플러그인 버전 별 요구사항</summary>

<table><thead><tr><th width="177.421875">플러그인 버전</th><th width="220">React Native SDK</th><th width="180">react-native-webview</th><th>React Native</th></tr></thead><tbody><tr><td>2.0.0 이상</td><td>4.0.0 이상 5.0.0 미만</td><td>13.13.0 이상</td><td>0.74.0 이상</td></tr><tr><td>1.2.0</td><td>3.30.0 이상 4.0.0 미만</td><td>13.13.0 이상</td><td>제한 없음</td></tr><tr><td>1.1.0 이상, 1.2.0 미만</td><td>3.30.0 이상 4.0.0 미만</td><td>11.0.0 이상</td><td>제한 없음</td></tr><tr><td>1.0.0 이상, 1.1.0 미만</td><td>3.28.0 이상 4.0.0 미만</td><td>11.0.0 이상</td><td>제한 없음</td></tr></tbody></table>

플러그인 2.0.0 이상 버전은 Android API 24 이상, iOS 13 이상을 요구합니다.

React Native 0.81 이상 버전을 사용하면서 플러그인 1.x를 유지해야 하는 경우 플러그인 1.1.1 이상 버전을 사용하세요.

</details>

[![](https://img.shields.io/npm/v/%40hackler%2Freact-native-webview-plugin)](https://www.npmjs.com/package/@hackler/react-native-webview-plugin)

{% tabs %}
{% tab title="npm" %}

```shell
# React Native SDK 4.x
npm install --save @hackler/react-native-webview-plugin@^2.0.0

# React Native SDK 3.x
npm install --save @hackler/react-native-webview-plugin@^1.2.0
```

{% endtab %}

{% tab title="yarn" %}

```shell
# React Native SDK 4.x
yarn add @hackler/react-native-webview-plugin@^2.0.0

# React Native SDK 3.x
yarn add @hackler/react-native-webview-plugin@^1.2.0
```

{% endtab %}
{% endtabs %}

#### iOS

```shell
cd ios
pod install
```

{% hint style="warning" %}
플러그인 설치 후 최초 빌드를 할 때는 반드시 클린 빌드를 실행해주세요.
{% endhint %}
{% endstep %}

{% step %}

### WebView 브릿지 주입

{% tabs %}
{% tab title="플러그인 2.x (React Native SDK 4.x)" %}
`WebView`를 `HackleWebViewBridge`로 감싸주세요. `HackleWebViewBridge`가 웹뷰에 브릿지를 설치하고, 웹사이트의 핵클 JavaScript SDK가 보낸 요청을 React Native SDK로 전달합니다.

```tsx
import { WebView } from 'react-native-webview';
import { createInstance, HackleProvider } from "@hackler/react-native-sdk";
import { HackleWebViewBridge } from '@hackler/react-native-webview-plugin';

// 웹앱 브릿지 주입 전 반드시 핵클 SDK 초기화가 완료되어야 합니다.
const hackleClient = createInstance("YOUR_APP_SDK_KEY");

function MyWebView() {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <HackleWebViewBridge>
        // 하위요소는 react-native-webview 객체 하나만 사용해주세요.
        <WebView source={{ uri: currentUrl }} />
      </HackleWebViewBridge>
    </HackleProvider>
  );
}
```

{% hint style="danger" %}
**`HackleWebViewBridge` 하위요소는 반드시 `WebView` 하나여야 합니다.**
{% endhint %}
{% endtab %}

{% tab title="플러그인 1.x (React Native SDK 3.x)" %}
react native webview의 `nativeConfig` props에 HackleWebViewConfig를 추가해주세요.

`createHackleWebViewConfig()` 함수를 이용하여 config 를 생성할 수 있습니다.

```tsx
import { WebView } from 'react-native-webview';
import { createInstance, HackleProvider } from "@hackler/react-native-sdk";
import { createHackleWebViewConfig } from '@hackler/react-native-webview-plugin';

// 웹앱 브릿지 주입 전 반드시 핵클 SDK 초기화가 완료되어야 합니다.
const hackleClient = createInstance("YOUR_APP_SDK_KEY");

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

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

{% hint style="info" %}
React Native SDK를 4.x로 올릴 때는 플러그인도 2.x로 함께 올려야 합니다. [마이그레이션 가이드](/development-guide/react-native/webapp-integration/react-native-web-app-plugin-migration.md)를 참고해주세요.
{% endhint %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
해당 기능을 사용하기 위해서는 **JavaScript 웹페이지에서 동일한 App SDK 키를 사용**해야 합니다.
{% endhint %}
{% endstep %}

{% step %}

### 웹뷰에서 발생하는 자동 수집 이벤트 연동

웹뷰 내 웹사이트에서 발생하는 `$page_view`와 `$engagement`는 비활성화 상태입니다.

웹뷰 브릿지를 설정할 때 자동 수집 이벤트를 각각 활성화할 수 있습니다.

{% tabs %}
{% tab title="플러그인 2.x (React Native SDK 4.x)" %}
`HackleWebViewBridge`에 prop을 전달하여 설정합니다.

```tsx
import { WebView } from 'react-native-webview';
import { createInstance, HackleProvider } from "@hackler/react-native-sdk";
import { HackleWebViewBridge } from '@hackler/react-native-webview-plugin';

// 웹앱 브릿지 주입 전 반드시 핵클 SDK 초기화가 완료되어야 합니다.
const hackleClient = createInstance("YOUR_APP_SDK_KEY");

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

값을 `false`로 설정할 때는 `automaticRouteTracking={false}` 와 같이 값을 명시해주세요.
{% endtab %}

{% tab title="플러그인 1.x (React Native SDK 3.x)" %}
`createHackleWebViewConfig()`에 `HackleWebViewConfig`를 전달하여 설정합니다.

```tsx
import { WebView } from 'react-native-webview';
import { createInstance, HackleProvider } from "@hackler/react-native-sdk";
import { createHackleWebViewConfig } from '@hackler/react-native-webview-plugin';

// 웹앱 브릿지 주입 전 반드시 핵클 SDK 초기화가 완료되어야 합니다.
const hackleClient = createInstance("YOUR_APP_SDK_KEY");

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

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

{% endtab %}
{% endtabs %}

#### 설정 옵션

설정 옵션의 이름과 기본값은 플러그인 1.x와 2.x가 동일합니다.

<table data-full-width="false"><thead><tr><th width="260.6715625">설정</th><th width="295.49">기능</th><th width="86.32953125">기본값</th><th width="100.2484375">지원 버전</th></tr></thead><tbody><tr><td><code>automaticScreenTracking</code></td><td><code>$page_view</code> 수집 여부</td><td><code>false</code></td><td>1.0.0 +</td></tr><tr><td><code>automaticEngagementTracking</code></td><td><code>$engagement</code> 수집 여부</td><td><code>false</code></td><td>1.0.0 +</td></tr><tr><td><code>automaticRouteTracking</code></td><td>페이지 정보 자동 수집 여부</td><td><code>true</code></td><td>1.1.0 +</td></tr></tbody></table>

{% hint style="info" %}
웹페이지 이동 시 수집 방식을 선택하세요.

* **자동 수집**: `automaticScreenTracking`, `automaticEngagementTracking`, `automaticRouteTracking`를 모두 `true`로 설정하세요.
* [**수동 수집**](/development-guide/javascript/event-tracking/js-track-page.md): `automaticScreenTracking`과 `automaticEngagementTracking`는 `true`로 설정하세요. `automaticRouteTracking`는 `false`로 설정하세요.
  {% endhint %}
  {% endstep %}
  {% endstepper %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/development-guide/react-native/webapp-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.