> 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.md).

# React Native

{% hint style="info" %}
Supports React Native **0.75 and above** and React **18.2.0 and above**.\
Supports both the **Old and New Architecture**.\
On the New Architecture, the SDK runs through the Interop Layer.
{% endhint %}

<details>

<summary>Supported OS by SDK Version</summary>

Check the minimum supported OS for the Hackle React Native SDK version you use.

| Hackle React Native SDK Version | Android          | iOS          |
| ------------------------------- | ---------------- | ------------ |
| 4.0.0 and above                 | API 24 and above | 13 and above |
| 3.36.0 and above, below 4.0.0   | API 21 and above | 13 and above |
| 3.31.0 and above, below 3.36.0  | API 16 and above | 13 and above |
| Below 3.31.0                    | API 16 and above | 10 and above |

</details>

<details>

<summary>Verified React Native Versions</summary>

Android and iOS compatibility has been verified on the following React Native versions.

| React Native Version | Verified Platforms |
| -------------------- | ------------------ |
| 0.88.0               | Android, iOS       |
| 0.86.3               | Android, iOS       |
| 0.85.3               | Android, iOS       |
| 0.83.5               | Android, iOS       |
| 0.78.3               | Android, iOS       |
| 0.76.9               | Android, iOS       |

</details>

## Add Dependency

{% hint style="warning" %}
After installing or updating the SDK, you must rebuild the app for the changes to take effect.
{% endhint %}

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

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

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

{% endtab %}

