React

The Hackle React SDK supports React version 16.8 and above.

The React SDK is built on top of the JavaScript SDK.

Add Dependency

NPM

npm install --save @hackler/react-sdk

YARN

yarn add @hackler/react-sdk

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

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.

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.

React

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

Next.js

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

Gatsby

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

SDK Initialization Config

You can initialize the SDK with configuration options.

React

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

Next.js

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

All Configuration Options

Option	Description	Default	Supported Version
debug	Prints logs for all features to the console.	false	1.0.0+
pollingIntervalMillis	Periodically updates the configuration set in the Dashboard. Minimum: 60000 (60 seconds)	-1	11.1.0+
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)	60000 (1 min / 11.23.0+) -1 (no dedup / below 11.23.0)	11.1.0+
sessionTimeoutMillis (deprecated)	Sets the session expiration time. Please use sessionPolicy instead.	1800000 (30 min)	11.8.0+
devTool	Enables User Explorer.	undefined	11.13.0+
autoOpenDevTool	Option to automatically show the User Explorer button.	false	11.13.0+
user	Injects a user at initialization time.	undefined	11.22.3+
sessionPolicy	Configures session persistence and expiration conditions.	ALWAYS_NEW_SESSION , 1800000	11.54.0+
optOutTracking	Whether opt-out is enabled.	false	11.54.0+
evaluationMode	Configures the evaluation mode.	local	12.0.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-sdk";

const config = {
    evaluationMode: "remote"
};

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

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

When you use remote evaluation, user information is not stored in the browser. If user information was already stored while using local evaluation, it is deleted.

For the differences between the two modes and how to choose between them, refer to the Evaluation Mode documentation.

Session Policy Configuration

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

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.

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

As of React SDK 12.0.0, the user prop of HackleProvider is applied only when its value changes, and when applied it replaces the existing user information instead of merging it.

If you use both the user prop and the user information setter functions (setUser, setUserId, setDeviceId, and so on), user information can be lost. Use only one of the two approaches. If you only need the initial user information, we recommend using user in config instead of the user prop.

React

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

Next.js

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

Refreshing Dashboard Configuration

You can explicitly refresh the Dashboard configuration.

This function can only be called once every 60 seconds.

await hackleClient.fetch();

As of React SDK 12.0.0, hooks such as useVariation are re-evaluated based on the latest configuration after fetch() completes.