# React

{% hint style="info" %}
The Hackle React SDK supports React version 16.8 and above.

The React SDK is built on top of the [JavaScript SDK](/en/development-guide/javascript.md).
{% endhint %}

## Add Dependency

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

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

```shell
npm install --save @hackler/react-sdk
```

{% endtab %}

{% tab title="YARN" %}

```shell
yarn add @hackler/react-sdk
```

{% endtab %}
{% endtabs %}

## SDK Initialization

You must initialize `HackleReactSDKClient` before using the SDK.

* `HackleReactSDKClient` is the class that provides methods for using SDK features.
* You can find the SDK Key in [SDK Integration Info](https://dashboard.hackle.io/config/sdk-setting) on the Hackle Dashboard.

During the application initialization phase, the SDK communicates with the Hackle server to sync data. This typically takes only a few milliseconds. Rendering begins immediately after synchronization is complete.

{% hint style="warning" %}
Note when using Google Tag Manager (GTM)

When integrating via GTM, you need to initialize the Hackle SDK and add it to the window object so that the SDK can be accessed from GTM.
{% endhint %}

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

```javascript
import { createInstance, HackleProvider } from "@hackler/react-sdk";

// YOUR_BROWSER_SDK_KEY 자리에 SDK 키를 넣습니다.
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")

ReactDOM.render(
  <HackleProvider hackleClient={hackleClient}>
    <YourApp />
  </HackleProvider>,
  document.getElementById('root')
);

// GTM 연동 시 추가 script
window.hackleClient = hackleClient
```

{% endtab %}

{% tab title="Next.js" %}

```javascript
import {createInstance, HackleProvider} from "@hackler/react-sdk";

// YOUR_BROWSER_SDK_KEY 자리에 SDK 키를 넣습니다.
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")

function MyApp({Component, pageProps}) {
  return (
    <HackleProvider hackleClient={hackleClient} supportSSR>
      <Component {...pageProps} />
    </HackleProvider>
  )
}

export default MyApp
```

{% endtab %}

{% tab title="Gatsby" %}

```javascript
import {createInstance, HackleProvider} from "@hackler/react-sdk";

// YOUR_BROWSER_SDK_KEY 자리에 SDK 키를 넣습니다.
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")

function App() {
  return (
    <HackleProvider hackleClient={hackleClient} supportSSR>
      <YourApp />
    </HackleProvider>
  )
}

export default App
```

{% endtab %}
{% endtabs %}

### SDK Initialization Config

You can initialize the SDK with configuration options.

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

```javascript
import { createInstance, HackleProvider } from "@hackler/react-sdk";

// 설정정보를 포함하여 초기화
const config = {
  debug: true
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

ReactDOM.render(
  <HackleProvider hackleClient={hackleClient}>
    <YourApp />
  </HackleProvider>,
  document.getElementById('root')
);
```

{% endtab %}

{% tab title="Next.js" %}

```javascript
import {createInstance, HackleProvider} from "@hackler/react-sdk";

// 설정정보를 포함하여 초기화
const config = {
  debug: true
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

function MyApp({Component, pageProps}) {
  return (
    <HackleProvider hackleClient={hackleClient} supportSSR>
      <Component {...pageProps} />
    </HackleProvider>
  )
}

export default MyApp
```

{% endtab %}
{% endtabs %}

#### All Configuration Options

<table data-full-width="false"><thead><tr><th width="213.57">Option</th><th width="295.49">Description</th><th width="125.81">Default</th><th width="108.1">Supported Version</th></tr></thead><tbody><tr><td><code>debug</code></td><td>Prints logs for all features to the console.</td><td><code>false</code></td><td>1.0.0+</td></tr><tr><td><code>pollingIntervalMillis</code></td><td>Periodically updates the configuration set in the Dashboard.<br>Minimum: 60000 (60 seconds)</td><td><code>-1</code></td><td>11.1.0+</td></tr><tr><td><code>exposureEventDedupIntervalMillis</code></td><td>Removes duplicate exposure events for the same A/B Test or Feature Flag distribution result triggered by the same user consecutively.<br>Minimum: 1000 (1 second)<br>Maximum: 3600000 (1 hour)</td><td><p><code>60000</code> (1 min / 11.23.0+)</p><p><code>-1</code> (no dedup / below 11.23.0)</p></td><td>11.1.0+</td></tr><tr><td><code>sessionTimeoutMillis</code> (deprecated)</td><td>Sets the session expiration time. Please use <code>sessionPolicy</code> instead.</td><td><code>1800000</code> (30 min)</td><td>11.8.0+</td></tr><tr><td><code>devTool</code></td><td>Enables <a href="/pages/I7utMnZm3ydkaK9KKklq">User Explorer</a>.</td><td><code>undefined</code></td><td>11.13.0+</td></tr><tr><td><code>autoOpenDevTool</code></td><td>Option to automatically show the User Explorer button.</td><td><code>false</code></td><td>11.13.0+</td></tr><tr><td><code>user</code></td><td>Injects a user at initialization time.</td><td><code>undefined</code></td><td>11.22.3+</td></tr><tr><td><code>sessionPolicy</code></td><td>Configures session persistence and expiration conditions.</td><td><p><code>ALWAYS_NEW_SESSION</code> ,</p><p><code>1800000</code></p></td><td>11.54.0+</td></tr><tr><td><code>optOutTracking</code></td><td>Whether opt-out is enabled.</td><td><code>false</code></td><td>11.54.0+</td></tr></tbody></table>

#### Session Policy Configuration

You can configure session persistence and expiration conditions using the session policy.

```javascript
import { createInstance, HackleProvider, HackleSessionPersistConditions } from "@hackler/react-sdk";

const config = {
    sessionPolicy: {
        timeoutMillis: 3600000,
        persistCondition: HackleSessionPersistConditions.NULL_TO_USER_ID
    }
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

ReactDOM.render(
  <HackleProvider hackleClient={hackleClient}>
    <YourApp />
  </HackleProvider>,
  document.getElementById('root')
);
```

#### Injecting User at Initialization

When `user` is set in config, you can initialize the SDK with user information included.

* If no user information is provided, the user information stored in cookies is used.
* If user information is provided, the user information stored in cookies is not used.
* If there is no user information in cookies, a user with the Hackle Device ID as the device id is used.

{% hint style="info" %}
You can freely update user information after SDK initialization using the user information setter functions.
{% endhint %}

{% hint style="warning" %}
The user information injected at initialization and the user information stored in cookies are not merged.

e.g.) If `userId: A` is stored in cookies and you inject `deviceId: B` at initialization, the user is set to `userId: null, deviceId: B`.
{% endhint %}

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

