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 키를 복사하여 사용하세요.

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)에서 볼 수 있습니다. | false | 1.0.0+ |
pollingIntervalMillis | 대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다. 최솟값 : 30000 (30초) | -1 | 11.1.0+ |
exposureEventDedupIntervalMillis | 동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다. 최솟값: 1000 (1초) 최댓값: 3600000 (1시간) | -1 (중복제거 하지 않음) | 11.1.0+ |
auto_track_page_view 설정에 대하여
auto_track_page_view
설정과 무관하게 데이터 세부 분석 시 핵클에서 제공하는 속성은 계속 수집됩니다.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로 연동 된 분배 결과를 볼 수 있습니다.

단계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로 전송한 이벤트를 찾아 실시간 이벤트 수집현황을 확인해볼 수 있습니다.

Updated 18 days ago