React Native

The Hackle React Native SDK supports React 17.0.1 and above, and React Native 0.64.1 and above.

The React Native SDK is built on top of the Android SDK and iOS SDK, and supports the following OS versions.

• Android API 24 (7.0 NOUGAT) and above

• iOS 13 and above

OS Support by React Native SDK Version

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

Add Dependency

After installing or updating the SDK, you must rebuild the app for the integration changes to take effect.

npm

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

yarn

yarn add @hackler/react-native-sdk

iOS

cd ios
pod install

Adding Dependency with Expo

Expo is supported in React Native SDK version 3.17.0 and above.

The React Native SDK does not support the Expo Go environment. Please use expo prebuild.

npm

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

yarn

yarn add @hackler/react-native-sdk

When using Expo, you do not need to run link or pod install.

Android Configuration

Only enter the code below manually for React Native SDK version 3.25.0 and below.

Starting from SDK version 3.26.0, the following configuration is applied automatically. Skip this step and proceed to the next.

Refer to the code below and add registerActivityLifecycleCallbacks.

If there is no Application class created, create a new one and register it in AndroidManifest.xml.

Add the following code to your Application class under the onCreate function.

Java

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

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

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

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

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.

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

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

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

Injecting User at Initialization

This feature is supported in React Native SDK version 3.31.0 and above.

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 in local storage, a user with the Hackle Device ID as the device id is used.

You can freely update user information after SDK initialization using the user information setter functions.

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.

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.

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>
  );
};

Option	Description	Default	Supported Version
exposureEventDedupIntervalMillis	Removes duplicate exposure events for the same A/B Test or Feature Flag distribution result triggered by the same user consecutively. Minimum: 1000 (1 second) Maximum: 3600000 (1 hour)	-1 (no dedup)	3.3.1+
debug	Prints logs for all features to the console and sends events immediately.	false	3.4.1+
pollingIntervalMillis	Periodically updates the configuration set in the Dashboard. Minimum: 60000 (60 seconds)	-1 (no periodic update)	3.6.0+
automaticAppLifecycleTracking	Whether to enable automatic app start/end tracking	true	3.30.0+
automaticScreenTracking	Whether to enable automatic screen tracking	true	3.30.0+
sessionPolicy	Configures session persistence and expiration conditions.	persistCondition: alwaysNewSession, timeoutMillis: 1800000 (30 min)	3.32.0+
optOutTracking	Whether opt-out is enabled. When enabled, all event sending is stopped.	false	3.32.0+
evaluationMode	Configures the evaluation mode.	"local"	4.0.0+
sessionTimeoutMillis (deprecated)	Sets the session expiration time. Please use sessionPolicy instead.	1800000 (30 min)	3.11.0+

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.

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>
  );
};

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

Session Policy Configuration

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

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.

This function can only be called once every 60 seconds.

hackleClient.fetch();