Go to Docs (KR)Sign in to Dashboard

SDK Integration

Suggest Edits

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

  • Step 1: Add Dependencies
  • Step 2: Initialize the SDK
  • Step3 : A/B test, Feature Flag
  • Step4 : Send customer event

Step 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

Step 2: Initialize the SDK

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

You need to pass the SDK key to createInstance() to create a HackleReactSDKClient and then pass this to the HackleProvider which wraps the React application.

Communication for data synchronization with the Hackle server is carried out in the application initialization stage. Typically, this takes only a few milliseconds. Rendering begins immediately after the synchronization is complete.

🚧

Precautions when using Google Tag Manager (GTM)

When integrating with Hackle using GTM, it is necessary to initialize the Hackle SDK and add a window declaration to allow GTM to access the SDK.

📘

Additional settings for Next.js / Gatsby

If you are using Next.js/Gatsby environment, click the appropriate code tab in the code below for each environment.

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

// Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")

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

// Additional script for Google Tag Manager integration
window.hackleClient = hackleClient

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

function MyApp({Component, pageProps}) {
    let hackleClient
    if (process.browser) {
        // Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
        hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")
    }

    return (
        hackleClient ? <HackleProvider hackleClient={hackleClient}>
            <Component {...pageProps} />
        </HackleProvider> : <Component {...pageProps} />
    )
}

export default MyApp

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

function App() {
    const isSSR = typeof window === "undefined"
    let hackleClient
    if (!isSSR) {
        // Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
        hackleClient = createInstance("YOUR_BROWSER_SDK_KEY")
    }

    return (
        hackleClient ? <HackleProvider hackleClient={hackleClient}>
            <YourApp />
        </HackleProvider> : <YourApp />
    )
}

export default App

Find SDK Key

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

📘

(Optional) You can add different configuration settings to the createInstance() method.

By adding different settings, you will be able to customize some of the functions of SDK. Please refer to Configuration for more information.

Configuration

During the SDK Initialization stage, you can customize and add different configuration settings to customizable keys. Refer to the example below. 

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

// Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
// Set your desired values for debug, auto_track_page_view. 
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", { debug: false, auto_track_page_view: true })

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

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

function MyApp({Component, pageProps}) {
    let hackleClient
    if (process.browser) {
        // Enter the SDK Key in the YOUR_BROWSER_SDK_KEY.
        // Set your desired values for debug, auto_track_page_view. 
        hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", { debug: false, auto_track_page_view: true })
    }

    return (
        hackleClient ? <HackleProvider hackleClient={hackleClient}>
            <Component {...pageProps} />
        </HackleProvider> : <Component {...pageProps} />
    )
}

export default MyApp

The configuration keys above have the following functions.

Configuration KeyFunction DescriptionDefault ValueSupported Version
debugDebug logs for all functions can be viewed from the the console.false1.0.0+
pollingIntervalMillisYou can periodically update the information you set in the dashboard.

Min value : 30000 (30s)		-1
(Do not update periodically)		11.1.0+
exposureEventDedupIntervalMillisRemoves consecutive exposure events for the same A/B test, feature flag from the same user

Min value: 1000 (1s)
Max value: 3600000 (1h)		-1
(Do not deduplication)		11.1.0+
auto_track_page_viewAuto track $page_view event when a page is loaded.true11.9.0+

Step3. A/B test, Feature Flag

A/B test

Before running an A/B test, you must distribute users to the test group and create the logic corresponding to each test group.
User distribution can then be carried out through the hackle SDK.

📘

Test Group

The test group refers to the existing one (control group) and improvement one (treatment group) to be tested, and there may be more than one treatment group. You can configure in the dashboard and for information on how to manage test groups, visit see the document A/B setting.

useVariation or useLoadableVariation

You can use the components provided by Hackle or use the Hooks API to distribute users to specific test and receive distribution results. The distribution must pass the test key.

Input Experiment key and user identifier to distribute users and receive results. You can implement logic by test group afterwards.

The experiment key is a unique number for each A/B test and can be found on the dashboard within the Hackle service.

The example code below inputs the Experiment key 42.

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

function App() {
  return (
// Determine which test group to expose to the user in the A/B test with the test key of 42.
// Returns test group A if the test group can not be decided.
    <HackleExperiment experimentKey={42}> 
      <HackleVariation variation={"A"}>
        <AwesomeFeature />
      </HackleVariation>
      <HackleVariation variation={"B"}>
        <SuperAwesomeFeature />
      </HackleVariation>
    </HackleExperiment>
  )
}