```javascript
import { createInstance, HackleProvider } from "@hackler/react-sdk";

const user = {
  userId: "LOGIN_ID",
  deviceId: "CUSTOM_DEVICE_ID"
};

const config = {
  debug: true,
  user: user
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

ReactDOM.render(
  <HackleProvider hackleClient={hackleClient}>
    <YourApp />
  </HackleProvider>,
  document.getElementById('root')
);
```

{% endtab %}

{% tab title="Next.js" %}

```javascript
import {createInstance, HackleProvider} from "@hackler/react-sdk";

const user = {
  userId: "LOGIN_ID",
  deviceId: "CUSTOM_DEVICE_ID"
};

const config = {
  debug: true,
  user: user
};

const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", config);

function MyApp({Component, pageProps}) {
  return (
    <HackleProvider hackleClient={hackleClient} supportSSR>
      <Component {...pageProps} />
    </HackleProvider>
  )
}

export default MyApp
```

{% endtab %}
{% endtabs %}

### Refreshing Dashboard Configuration

You can explicitly refresh the Dashboard configuration.

{% hint style="warning" %}
This function can only be called once every 60 seconds.
{% endhint %}

```javascript
hackleClient.fetch();
```


---

# Agent Instructions: 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:

```
GET https://docs.hackle.io/en/development-guide/react.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.