This document provides steps for integrating your browser with Hackle via the Hackle SDK for Javascript platforms. SDK Integration is a must in order to use the functions we provide.

Follow these steps to quickly integrate the SDK:

Add Dependencies
Initialize the SDK
User Configuration
Event Tracking
A/B Testing
Feature Flags

1. Add Dependencies

Think of this step as importing our SDK into your codebase. To use our Hackle services add the following dependency code and import our SDK.

npm install --save @hackler/react-sdk

yarn add @hackler/react-sdk

2. Initialize the SDK

Once you have imported the dependencies, in order to start using the Hackle SDK you must initialize the HackleReactSDKClient. During this step, we get the information needed for SDK integration from the Hackle Server and store it in the SDK.

HackleReactSDKClient is a class that provides methods for using SDK functions.
Here you can pass the SDK key to the createInstance() method to instantiate it.

The SDK key can be found in the SDK integration in the dashboard of Hackle service. Copy and use the App or Browser SDK key.

During the application initialization phase, communication with the Hackle server is performed to synchronize data. Typically, this process takes only a few milliseconds. Once synchronization is complete, rendering occurs immediately.

🚧
Caution when using Google Tag Manager (GTM)
When integrating with GTM, after initializing the Hackle SDK, you need to add a window declaration to allow GTM to access the SDK.

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

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

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

Initialization Configuration

You can initialize the SDK with configuration options.

Debug Mode

You can activate the debug mode by setting the debug option to true. When the debug mode is enabled, logs for all features will be displayed in the console.

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

// Initialize with configuration, including the debug option
const config = {
  debug: true
};

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

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

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

// Initialize with configuration, including the debug option
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

Key	Description	Default Value	Supported Version
debug	Logs all features to the console.	false	1.0.0+
pollingIntervalMillis	Allows periodic updates of the information set in the dashboard. Minimum value: 30000 (30 seconds)	-1 (No periodic updates)	11.1.0+
exposureEventDedupIntervalMillis	Removes duplicate exposure events generated by the same user for consecutive A/B tests and feature flag distributions. Minimum value: 1000 (1 second) Maximum value: 3600000 (1 hour)	36000 (1 minute / 11.23.0+) -1 (No deduplication / below 11.23.0)	11.1.0+
auto_track_page_view	Automatically collects pageview events on page entry.	true	11.9.0+
devTool	Enables user exploration. Refer to the User Explorer documentation for more information.	undefined	11.13.0+
autoOpenDevTool	Option to automatically display the user exploration button.	false	11.13.0+

3. User Configuration

You can configure user information in the SDK.

Setting User ID

If the user logs in, you can call setUserId to set the ID of the logged-in user.

You only need to set it once when the user logs in.
For users who are already logged in, you can call it when retrieving their login information.

const userId = ... // ID of the logged-in user (e.g., member number, user ID)
hackleClient.setUserId(userId);

Setting User Properties

You can use user properties such as email address, location, age, and membership level. You can use the setUserProperty and setUserProperties methods to set user properties.

import { PropertyOperationsBuilder } from "@hackler/javascript-sdk"

const operations = new PropertyOperationsBuilder()
    .set("age", 42)
    .set("grade", "GOLD")
    .build();

hackleClient.updateUserProperties(operations);

Resetting User Configuration on Logout

If the user logs out, you can call resetUser to reset the previously set user information. The following information will be reset:

User ID
User properties

hackleClient.resetUser();

4. Event Tracking

You can send user actions as events. The sent events are used for A/B test analysis, data analysis, etc. For example, if a user performs a purchase action, you can send an event as follows:

// Collecting an event
hackleClient.track('purchase')

// Collecting an event with properties
const event = {
  key: "purchase",
  properties: {
    amount: 4200,
    pay_method: "CARD",
    is_discount: false,
    product_ids: [42, 43]
  }
}
hackleClient.track(event);

Viewing Sent Events

You can view the sent events in the Event Management menu on the dashboard. It typically takes around 60 seconds for the events to appear on the dashboard after being sent.

5. A/B Testing

You can distribute users into test groups and implement A/B testing by writing logic based on the assigned variations. By passing the experiment key to variation, you can receive the distribution result.

Experiment Key: A unique identifier for each A/B test. It is automatically assigned when creating an A/B test.

import {HackleExperiment, HackleVariation} from "@hackler/react-sdk";

function App() {
  return (
  // Determines the test group to be exposed to the user in an A/B test with variation key 42.
  // If unable to determine, it returns test group A.
  <HackleExperiment experimentKey={42}> 
      <HackleVariation variation={"A"}>
        <AwesomeFeature />
      </HackleVariation>
      <HackleVariation variation={"B"}>
        <SuperAwesomeFeature />
      </HackleVariation>
    </HackleExperiment>
  )
}

import {HackleExperiment} from "@hackler/react-sdk";

function App() {
  return (
  // Determines the test group to be exposed to the user in an A/B test with variation key 42.
  // If unable to determine, it returns test group A.
    <HackleExperiment experimentKey={42}>
      {(variation) => {
        switch (variation) { // logic for assigned group
          case "A":
            return <AwesomeFeature />
          case "B":
            return <SuperAwesomeFeature />
          default:
            return <AwesomeFeature />
        }
      }}
    </HackleExperiment>
  )
}

import {useLoadableVariation, useVariation} from "@hackler/react-sdk";

// general case
function App() {
  // Determines the test group to be exposed to the user in an A/B test with variation key 42.
  // If unable to determine, it returns test group A.
  const variation = useVariation(42)
  
// logic for assigned group
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

// SSR case
function App() {
  // Determines the test group to be exposed to the user in an A/B test with variation key 42.
  // If unable to determine, it returns test group A.
  const { isLoading, variation } = useLoadableVariation(42)

  // Hiding Components Before SDK Loading
  if (isLoading) return null

  // logic for assigned group
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

Viewing Distribution Results

You can check the distribution results in the Real-Time Status tab on the A/B test's details page. It typically takes around 60 seconds for the distribution results to appear on the dashboard after being distributed.

6. Feature Flags

Feature flags have two states: "on" and "off". You can implement feature flags by writing different logic based on these states. With Hackle, you can pass feature flag keys to the provided components and Hooks API to receive the "on" or "off" results.

Feature Flag Key: A unique identifier for each feature flag. It is automatically assigned when creating a feature flag.

import {HackleFeature} from "@hackler/react-sdk";

function App() {
  return (
  // Determines the user's status in a feature flag with key 42.
  // If unable to determine, it returns false (off state).
    <HackleFeature featureKey={42}>
      {(featureOn) =>
        featureOn ? (
          <SuperAwesomeFeature /> // On state logic
        ) : (
          <AwesomeFeature /> // Off state logic
        )
      }
    </HackleFeature>
  )
}

import {useFeature, useLoadableFeature} from "@hackler/react-sdk";

function App() {
  // Determines the user's status in a feature flag with key 42.
  // If unable to determine, it returns false (off state).
  const featureOn = useFeature(42)
  return (
    <>
    {
      featureOn ? (
        <SuperAwesomeFeature /> // On state logic
      ) : (
        <AwesomeFeature /> // Off state logic
      )
    }
    </>
  )
}

// SSR case
function App() {
  // Determines the user's status in a feature flag with key 42.
  // If unable to determine, it returns false (off state).
  const { isLoading, isOn } = useLoadableFeature(42)
  return (
    <>
    {
      isOn ? (
        <SuperAwesomeFeature /> // On state logic
      ) : (
        <AwesomeFeature /> // Off state logic
      )
    }
    </>
  )
}