function App() {
  return (
// Determine which test group to expose to the user in the A/B test with the test key of 42.
// Returns test group A if the test group can not be decided.
    <HackleExperiment experimentKey={42}>
      {(variation) => {
        switch (variation) { // Logic for Assigned Group
          case "A":
            return <AwesomeFeature />
          case "B":
            return <SuperAwesomeFeature />
          default:
            return <AwesomeFeature />
        }
      }}
    </HackleExperiment>
  )
}

// General case
function App() {
  // Determine which test group to expose to the user in the A/B test with the test key of 42.
  // Returns test group A if the test group can not be decided.
  const variation = useVariation(42)
  
  // Logic for Assigned Group
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

// SSR usecase
function App() {
   // Determine which test group to expose to the user in the A/B test with the test key of 42.
  // Returns test group A if the test group can not be decided.
  const { isLoading, variation } = useLoadableVariation(42)

  // Do not display Component befroe SDK Loading
  if (isLoading) return null

  // Logic for Assigned Group
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

Feature Flag

The feature flags are in the ON state and the OFF state. Different features will be set for each state.
When a user accesses a function with a feature flag applied, the user must be able to receive an on or off state. This status determination can be made via the hackle SDK.

useFeature or useLoadableFeature

Input Feature key to the 'isFeatureOn()' method to receive status results for the user. Implement logic based on subsequent states.

The Feature key is a unique number for each Feature Flag and can be found on the dashboard within the Hackle service.

The example code below input the Feature key 42.

function App() {
  return (
// Determine which status to expose to the user in the flag with the flag key of 42.
// Returns off statep if the state can not be decided.  
    <Feature featureKey={42}>
      {(featureOn) =>
        featureOn ? (
          <SuperAwesomeFeature />     // logic for ON
        ) : (
          <AwesomeFeature />     // logic for OFF 
        )
      }
    </Feature>
  )
}

function App() {
// Determine which status to expose to the user in the flag with the flag key of 42.
// Returns off statep if the state can not be decided. 
  const featureOn = useFeature(42)
  return (
    <>
    {
      featureOn ? (
        <SuperAwesomeFeature /> // logic for ON
      ) : (
        <AwesomeFeature />     // logic for OFF 
      )
    }
    </>
  )
}

// SSR Case
function App() {
// Determine which status to expose to the user in the flag with the flag key of 42.
// Returns off statep if the state can not be decided. 
  const { isLoading, isOn } = useLoadableFeature(42)
  return (
    <>
    {
      isOn ? (
        <SuperAwesomeFeature />     // logic for ON
      ) : (
        <AwesomeFeature />     // logic for OFF 
      )
    }
    </>
  )
}

Check the exposure results

On the [Dashboard Left Menu Bar] - [A/B Test] or [Feature Flag] page, browse to the detail page for the list of exposed A/B tests or feature flags, and click the Real-Time Exposure tab in the middle of the page to view the distribution results from integrated SDK.

Step 4. Send User Events

The Hackle SDK provides the ability to send user events to the hackle.
At each point where changes in user behavior occur, this feature provides meaningful data about user behavior and allows you to analyze user behavior from those collected data.

track

User events can be sent by passing event keys and user identifiers to the 'track()' method. If necessary, when sending user events, numeric values can be put in 'value' to be sent together.

  • You can only put the number type for 'value'

Example

Suppose you have defined an event key called 'purchase' to collect events when the user presses the buy button. At this time, you may want to collect the purchase price together. In this case, you can also receive the purchase amount in 'value'.

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

/* Example 1: Send event key only */
const track = useTrack()
const event = { key: "purchase" }

<Button onClick={() => track(event)}>purchase</Button>

/* Example 2: Send event keys and numeric values together */
const track = useTrack()
const event = {
  key: "purchase",
  value: 13200
}

<Button onClick={() => track(event)}>purchase</Button>

Example 1 only sends event keys; Example 2 shows a case of putting the purchase amount in 'value' to collect the purchase amount together.

Validate the sending of user events

Verify that user events sent by SDK are being collected successfully.
You can check the real-time event collection status by finding events sent to the SDK in the [left menu bar of dashboards] - [Event Management].

Updated 3 days ago