1. 의존성 추가

npm install --save @hackler/react-sdk

yarn add @hackler/react-sdk

2. SDK 초기화

SDK를 사용하기 위해서 반드시 HackleReactSDKClient 를 초기화 해야 합니다. 인스턴스를 초기화 하기 위해 SDK 키가 필요합니다.

HackleReactSDKClient는 SDK의 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.
SDK 키는 핵클 서비스의 대시보드 안에 위치한 SDK 연동 정보에서 확인하실 수 있습니다.

어플리케이션 초기화 단계에 핵클 서버와 데이터 동기화를 위한 통신을 진행합니다. 일반적으로 이 시간은 수 밀리 초에 불과합니다. 동기화가 완료되면 즉시 렌더링이 진행됩니다.

🚧
Google Tag Manager (GTM) 사용시 주의 사항
GTM을 사용하여 연동을 진행할 경우, Hackle SDK 초기화를 하고, SDK를 GTM 에서 접근할 수 있도록 window에 추가 선언이 필요합니다.

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

초기화 설정정보

설정정보를 포함하여 SDK를 초기화 할 수 있습니다.

디버그 모드

debug 옵션을 true 로 설정하여 활성화 합니다. 디버그 모드를 활성화 시키면 모든 기능에 대한 로그가 콘솔에 출력됩니다.

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

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

모든 설정옵션

key	기능	기본값	지원 버전
debug	모든 기능에 대한 디버그(debug) 로그를 콘솔(console)에서 볼 수 있습니다.	false	1.0.0+
pollingIntervalMillis	대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다. 최솟값 : 30000 (30초)	-1	11.1.0+
exposureEventDedupIntervalMillis	동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다. 최솟값: 1000 (1초) 최댓값: 3600000 (1시간)	36000(1분 / 11.23.0 버전 이상) -1 (중복제거 하지 않음 / 11.23.0 버전 미만)	11.1.0+
auto_track_page_view	페이지 진입 시 $page_view 이벤트를 자동 수집합니다.	true	11.9.0+
devTool	사용자 탐색을 사용할 수 있도록 합니다. 자세한 설명은 사용자 탐색 문서를 참고해주세요.	undefined	11.13.0+
autoOpenDevTool	사용자 탐색 버튼이 자동으로 나타나도록 하는 옵션입니다.	false	11.13.0+

3. 사용자 설정

사용자 정보를 SDK에 설정할 수 있습니다.

사용자 ID 설정

사용자가 로그인한 경우, setUserId 를 호출해서 로그인한 사용자의 ID를 설정할 수 있습니다.

로그인 시 한번만 설정하면 됩니다.
이미 로그인이 되어있는 사용자의 경우에는 로그인한 정보를 가지고 오는 시점에 호출하면 됩니다.

const userId = ... // 로그인한 사용자의 ID (회원번호, 멤버 ID 등)
hackleClient.setUserId(userId);

사용자 속성 설정

이메일주소, 위치, 나이, 회원등급과 같은 정보를 사용자 속성으로 사용할 수 있습니다. setUserProperty, setUserProperties 를 호출하여 사용자 속성을 설정할 수 있습니다.

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

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

hackleClient.updateUserProperties(operations);

사용자 로그아웃 시 재설정

사용자가 로그아웃 한 경우 resetUser를 호출해서 기존에 설정한 사용자 정보를 리셋할 수 있습니다. 아래 정보가 리셋됩니다.

사용자 ID
사용자 속성

hackleClient.resetUser();

4. 이벤트 전송

사용자가 수행하는 행동을 이벤트로 전송할 수 있습니다. 전송된 이벤트는 A/B 테스트 분석, 데이터 분석 등에 사용됩니다. 예를들어, 사용자가 구매라는 행동을 했다면 아래와 같이 이벤트를 전송할 수 있습니다.

// 이벤트 수집
hackleClient.track('purchase')

// 이벤트를 속성과 함께 수집
const event = {
  key: "purchase",
  properties: {
    amount: 4200,
    pay_method: "CARD",
    is_discount: false,
    product_ids: [42, 43]
  }
}
hackleClient.track(event);

