SDK 연동

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

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

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://cdn.jsdelivr.net/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모든 기능에 대한 로그를 콘솔에 출력합니다.false1.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페이지 진입 시 페이지뷰 이벤트를 자동 수집합니다.true11.9.0+
devTool사용자 탐색을 사용할 수 있도록 합니다.
자세한 설명은 사용자 탐색 문서를 참고해주세요.
undefined11.13.0+
autoOpenDevTool사용자 탐색 버튼이 자동으로 나타나도록 하는 옵션입니다.false11.13.0+
sameSiteCookie핵클 쿠키에 sameSite 플래그를 설정하고 쿠키 개인정보 보호 정책을 결정합니다.Lax11.20.0+
secureCookietrue 로 설정하시면 핵클 쿠키에 Secure 플래그를 설정합니다.false11.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 기능
  }
});