SDK 연동

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

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

1. 의존성 추가

CocoaPods

pod 'Hackle', '~> 2.20.1'

Swift Package Manager

// ...
dependencies: [
    .package(url: "https://github.com/hackle-io/hackle-ios-sdk.git", 
                          .upToNextMinor("2.20.1"))
],
targets: [
    .target(
        name: "YOUR_TARGET",
        dependencies: ["Hackle"]
    )
],
// ...

2. SDK 초기화

SDK를 사용하기 위해서 반드시 HackleApp을 초기화 해야 합니다. HackleApp을 초기화 하기 위해 SDK 키가 필요합니다.

  • HackleApp은 SDK의 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.
  • SDK 키는 핵클 서비스의 대시보드 안에 위치한 SDK 연동 정보에서 확인하실 수 있습니다.
import Hackle

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY)
@import Hackle;

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:[HackleConfig DEFAULT]];

초기화 완료

초기화가 시작되면 핵클 서버로부터 필요한 정보들을 가져와서 SDK에 저장합니다. 이 작업은 비동기로 실행되며, 초기화시 마지막 파라미터로 콜백을 전달하면 SDK 사용 준비가 완료된 것을 알 수 있습니다. 초기화가 완료 되기 전에 A/B 테스트, 기능 플래그를 호출하면 기본 그룹(A), 꺼짐(false)을 리턴합니다.

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY) {
    // SDK ready to use.
}
[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:[HackleConfig DEFAULT] completion:^{
    // SDK ready to use.
}];

권장 초기화 전략: 로딩 화면을 통한 초기화

앱을 즉시 시작하지 않고 로딩 화면을 표시하고 SDK를 초기화합니다.
이후 콜백을 통해 로딩 화면을 닫고 사용자가 앱과 상호작용을 시작할 수 있도록 합니다.

이 전략을 사용하는 경우 로딩 화면에 제한 시간을 두는 것이 좋습니다.

인스턴스 가져오기

초기화 이후 아래 코드를 통해 HackleApp 인스턴스를 가져올 수 있습니다.

let hackleApp = Hackle.app()
HackleApp *hackleApp = [Hackle app];

초기화 설정정보

설정정보를 포함하여 SDK를 초기화 할 수 있습니다

let config = HackleConfigBuilder()
  .exposureEventDedupIntervalSeconds(60)
  .build()

Hackle.initialize(sdkKey: YOUR_APP_SDK_KEY, config: config) {
    // SDK ready to use.
}
HackleConfigBuilder *builder = [[HackleConfigBuilder alloc] init];
[builder exposureEventDedupIntervalSeconds:1];
HackleConfig *config = [builder build];

[Hackle initializeWithSdkKey:@"YOUR_APP_SDK_KEY" config:config completion:^{
    // SDK ready to use.
}];

모든 설정 옵션

설정기능기본값지원 버전
exposureEventDedupIntervalSeconds동일한 사용자가 연속으로 발생시킨 동일한 A/B 테스트, 기능플래그 분배결과에 대한 노출 이벤트를 제거합니다.

최솟값: 1
최댓값: 3600 (1시간)
60 (1분)2.7.0+
pollingIntervalSeconds대시보드에서 설정한 정보를 주기적으로 업데이트 할 수 있습니다.

최솟값 : 60 (1분)
-1
(주기적으로 업데이트하지 않음)
2.18.0+

3. 사용자 설정

사용자 정보를 SDK에 설정 할 수 있습니다.

사용자 ID 설정

사용자가 로그인한 경우, setUserId를 호출해서 로그인한 사용자의 ID를 설정할 수 있습니다.

  • 로그인 시 한번만 설정하면 됩니다.
  • 이미 로그인이 되어있는 사용자의 경우에는 로그인한 정보를 확인하는 시점에 호출하면 됩니다.
let userId: String = ... // 로그인한 사용자의 ID (회원번호, 멤버 ID 등)
hackleApp.setUserId(userId: userId)
NSString *userId = ... // 로그인한 사용자의 ID (회원번호, 멤버 ID 등)
[hackleApp setUserIdWithUserId:userId];