전송한 이벤트 확인하기

대시보드 이벤트관리 메뉴에서 전송한 이벤트를 확인할 수 있습니다. 이벤트 전송 후 대시보드에 표시되기까지 일반적으로 ~60초가 걸립니다.

5. A/B 테스트

사용자를 테스트 그룹으로 분배하고 분배된 결과에 해당하는 로직을 작성하여 A/B 테스트를 구현합니다.
핵클이 제공하는 컴포넌트를 사용하거나 Hooks API를 사용하여 사용자를 특정 그룹으로 분배하고 분배 결과를 전달 받을 수 있습니다. 분배 시에는 실험 키를 전달해야 합니다.

실험키: 각 A/B 테스트별로 갖게 되는 고유 번호입니다. A/B 테스트를 생성하면 자동으로 발급됩니다.

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

function App() {
  return (
    // 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
    // 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
    <HackleExperiment experimentKey={42}> 
      <HackleVariation variation={"A"}>
        <AwesomeFeature />
      </HackleVariation>
      <HackleVariation variation={"B"}>
        <SuperAwesomeFeature />
      </HackleVariation>
    </HackleExperiment>
  )
}

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

function App() {
  return (
    // 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
    // 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
    <HackleExperiment experimentKey={42}>
      {(variation) => {
        switch (variation) { // 할당받은 그룹에 대한 로직
          case "A":
            return <AwesomeFeature />
          case "B":
            return <SuperAwesomeFeature />
          default:
            return <AwesomeFeature />
        }
      }}
    </HackleExperiment>
  )
}

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

// 일반적인 경우
function App() {
  // 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
  // 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
  const variation = useVariation(42)
  
  // 할당받은 그룹에 대한 로직
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

// SSR 사용 시
function App() {
  // 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
  // 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
  const { isLoading, variation } = useLoadableVariation(42)

  // SDK Loading 전 컴포넌트 비노출
  if (isLoading) return null

  // 할당받은 그룹에 대한 로직
  if (variation === "A") return <AwesomeFeature />
  if (variation === "B") return <SuperAwesomeFeature />
  return <AwesomeFeature />
}

분배 결과 확인하기

대시보드 A/B 테스트의 상세페이지의 실시간 노출 현황 탭에서 분배된 결과를 확인할 수 있습니다. 분배 후 대시보드에 표시되기까지 일반적으로 ~60초가 걸립니다.

6. 기능 플래그

기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 상태에 따라 다른 로직을 작성하여 기능 플래그를 구현합니다.
핵클이 제공하는 컴포넌트, Hooks API에 기능플래그 키를 전달하여 on/off 결과를 전달 받을 수 있습니다

기능플래그키: 각 기능플래그별로 갖게 되는 고유 번호입니다. 기능플래그를 생성하면 자동으로 발급됩니다.

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

function App() {
  return (
    // 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
    // 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
    <HackleFeature featureKey={42}>
      {(featureOn) =>
        featureOn ? (
          <SuperAwesomeFeature /> // 켜짐 상태일 때의 기능
        ) : (
          <AwesomeFeature /> // 꺼짐 상태일 때의 기능
        )
      }
    </HackleFeature>
  )
}

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

function App() {
  // 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
  // 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
  const featureOn = useFeature(42)
  return (
    <>
    {
      featureOn ? (
        <SuperAwesomeFeature /> // 켜짐 상태일 때의 기능
      ) : (
        <AwesomeFeature /> // 꺼짐 상태일 때의 기능
      )
    }
    </>
  )
}

// SSR 사용 시
function App() {
  // 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
  // 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
  const { isLoading, isOn } = useLoadableFeature(42)
  return (
    <>
    {
      isOn ? (
        <SuperAwesomeFeature /> // 켜짐 상태일 때의 기능
      ) : (
        <AwesomeFeature /> // 꺼짐 상태일 때의 기능
      )
    }
    </>
  )
}