SDK 연동
몇 가지 단계를 거쳐 SDK 연동을 시작해보세요.
- 의존성 추가
- SDK 초기화
- 사용자 설정
- 이벤트 전송
- A/B 테스트
- 기능 플래그
Google Tag Manager를 통한 연동 방법은 GTM 문서를 확인해주세요.
1. 의존성 추가
npm install --save @hackler/javascript-sdk
yarn add @hackler/javascript-sdk
<!-- HTML의 경우 의존성 추가 작업이 필요하지 않습니다 -->
2. SDK 초기화
SDK를 사용하기 위해서 반드시 HackleClient 를 초기화 해야 합니다. 인스턴스를 초기화 하기 위해 SDK 키가 필요합니다.
HackleClient
는 SDK의 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.- SDK 키는 핵클 서비스의 대시보드 안에 위치한 SDK 연동 정보에서 확인하실 수 있습니다.
import * as Hackle from "@hackler/javascript-sdk";
// YOUR_BROWSER_SDK_KEY로 초기화
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY");
<!-- 기존 코드 head 안에 추가 -->
<script src="https://cdn2.hackle.io/npm/@hackler/[email protected]/lib/index.browser.umd.min.js"></script>
<script>
// YOUR_BROWSER_SDK_KEY로 초기화
window.hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY");
</script>
초기화 설정정보
설정정보를 포함하여 SDK를 초기화 할 수 있습니다.
디버그 모드
debug
옵션을 true
로 설정하여 활성화 합니다. 디버그 모드를 활성화 시키면 모든 기능에 대한 로그가 콘솔에 출력됩니다.
const config = {
debug: true
};
// 설정정보를 포함하여 초기화
const hackleClient = Hackle.createInstance("YOUR_BROWSER_SDK_KEY", config);
모든 설정옵션
키 | 기능 | 기본값 | 지원 버전 |
---|---|---|---|
debug | 모든 기능에 대한 로그를 콘솔에 출력합니다. | 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+ |
sessionTimeoutMillis | 세션만료 시간을 설정합니다. | 1800000 (30분) | 11.8.0+ |
devTool | 사용자 탐색을 사용할 수 있도록 합니다. 자세한 설명은 사용자 탐색 문서를 참고해주세요. | undefined | 11.13.0+ |
autoOpenDevTool | 사용자 탐색 버튼이 자동으로 나타나도록 하는 옵션입니다. | false | 11.13.0+ |
sameSiteCookie | 핵클 쿠키에 sameSite 플래그를 설정하고 쿠키 개인정보 보호 정책을 결정합니다. | Lax | 11.20.0+ |
secureCookie | true 로 설정하시면 핵클 쿠키에 Secure 플래그를 설정합니다. | false | 11.20.0+ |
초기화 완료
초기화가 시작되면 핵클 서버로부터 필요한 정보들을 가져와서 SDK에 저장합니다. 이 작업은 비동기로 실행되며 onReady
를 통해 SDK 사용 준비가 완료된 것을 알 수 있습니다. 주로 초기화가 완료된 이후 실행되어야 하는 기능(A/B 테스트, 기능플래그)을 위해 사용됩니다.
hackleClient.onReady(() => {
// SDK ready to use
});
대시보드 설정 정보 갱신
대시보드 설정 정보를 명시적으로 갱신 할 수 있습니다.
hackleClient.fetch();
핵클 JavaScript SDK 11.29.0 이상 버전에서 지원하는 기능입니다.
해당 함수는 60초에 한번 제한적으로 호출할 수 있습니다.
3. 사용자 설정
사용자 정보를 SDK에 설정할 수 있습니다.
사용자 ID 설정
사용자가 로그인한 경우, setUserId
를 호출해서 로그인한 사용자의 ID를 설정할 수 있습니다.
- 로그인 시 한번만 설정하면 됩니다.
- 이미 로그인이 되어있는 사용자의 경우에는 로그인한 정보를 가지고 오는 시점에 호출하면 됩니다.
const userId = ... // 로그인한 사용자의 ID (회원번호, 멤버 ID 등)
hackleClient.setUserId(userId);
사용자 속성 설정
이메일주소, 위치, 나이, 회원등급과 같은 정보를 사용자 속성으로 사용할 수 있습니다.
import { PropertyOperationsBuilder } from "@hackler/javascript-sdk"
const operations = new PropertyOperationsBuilder()
.set("age", 42)
.set("grade", "GOLD")
.build();
hackleClient.updateUserProperties(operations);
<script>
const operations = new Hackle.PropertyOperationsBuilder()
.set("age", 42)
.set("grade", "GOLD")
.build();
hackleClient.updateUserProperties(operations);
</script>
사용자 로그아웃 시 재설정
사용자가 로그아웃 한 경우 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 테스트를 구현합니다. variation
에 실험키를 전달하여 호출하면 분배결과를 리턴받을 수 있습니다.
실험키: 각 A/B 테스트별로 갖게 되는 고유 번호입니다. A/B 테스트를 생성하면 자동으로 발급됩니다.
// SDK가 준비된 이후에 실행이 되어야합니다. onReady로 감싸는 것을 잊지 마세요.
hackleClient.onReady(function() {
// 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
// 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
const variation = hackleClient.variation(42);
// 할당받은 그룹에 대한 로직
if (variation === "A") {
// 그룹 A 로직
} else if (variation === "B") {
// 그룹 B 로직
}
});
분배 결과 확인하기
대시보드 A/B 테스트의 상세페이지의 실시간 노출 현황 탭에서 분배된 결과를 확인할 수 있습니다. 분배 후 대시보드에 표시되기까지 일반적으로 ~60초가 걸립니다.
6. 기능 플래그
기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 상태에 따라 다른 로직을 작성하여 기능 플래그를 구현합니다. isFeatureOn
에 기능플래그키를 전달하여 호출하면 on/off 여부를 리턴받을 수 있습니다.
기능플래그키: 각 기능플래그별로 갖게 되는 고유 번호입니다. 기능플래그를 생성하면 자동으로 발급됩니다.
// SDK가 준비된 이후에 실행이 되어야합니다. onReady로 감싸는 것을 잊지 마세요.
hackleClient.onReady(function() {
// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
// 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
const isOn = hackleClient.isFeatureOn(42);
// 상태 별 로직
if (isOn) {
// ON 기능
} else {
// OFF 기능
}
});
Updated 29 days ago