SDK 연동
몇 가지 단계를 거쳐 빠르게 SDK 연동을 시작해보세요.
- 단계1. SDK 의존성 추가
- 단계2. SDK 초기화
- 단계3. 사용자 이벤트 전송
- 단계4. A/B 테스트, 기능플래그
- 단계5. 종료
단계 1. SDK 의존성 추가
SDK 의존성을 추가합니다.
repositories {
mavenCentral()
}
dependencies {
implementation 'io.hackle:hackle-server-sdk:2.24.0'
}
단계 2. SDK 초기화
HackleClient는 SDK 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.
SDK 를 사용하기 위해서는 HackleClinet 초기화가 필요합니다.
인스턴스화
SDK 키를 전달하여 HackleClient
를 인스턴스화 합니다.
HackleClient
는 필요한 정보들을 얻기 위해 백그라운드 작업으로 핵클 서버와 주기적으로 동기화합니다.
HackleClient는 반드시 싱글톤이어야 합니다.
HackleClient
는 호출 쓰레드를 블록킹 하지 않고 바로 테스트 그룹을 분배하기 위해 내부적으로 상태를 관리합니다. 이를 위해 추가적인 리소스를 사용합니다. 모든 요청에 대해 새로운 클라이언트를 인스턴스화 하지 않고 어플리케이션 생명주기 동안 싱글 인스턴스로 관리되어야 합니다.
import io.hackle.sdk.HackleClient
import io.hackle.sdk.HackleClients
// YOUR_SERVER_SDK_KEY 자리에 SDK 키를 넣습니다.
HackleClient hackleClient = HackleClients.create(YOUR_SERVER_SDK_KEY);
import io.hackle.sdk.HackleClient
import io.hackle.sdk.HackleClients
// YOUR_SERVER_SDK_KEY 자리에 SDK 키를 넣습니다.
val hackleClient = Hackle.client(YOUR_SERVER_SDK_KEY)
SDK 키는 단계 1에서 가입한 핵클 대시보드 안에서 확인할 수 있습니다. SDK 연동 정보 에서 SDK 종류/환경 별 SDK 키를 확인 후 Server
SDK 키를 복사하여 사용하세요.
단계 3. 이벤트 전송
사용자가 수행하는 행동을 이벤트로 전송할 수 있습니다. 전송된 이벤트는 A/B 테스트 분석, 데이터 분석 등에 사용됩니다.
예를들어, 사용자가 구매라는 행동을 했다면 아래와 같이 이벤트를 전송할 수 있습니다.
import io.hackle.sdk.HackleClient;
import io.hackle.sdk.common.Event;
import io.hackle.sdk.common.User;
// 'ae2182e0'라는 디바이스 식별자 가진 사용자가 발생시킨 'purchase'라는 이벤트를 전송
User user = User.builder()
.deviceId("ae2182e0")
.build();
Event event = Event.builder("purchase")
.property("pay_method", "CARD")
.property("discount_amount", 800)
.property("is_discount", true)
.build();
hackleClient.track(event, user);
import io.hackle.sdk.HackleClient
import io.hackle.sdk.common.Event
import io.hackle.sdk.common.User
// 'ae2182e0'라는 디바이스 식별자 가진 사용자가 발생시킨 'purchase'라는 이벤트를 전송
val user = User.builder()
.deviceId("ae2182e0")
.build()
val event = Event.builder("purchase")
.property("pay_method", "CARD")
.property("discount_amount", 800)
.property("is_discount", true)
.build()
hackleClient.track(event, user)
사용자 이벤트 전송 확인하기
SDK 에서 전송한 사용자 이벤트가 정상적으로 수집되고 있는지 확인해보세요.
핵클 대시보드 안의 [왼쪽 메뉴바] - [이벤트 관리] 메뉴에서 SDK로 전송한 이벤트를 찾아 실시간 이벤트 수집현황을 확인해볼 수 있습니다.
단계 4. A/B 테스트, 기능플래그
A/B 테스트
A/B 테스트를 진행할 때, 테스트 그룹을 대상으로 사용자를 분배하고 각 테스트 그룹에 해당하는 로직을 작성해야 합니다. 이 때 사용자 분배를 핵클 SDK를 통해 진행할 수 있습니다.
테스트 그룹
테스트 그룹은 테스트 대상이 되는 기존안(대조군)과 개선안(실험군)을 의미하며, 개선안은 1개 이상일 수 있습니다. 대시보드에서 설정 가능하며, 테스트 그룹을 관리하는 방법에 대해서는 A/B 테스트 설정 문서를 참고하시기 바랍니다.
variation
variation()
메소드에 실험 키와 사용자 식별자를 전달하면 사용자를 분배하고 결과를 전달받을 수 있습니다. 이후 테스트 그룹 별 로직을 구현합니다.
실험 키는 각 A/B 테스트별로 갖게 되는 고유 번호이며, 핵클 서비스 내의 대시보드에서 확인할 수 있습니다.
아래 예제 코드에서는 실험 키 42를 전달하고 있으며, 사용자 식별자는 "ae2182e0" 입니다. 테스트 그룹은 A와 B 두 개가 존재합니다.
import io.hackle.sdk.HackleClient;
import io.hackle.sdk.common.User;
import io.hackle.sdk.common.Variation;
// 실험 키가 42인 A/B 테스트에서
// "ae2182e0"라는 디바이스 식별자를 가진 사용자에게 노출할 테스트 그룹을 결정합니다.
// 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
User user = User.builder()
.deviceId("ae2182e0")
.build();
Variation variation = hackleClient.variation(42, user);
// 할당받은 그룹에 대한 로직
if (variation == Variation.A) {
// 그룹 A 로직
} else if (variation == Variation.B) {
// 그룹 B 로직
}
import io.hackle.sdk.HackleClient
import io.hackle.sdk.common.User
import io.hackle.sdk.common.Variation
// 실험 키가 42인 A/B 테스트에서
// "ae2182e0"라는 식별자를 가진 사용자에게 노출할 테스트 그룹을 결정합니다.
// 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
val user = User.builder()
.deviceId("ae2182e0")
.build()
val variation: Variation = hackleClient.variation(42, user)
// 할당받은 그룹에 대한 로직
if (variation == Variation.A) {
// 그룹 A 로직
} else if (variation == Variation.B) {
// 그룹 B 로직
}
기능플래그
기능 플래그는 SDK 버전 2.0.0 이상인 경우 사용 가능합니다.
기능 플래그를 사용하시는 경우 의존성 추가 시 SDK 버전을 2.0.0 이상으로 적용하시기 바랍니다.
기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 각 상태에 따라 다른 기능을 설정하게 됩니다.
기능 플래그를 적용한 기능에 어떤 사용자가 접근할 경우 켜짐 혹은 꺼짐 상태를 받을 수 있어야 합니다. 이 상태 결정을 핵클 SDK를 통해 진행할 수 있습니다.
isFeatureOn
isFeatureOn()
메소드에 기능 키를 전달하면 사용자에 대한 상태 결과를 전달받을 수 있습니다. 이후 상태에 따른 로직을 구현합니다.
기능 키는 각 기능 플래그별로 갖게 되는 고유 번호이며 핵클 서비스 내의 대시보드에서 확인하실 수 있습니다.
아래 예제 코드에서는 기능 키 42를 전달하고 있으며, 상태를 받을 사용자의 사용자 식별자는 "ae03e1adf" 입니다.
import io.hackle.sdk.HackleClient
// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
// 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
boolean isFeatureOn = hackleClient.isFeatureOn(42, "ae03e1adf");
if (isFeatureOn) {
// ON 기능
} else {
// OFF 기능
}
import io.hackle.sdk.HackleClient
// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
// 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
val isFeatureOn: Boolean = hackleClient.isFeatureOn(42, "ae03e1adf")
if (isFeatureOn) {
// ON 기능
} else {
// OFF 기능
}
분배결과 확인하기
핵클 대시보드 안의 [왼쪽 메뉴바] - [A/B 테스트 또는 기능플래그] 화면에서 노출되는 A/B테스트 또는 기능플래그 리스트 중 연동한 대상을 찾아 상세 페이지로 이동 한 후 화면 중간에 [실시간 노출 현황] 탭을 클릭하면 SDK로 연동 된 분배 결과를 볼 수 있습니다.
단계 5. 종료
import io.hackle.sdk.HackleClient
hackleClient.close();
import io.hackle.sdk.HackleClient
hackleClient.close()
어플리케이션이 종료될 때 close()
메소드를 호출해야 합니다. 이 과정을 통해 사용 중인 리소스를 반납하고 남아있는 이벤트를 전송합니다. 이 과정 없이 어플리케이션이 종료되면 이벤트가 누락될 수 있습니다.
스프링 프레임워크를 사용 중이라면?
HackleClient
를 빈(bean)으로 등록하는 것이 가장 좋은 방법입니다.
어플리케이션 생명주기 동안 싱글 인스턴스로 관리가 되며 어플리케이션 종료 시close()
까지 자동으로 호출됩니다.
Hackle Client 를 wrapping 하여 사용하시는 경우
wrapping 클래스에 AutoClosable
implementation 하시고 close()
시에 HackleClient 의 close()
를 호출 하시는 방법을 권장드립니다.
import io.hackle.sdk.HackleClient
public class CustomHackleClient implements AutoCloseable {
private final HackleClient hackleClient;
public CustomHackleClient(HackleClient hackleClient) {
this.hackleClient = hackleClient;
}
@Override
public void close() throws Exception {
hackleClient.close();
}
}
import io.hackle.sdk.HackleClient
class CustomHackleClient(private val hackleClient: HackleClient): AutoCloseable {
override fun close() {
hackleClient.close()
}
}
Updated 4 months ago