SDK 연동

몇 가지 단계를 거쳐 빠르게 SDK 연동을 시작해보세요.

단계1. SDK 의존성 추가
단계2. SDK 초기화
단계3. A/B 테스트, 기능플래그
단계4. 사용자 이벤트 전송

1 단계 : 의존성 추가

npm install --save @hackler/react-sdk
yarn add @hackler/react-sdk

2 단계 : SDK 초기화

createInstance()에 SDK 키를 전달하여 HackleReactSDKClient를 생성하고 React 어플리케이션을 감싸는 HackleProvider에 전달해야 합니다.

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

📘

Next.js / Gatsby 등 SSR 사용 시 추가 설정

Next.js / Gatsby 환경 연동 시 아래 코드에서 각 환경에 맞는 코드탭을 클릭하시면 편리하게 연동하실 수 있습니다.

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

📘

createInstance() 메소드에 설정을 추가할 수 있습니다.

보다 자세한 내용은 아래 2-1단계: 설정 추가를 참고해주세요.

SDK 키 확인하기

SDK 키는 [대시보드 왼쪽 메뉴] - [SDK 연동 정보] 메뉴를 클릭하면 JDK 종류/환경 별 SDK 키를 확인할 수 있습니다.
App 또는 Browser SDK 키를 복사하여 사용하세요.

2556

SDK 키 확인하기

HackleClient가 인스턴스화 되면 핵클 서버로부터 필요한 정보들을 가져와서 SDK에 저장합니다.
이 작업은 비동기로 실행되며 onReady() 메소드를 통해 SDK 사용 준비가 완료된 것을 알 수 있습니다.

hackleClient.onReady(() => {
  // SDK ready to use
});

2-1 단계: 설정 추가

SDK 초기화 시 몇 가지 설정을 추가할 수 있습니다. 다음의 예시를 참고하세요.

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

// YOUR_BROWSER_SDK_KEY 자리에 SDK 키를 넣습니다.
// 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";

// YOUR_BROWSER_SDK_KEY 자리에 SDK 키를 넣습니다.
// debug, auto_track_page_view 값을 설정할 수 있습니다.
const hackleClient = createInstance("YOUR_BROWSER_SDK_KEY", { debug: false, auto_track_page_view: true })
        
function MyApp({Component, pageProps}) {
    return (
                <HackleProvider hackleClient={hackleClient} supportSSR>
            <Component {...pageProps} />
        </HackleProvider>
    )
}

export default MyApp

설정 값의 의미는 다음과 같습니다.

key기능기본값지원 버전
debug모든 기능에 대한 디버그(debug) 로그를 콘솔(console)에서 볼 수 있습니다.false1.0.0+
pollingIntervalMillis대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다.

최솟값 : 30000 (30초)
-111.1.0+
exposureEventDedupIntervalMillis동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다.

최솟값: 1000 (1초)
최댓값: 3600000 (1시간)
-1 (중복제거 하지 않음)11.1.0+

🚧

auto_track_page_view 설정에 대하여

  1. auto_track_page_view 설정과 무관하게 데이터 세부 분석 시 핵클에서 제공하는 속성은 계속 수집됩니다.
  2. auto_track_page_view를 false로 변경할 경우 사용자 퍼널 분석 시 URL을 사용할 수 없습니다.

단계3. A/B 테스트, 기능플래그

A/B 테스트

A/B 테스트를 진행할 때, 테스트 그룹을 대상으로 사용자를 분배하고 각 테스트 그룹에 해당하는 로직을 작성해야 합니다.
이 때 사용자 분배를 핵클 SDK를 통해 진행할 수 있습니다.

📘

테스트 그룹

테스트 그룹은 테스트 대상이 되는 기존안(대조군)과 개선안(실험군)을 의미하며, 개선안은 1개 이상일 수 있습니다. 대시보드에서 설정 가능하며, 테스트 그룹을 관리하는 방법에 대해서는 A/B 테스트 설정 문서를 참고하시기 바랍니다.

useVariation or useLoadableVariation

핵클이 제공하는 컴포넌트를 사용하거나 Hooks API를 사용하여 사용자를 특정 그룹으로 분배하고 분배 결과를 전달받을 수 있습니다. 분배 시에는 실험 키를 전달해야 합니다.
실험 키는 각 A/B 테스트별로 갖게 되는 고유 번호이며, 핵클 서비스 내의 대시보드에서 확인할 수 있습니다.
아래 예제 코드의 경우 실험 키 42를 전달하고 있습니다.

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>
  )
}
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>
  )
}
// 일반적인 경우
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 />
}

기능플래그

기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 각 상태에 따라 다른 기능을 설정하게 됩니다.
기능 플래그를 적용한 기능에 어떤 사용자가 접근할 경우 켜짐 혹은 꺼짐 상태를 받을 수 있어야 합니다. 이 상태 결정을 핵클 SDK를 통해 진행할 수 있습니다.

useFeature or useLoadableFeature

isFeatureOn() 메소드에 기능 키를 전달하면 사용자에 대한 상태 결과를 전달받을 수 있습니다. 이후 상태에 따른 로직을 구현합니다.
기능 키는 각 기능 플래그별로 갖게 되는 고유 번호이며 핵클 서비스 내의 대시보드에서 확인하실 수 있습니다.
아래 예제 코드에서는 기능 키 42를 전달하고 있습니다.

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

분배결과 확인하기

[대시보드 왼쪽 메뉴] - [A/B 테스트 또는 기능플래그] 화면에서 노출되는 A/B테스트 또는 기능플래그 리스트 중 연동한 대상을 찾아 상세 페이지로 이동 한 후 화면 중간에 [실시간 노출 현황] 탭을 클릭하면 SDK로 연동 된 분배 결과를 볼 수 있습니다.

2464

단계4. 이벤트 전송

핵클 SDK는 사용자 이벤트를 핵클로 전송하는 기능을 제공합니다.
사용자 행동의 변화가 일어나는 지점마다 이 기능을 활용하면 사용자 행동에 대한 유의미한 데이터를 얻을 수 있으며, 그렇게 모인 데이터를 통해 사용자 행동 분석을 할 수 있습니다.

track

track() 메소드에 이벤트 키사용자 식별자를 전달하여 사용자 이벤트를 전송할 수 있습니다. 필요한 경우 사용자 이벤트 전송 시 숫자 값을 value에 넣어 함께 전송할 수 있습니다.

  • value는 number 타입만 넣을 수 있습니다.

예시

사용자가 구매하기 버튼을 눌렀을 때 이벤트를 수집하기 위해 purchase 라는 이벤트 키를 정의했다고 가정합니다. 이 때 구매 금액을 같이 수집하고 싶을 수 있습니다. 이런 경우 value에 구매 금액을 함께 받을 수 있습니다.

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

/* 예시 1: 이벤트 키만 전송 */
const track = useTrack()
const event = { key: "purchase" }

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

/* 예시 2: 이벤트 키와 숫자 값을 함께 전송 */
const track = useTrack()
const event = {
  key: "purchase",
  value: 13200
}

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

예시 1에서는 이벤트 키만 전송하고 있으며, 예시 2에서는 구매 금액을 함께 수집하기 위해 value에 구매 금액을 넣은 사례를 보여주고 있습니다.

사용자 이벤트 전송 확인하기

SDK 에서 전송한 사용자 이벤트가 정상적으로 수집되고 있는지 확인해보세요.
[대시보드 왼쪽 메뉴] - [이벤트 관리] 메뉴에서 SDK로 전송한 이벤트를 찾아 실시간 이벤트 수집현황을 확인해볼 수 있습니다.

2466