SDK 연동

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

• 단계1. SDK 설치
• 단계2. SDK 초기화
• 단계3. 사용자 이벤트 전송
• 단계4. A/B 테스트, 기능플래그

단계 1. SDK 설치

Unity Package Manager를 통해 SDK 설치가 필요합니다.

여기를 클릭하여, SDK를 다운로드 받습니다.

Unity에서 Assets > Import Package > Custom Package를 클릭합니다.
다운받은 package를 선택하고, import 하면 설치가 완료됩니다.

Android ProGuard / R8

ProGuard, R8을 사용하는 경우, aar 아티팩트에 난독화 규칙이 자동으로 포함됩니다. 이 경우가 아니라면 아래 규칙을 포함시켜야 합니다.

-keep class io.hackle.android.** { *; }
-keep class io.hackle.sdk.** { *; }

📘

SDK 설치 후 앱 재설치

Unity SDK는 Android, iOS SDK가 포함되어 있습니다.
기존에 테스트 중이던 앱을 새롭게 빌드해야 연동이 완료됩니다.

업데이트 시 유의사항

업데이트를 하시는 경우, 기존 import 된 라이브러리 중 위의 선택된 라이브러리 삭제 후 다시 import 작업을 진행해야합니다.

• hackle-android-sdk-x.x.x
• hackle-android-unity-wrapper-x.x.x
• hackle-sdk-common-x.x.x
• hackle-sdk-core-x.x.x
• ios-arm64_armv7
• ios-arm64_i386_x86_64-simulator

Android SDK 의존성 관리

Android에서는 아래와 같은 의존성 라이브러리를 가지고 있습니다.
Unity SDK가 Android 환경에서 동작을 하지 않는 경우 아래 라이브러리가 존재하는지 확인이 필요합니다.

• hackle-android-sdk-2.12.0
• hackle-android-unity-wrapper-1.5.0
• hackle-sdk-common-2.9.0
• hackle-sdk-core-2.9.0
• core-common
• gson
• kotlin-stdlib
• lifecycle-common
• lifecycle-extensions
• lifecycle-process
• lifecycle-runtime
• okhttp
• okio

단계 2. SDK 초기화

핵클 서버로부터 SDK 연동에 필요한 정보들을 가져와서 SDK에 저장합니다. 이 작업은 비동기로 실행되며 콜백을 통해 초기화가 완료된 것을 알 수 있습니다.
Hackle.Initialize() 메소드에 SDK 키를 전달하여 초기화하고, 초기화 완료 시까지 기다리기 위해 await를 합니다.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class HackleInit : MonoBehaviour
{
    async void Awake () {
        await Hackle.Initialize("YOUR_APP_SDK_KEY");
    }
}

SDK 키 확인하기

SDK 키는 단계 1에서 가입한 핵클 대시보드 안에서 확인할 수 있습니다. SDK 연동 정보 에서 SDK 종류/환경 별 SDK 키를 확인 후 APP SDK 키를 복사하여 사용하세요.

단계 3. 사용자 이벤트 전송

핵클 SDK는 사용자 이벤트를 핵클로 전송하는 기능을 제공합니다.
사용자 행동의 변화가 일어나는 지점마다 이 기능을 활용하면 사용자 행동에 대한 유의미한 데이터를 얻을 수 있으며, 그렇게 모인 데이터를 통해 사용자 행동 분석을 할 수 있습니다.

track

Track() 메소드에 이벤트 키를 전달하여 사용자 이벤트를 전송할 수 있습니다. 필요한 경우 사용자 이벤트 전송 시 숫자 값을 value에 넣어 함께 전송할 수 있습니다.

• value는 number 타입만 넣을 수 있습니다.

예시

사용자가 구매하기 버튼을 눌렀을 때 이벤트를 수집하기 위해 purchase 라는 이벤트 키를 정의했다고 가정합니다.
이 때 구매 속성정보를 같이 수집하고 싶을 수 있습니다. 이런 경우 property에 구매 속성정보를 함께 받을 수 있습니다.

/* 예시 1: 이벤트 키만 전송 */
hackle.Track("purcahse");

/* 예시 2: 이벤트 키와 속성정보를 함께 전송 */
Dictionary<string, object> properties = new Dictionary<string, object>();
properties["pay_method"] = "CARD";
properties["discount_amount"] = 800;
properties["is_discount"] = true;