{% tab title="yarn" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Expo is supported in React Native SDK 3.17.0 and above.\
`Expo Go` is not supported, so use `expo prebuild`.
{% endhint %}

### Platform Settings

{% tabs %}
{% tab title="iOS" %}
{% tabs %}
{% tab title="CocoaPods" %}
Run `pod install` in the `ios` directory.

```shell
cd ios
pod install
```

{% hint style="info" %}
The pod name is `HackleReactNativeSdk`.\
The Hackle iOS SDK is added as a Swift Package during `pod install`, so `Podfile.lock` does not contain a `Hackle` pod.
{% endhint %}

{% hint style="warning" %}
If Xcode shows a `The project "Pods" is damaged` error after `pod install` on React Native 0.86 or below, see [Troubleshooting](https://docs.hackle.io/en/development-guide/react-native/react-native-troubleshooting.md).
{% endhint %}
{% endtab %}

{% tab title="Swift Package Manager" %}
{% hint style="info" %}
Supported in React Native 0.87 and above.
{% endhint %}

Run the command below in the `ios` directory.\
The React Native SDK and the Hackle iOS SDK it uses are added as Swift Packages.

```shell
cd ios
npx react-native spm add
```

When switching from CocoaPods to Swift Package Manager, add the `--deintegrate` option.

```shell
cd ios
npx react-native spm add --deintegrate
```

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

{% tab title="Android" %}
{% hint style="info" %}
Add the code below manually only for React Native SDK 3.25.0 and below.
{% endhint %}

Add `registerActivityLifecycleCallbacks` to the `onCreate` function of your `Application` class.\
If there is no [Application](https://developer.android.com/reference/android/app/Application) class, create one and register it in `AndroidManifest.xml`.

{% tabs %}
{% tab title="Java" %}
{% code title="MyApplication.java" %}

```java
import android.app.Application;
import io.hackle.android.HackleApp;

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    ...
    HackleApp.registerActivityLifecycleCallbacks(this);
    ...
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Kotlin" %}
{% code title="MyApplication.kt" %}

```kotlin
import android.app.Application
import io.hackle.android.Hackle
import io.hackle.android.registerActivityLifecycleCallbacks

class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    ...
    Hackle.registerActivityLifecycleCallbacks(this)
    ...
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## SDK Initialization

To use the SDK, you must pass the SDK Key to `createInstance()` to create a `HackleReactNativeSDKClient` and pass it to the `HackleProvider` that wraps your React application.

* You can find the SDK Key in [SDK Integration Info](https://dashboard.hackle.io/config/sdk-setting) on the Hackle Dashboard.

At initialization, the SDK fetches necessary data from the Hackle server and stores it. This typically takes only a few milliseconds. Rendering begins immediately after synchronization is complete.

{% hint style="warning" %}
**Do not call SDK features before initialization is complete.**

Initialization runs asynchronously and is only complete once synchronization with the Hackle server has finished. If you call SDK features before initialization is complete, the SDK may not work correctly or events may be lost.

* **A/B Tests, Feature Flags, and Remote Config do not work correctly.** Instead of the actual assignment result, they return the default group (`A`), off (`false`), or the default value passed in the call. (Reason: `SDK_NOT_READY`)
* **Exposure events are not recorded.** Even if a user was actually part of the experiment, they are not counted as exposed, which can distort the experiment results.
* **Events may be lost.** Events collected with `track()` may not be sent.
* **Events may carry an inaccurate session ID.**
* **In-App Messages are not displayed.** Trigger conditions are evaluated at the moment an event is collected, and events collected before initialization is complete are not re-evaluated afterwards.

Make sure to call SDK features only after initialization is complete.
{% endhint %}

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

// Replace YOUR_APP_SDK_KEY with your SDK Key.
const hackleClient = createInstance("YOUR_APP_SDK_KEY");

const App = () => {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <YourApp />
    </HackleProvider>
  );
};
```

### Injecting User at Initialization

{% hint style="info" %}
This feature is supported in React Native SDK version 3.31.0 and above.
{% endhint %}

You can initialize the SDK with user information included.

* If no user information is provided, the user information stored in local storage is used.
* If user information is provided, the user information stored in local storage is not used.
* If no user is injected and there is no user information stored in local storage, 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 local storage are not merged.

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

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

const config = {
  debug: true
};

const user = {
  userId: "YOUR_USER_ID"
}

const hackleClient = createInstance("YOUR_APP_SDK_KEY", config, user);

const App = () => {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <YourApp />
    </HackleProvider>
  );
};
```

### SDK Initialization Config

You can initialize the SDK with configuration options.

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

const config = {
  debug: true
};

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

const App = () => {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <YourApp />
    </HackleProvider>
  );
};
```

<table data-full-width="false"><thead><tr><th width="224.4684375">Option</th><th width="295.49">Description</th><th width="125.81">Default</th><th width="99.209375">Supported Version</th></tr></thead><tbody><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><code>-1</code> (no dedup)</td><td>3.3.1+</td></tr><tr><td><code>debug</code></td><td>Prints logs for all features to the console and sends events immediately.</td><td><code>false</code></td><td>3.4.1+</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> (no periodic update)</td><td>3.6.0+</td></tr><tr><td><code>automaticAppLifecycleTracking</code></td><td>Whether to enable automatic app start/end tracking</td><td><code>true</code></td><td>3.30.0+</td></tr><tr><td><code>automaticScreenTracking</code></td><td>Whether to enable automatic screen tracking</td><td><code>true</code></td><td>3.30.0+</td></tr><tr><td><code>sessionPolicy</code></td><td>Configures session persistence and expiration conditions.</td><td><p><code>persistCondition: alwaysNewSession</code>,</p><p><code>timeoutMillis: 1800000</code> (30 min)</p></td><td>3.32.0+</td></tr><tr><td><code>optOutTracking</code></td><td>Whether opt-out is enabled. When enabled, all event sending is stopped.</td><td><code>false</code></td><td>3.32.0+</td></tr><tr><td><code>evaluationMode</code></td><td>Configures the evaluation mode.</td><td><code>"local"</code></td><td>4.0.0+</td></tr><tr><td><code>manualScreenViewDedupEnabled</code></td><td>Whether to deduplicate the screen view event when <code>setCurrentScreen</code> is called with the same screen as the current one. If set to <code>false</code>, <code>$page_view</code> is fired every time the same screen is set again.</td><td><code>true</code></td><td>4.1.0+</td></tr><tr><td><code>delegate</code></td><td>Registers a <code>HackleDelegate</code> that handles Push Message and In-App Message links directly in the app. For details, see <a href="https://docs.hackle.io/en/development-guide/react-native/react-native-deeplink/react-native-deeplink-delegate.md">Handle Links with HackleDelegate</a>.</td><td>None</td><td>4.2.0+</td></tr><tr><td><code>universalLinkDomainCheckEnabled</code></td><td>(iOS) Whether to check that an http/https link belongs to a domain registered in Associated Domains before passing it to the app. Not applied when <code>delegate</code> is registered.</td><td><code>false</code></td><td>4.2.0+</td></tr></tbody></table>

#### Evaluation Mode Configuration

You can choose whether the SDK performs evaluation itself or fetches results that the Hackle server has already evaluated.\
If not configured, the default value `"local"` (local evaluation) is used.

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

const config = {
  evaluationMode: "remote"
};

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

const App = () => {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <YourApp />
    </HackleProvider>
  );
};
```

{% hint style="warning" %}
When you use remote evaluation, user information is not stored on the device. Any user information already stored from local evaluation is deleted.

For the differences between the two modes and how to choose one, see the [Evaluation Mode](https://docs.hackle.io/en/development-guide/sdk/evaluation-mode.md) document.
{% endhint %}

#### Session Policy Configuration

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

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

const config = {
    sessionPolicy: {
        timeoutMillis: 3600000,
        persistCondition: 'nullToUserId'
    }
};

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

const App = () => {
  return (
    <HackleProvider hackleClient={hackleClient}>
      <YourApp />
    </HackleProvider>
  );
};
```

### 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
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.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.