사용자 속성 설정

이메일주소, 위치, 나이, 회원등급과 같은 정보를 사용자 속성으로 사용할 수 있습니다.

let operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .build()

hackleApp.updateUserProperties(operations: operations)
PropertyOperationsBuilder *builder = [PropertyOperations builder];
[builder set:@"age" :@42];
[builder set:@"grade" :@"GOLD"];
PropertyOperations *operations = [builder build];

[hackleApp updateUserPropertiesWithOperations:operations];

사용자 로그아웃 시 재설정

사용자가 로그아웃 한 경우 resetUser를 호출하여 기존에 설정한 사용자 정보를 리셋할 수 있습니다. 아래 정보가 리셋됩니다.

  • 사용자 ID
  • 사용자 속성
hackleApp.resetUser()
[hackleApp resetUser];

4. 이벤트 전송

사용자가 수행하는 행동을 이벤트로 전송할 수 있습니다. 전송된 이벤트는 A/B 테스트 분석, 데이터 분석 등에 사용됩니다. 예를들어, 사용자가 구매라는 행동을 했다면 아래와 같이 이벤트를 전송할 수 있습니다.

import Hackle

// 이벤트 전송
hackleApp.track(eventKey: "purcahse")

// 이벤트를 속성과 함께 전송
let event = Event.builder("purchase")
    .property("amount", 4200)
    .property("pay_method", "CARD")
    .property("is_discount", false)
    .build()

hackleApp.track(event: event)
@import Hackle;

// 이벤트 전송
[hackleApp trackWithEventKey:@"purchase"];

// 이벤트를 속성과 함께 전송
HackleEventBuilder *builder = [Event builder:@"purchase"];
[builder property:@"amount" :@4200];
[builder property:@"pay_method" :@"CARD"];
[builder property:@"is_discount" :@false];
Event *event = [builder build];

[hackleApp trackWithEvent:event];

전송한 이벤트 확인하기

대시보드 이벤트관리 메뉴에서 전송한 이벤트를 확인할 수 있습니다. 이벤트 전송 후 대시보드에 표시되기까지 일반적으로 ~60초가 걸립니다.


5. A/B 테스트

사용자를 테스트 그룹으로 분배하고 분배된 결과에 해당하는 로직을 작성하여 A/B 테스트를 구현합니다. variation에 실험키를 전달하여 호출하면 분배결과를 리턴받을 수 있습니다.

실험키: 각 A/B 테스트별로 갖게 되는 고유 번호입니다. A/B 테스트를 생성하면 자동으로 발급됩니다.

// 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
let variation = hackleApp.variation(experimentKey: 42)

// 할당받은 그룹에 대한 로직
if variation == "A" {
  // 그룹 A 로직
} else if variation == "B" {
  // 그룹 B 로직
}
// 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
NSString *variation = [hackleApp variationWithExperimentKey:42 defaultVariation:@"A"];

// 할당받은 그룹에 대한 로직
if([variation isEqual:@"A"]) {
    // 그룹 A 로직
} else if ([variation isEqual:@"B"]) {
    // 그룹 B 로직
}

분배 결과 확인하기

대시보드 A/B 테스트의 상세페이지의 실시간 노출 현황 탭에서 분배된 결과를 확인할 수 있습니다. 분배 후 대시보드에 표시되기까지 일반적으로 ~60초가 걸립니다.


6. 기능 플래그

기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 상태에 따라 다른 로직을 작성하여 기능 플래그를 구현합니다. isFeatureOn에 기능플래그키를 전달하여 호출하면 on/off 여부를 리턴받을 수 있습니다.

기능플래그키: 각 기능플래그별로 갖게 되는 고유 번호입니다. 기능플래그를 생성하면 자동으로 발급됩니다.

// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
let isFeatureOn: Bool = hackleApp.isFeatureOn(featureKey: 42)

if isFeatureOn {
    // ON 기능
} else {
    // OFF 기능
}
// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
bool isFeatureOn = [hackleApp isFeatureOnFeatureKey:@42];

if (isFeatureOn) {
    // ON 기능      
} else {
    // OFF 기능
}