HackleEvent event = new HackleEvent(
  eventKey: "purchase", 
  value: 13200, 
  properties: properties
);
hackle.Track(event);

예시 1에서는 이벤트 키만 전송하고 있으며, 예시 2에서는 구매 속성정보를 함께 수집하기 위해 properties에 구매 속성정보를 넣은 사례를 보여주고 있습니다.

사용자 이벤트 전송 확인하기

SDK 에서 전송한 사용자 이벤트가 정상적으로 수집되고 있는지 확인해보세요.
핵클 대시보드 안의 [왼쪽 메뉴바] - [이벤트 관리] 메뉴에서 SDK로 전송한 이벤트를 찾아 실시간 이벤트 수집현황을 확인해볼 수 있습니다.

단계 4. A/B 테스트, 기능플래그

A/B 테스트

A/B 테스트를 진행할 때, 테스트 그룹을 대상으로 사용자를 분배하고 각 테스트 그룹에 해당하는 로직을 작성해야 합니다. 이 때 사용자 분배를 핵클 SDK를 통해 진행할 수 있습니다.

📘

테스트 그룹

테스트 그룹은 테스트 대상이 되는 기존안(대조군)과 개선안(실험군)을 의미하며, 개선안은 1개 이상일 수 있습니다. 대시보드에서 설정 가능하며, 테스트 그룹을 관리하는 방법에 대해서는 A/B 테스트 설정 문서를 참고하시기 바랍니다.

🚧

Unity Editor

Unity SDK는 Android, iOS SDK를 기반으로 동작합니다.
따라서, Unity Editor에서는 모두 그룹 A를 리턴합니다.

variation

Variation() 메소드에 실험 키를 전달하면 사용자를 분배하고 결과를 전달받을 수 있습니다. 이후 테스트 그룹 별 로직을 구현합니다.
실험 키는 각 A/B 테스트별로 갖게 되는 고유 번호이며, 핵클 서비스 내의 대시보드에서 확인할 수 있습니다.
아래 예제 코드에서는 실험 키 42를 전달하고 있으며, 테스트 그룹은 A와 B 두 개가 존재합니다.

// 실험 키가 42인 A/B 테스트에서 사용자에게 노출할 테스트 그룹을 결정합니다.
// 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.
string variation = hackle.Variation(42);

// 할당받은 그룹에 대한 로직
if (variation == "A") {
  // 그룹 A 로직
} else if (variation == "B") {
  // 그룹 B 로직
}

기능플래그

기능 플래그는 켜짐(on) 상태와 꺼짐(off) 상태가 있습니다. 각 상태에 따라 다른 기능을 설정하게 됩니다.
기능 플래그를 적용한 기능에 어떤 사용자가 접근할 경우 켜짐 혹은 꺼짐 상태를 받을 수 있어야 합니다. 이 상태 결정을 핵클 SDK를 통해 진행할 수 있습니다.

🚧

Unity Editor

Unity SDK는 Android, iOS SDK를 기반으로 동작합니다.
따라서, Unity Editor에서는 꺼짐(off)상태인 false를 리턴합니다.

isFeatureOn

IsFeatureOn() 메소드에 기능 키를 전달하면 사용자에 대한 상태 결과를 전달받을 수 있습니다. 이후 상태에 따른 로직을 구현합니다.
기능 키는 각 기능 플래그별로 갖게 되는 고유 번호이며 핵클 서비스 내의 대시보드에서 확인하실 수 있습니다.
아래 예제 코드에서는 기능 키 42를 전달하고 있습니다.

// 기능 키가 42인 기능 플래그에서 사용자의 상태를 결정합니다.
// 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.
bool isFeatureOn = hackle.IsFeatureOn(42);

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

분배결과 확인하기

핵클 대시보드 안의 [왼쪽 메뉴바] - [A/B 테스트 또는 기능플래그] 화면에서 노출되는 A/B테스트 또는 기능플래그 리스트 중 연동한 대상을 찾아 상세 페이지로 이동 한 후 화면 중간에 [실시간 노출 현황] 탭을 클릭하면 SDK로 연동 된 분배 결과를 볼 수 있습니다.