React

Hackle React SDK는 React 16.8 이상 버전을 지원합니다.

React SDK는 JavaScript SDK 를 기반으로 동작합니다.

의존성 추가

NPM

npm install --save @hackler/react-sdk

YARN

yarn add @hackler/react-sdk

SDK 초기화

SDK를 사용하기 위해서 반드시 HackleReactSDKClient 를 초기화 해야 합니다.

• HackleReactSDKClient는 SDK의 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.

• SDK 키는 핵클 서비스의 대시보드 안에 위치한 SDK 연동 정보 에서 확인하실 수 있습니다.

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

Google Tag Manager (GTM) 사용시 주의 사항

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

React

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

Next.js

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

Gatsby

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를 초기화 할 수 있습니다.

React

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

Next.js

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

모든 설정옵션

설정	기능	기본값	지원 버전
debug	모든 기능에 대한 로그를 콘솔에 출력합니다.	false	1.0.0+
pollingIntervalMillis	대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다. 최솟값 : 60000 (60초)	-1	11.1.0+
exposureEventDedupIntervalMillis	동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다. 최솟값: 1000 (1초) 최댓값: 3600000 (1시간)	60000(1분 / 11.23.0 버전 이상) -1(중복제거 하지 않음 / 11.23.0 버전 미만)	11.1.0+
sessionTimeoutMillis (deprecated)	세션만료 시간을 설정합니다. sessionPolicy를 사용해 주세요.	1800000 (30분)	11.8.0+
devTool	사용자 탐색을 사용할 수 있도록 합니다.	undefined	11.13.0+
autoOpenDevTool	사용자 탐색 버튼이 자동으로 나타나도록 하는 옵션입니다.	false	11.13.0+
user	초기화 시점에 사용자를 주입합니다.	undefined	11.22.3+
sessionPolicy	세션 유지 조건과 만료 조건을 설정합니다.	ALWAYS_NEW_SESSION , 1800000	11.54.0+
optOutTracking	옵트아웃 활성화 여부.	false	11.54.0+
evaluationMode	분배 방식을 설정합니다.	local	12.0.0+

세션 정책 설정

세션 정책을 설정하여 세션의 유지 조건과 만료 조건을 제어할 수 있습니다.

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

const config = {
    sessionPolicy: {
        timeoutMillis: 3600000,
        persistCondition: HackleSessionPersistConditions.NULL_TO_USER_ID
    }
};

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

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

초기화 시 사용자 주입

config에 user를 설정한 경우 유저 정보를 포함하여 SDK를 초기화 할 수 있습니다.

• 유저 정보를 포함하지 않으면 쿠키에 저장된 유저 정보를 사용합니다.

• 유저 정보를 포함하는 경우 쿠키에 저장된 유저 정보는 사용하지 않습니다.

• 쿠키에 저장된 유저 정보가 없는 경우 Hackle Device ID를 device id로 가지고 유저를 사용합니다.

유저 정보는 SDK 초기화 이후에도 유저 정보 설정 함수를 통해 자유롭게 수정 할 수 있습니다.

초기화 시 주입한 유저 정보와 쿠키에 저장된 유저 정보는 병합하지 않습니다.

ex) 쿠키에 userId: A 가 저장된 상태에서 초기화 시 deviceId: B 를 주입하는 경우, userId: null, deviceId: B인 유저로 설정됩니다.

React SDK 12.0.0 부터 HackleProvider의 user prop은 값이 변경된 경우에만 적용되며, 적용 시 기존 사용자 정보를 병합하지 않고 대체합니다.

user prop 방식과 사용자 정보 변경 함수(setUser, setUserId, setDeviceId 등) 방식을 함께 사용하면 사용자 정보가 유실될 수 있습니다. 두 방식 중 하나만 사용해주세요. 초기 사용자 정보만 필요한 경우 user prop 대신 config의 user 사용을 권장합니다.

React

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

const user = {
  userId: "LOGIN_ID",
  deviceId: "CUSTOM_DEVICE_ID"
};

const config = {
  debug: true,
  user: user
};

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

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

Next.js

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

const user = {
  userId: "LOGIN_ID",
  deviceId: "CUSTOM_DEVICE_ID"
};

const config = {
  debug: true,
  user: user
};

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

function MyApp({Component, pageProps}) {
  return (
    <HackleProvider hackleClient={hackleClient} supportSSR>
      <Component {...pageProps} />
    </HackleProvider>
  )
}

export default MyApp

대시보드 설정 정보 갱신

대시보드 설정 정보를 명시적으로 갱신 할 수 있습니다.

해당 함수는 60초에 한번 제한적으로 호출할 수 있습니다.

await hackleClient.fetch();

React SDK 12.0.0 부터 fetch() 완료 후 훅(useVariation 등)이 최신 설정 정보 기준으로 다시 평가됩니다.