📘

Hackle Python SDK는 Python 3 이상을 지원합니다.

WSGI 환경을 사용하시는 경우 가이드 WSGI 설정 을 꼭 확인해주세요

1. 의존성 추가

pip install hackle-sdk

2. SDK 초기화

hackle_client는 SDK 기능을 사용하기 위한 메소드들을 제공하는 클래스입니다.

SDK를 사용하기 위해서는 hackle_client 초기화가 필요합니다.

인스턴스화

SDK 키를 전달하여 hackle_client를 인스턴스화 합니다.
hackle_client는 필요한 정보들을 얻기 위해 백그라운드 작업으로 핵클 서버와 주기적으로 동기화합니다.

• SDK 키는 핵클 서비스의 대시보드 안에 위치한 SDK 연동 정보에서 확인하실 수 있습니다.

❗️

hackle_client는 전역변수이며, 반드시 한 번만 생성해야 합니다.

hackle_client는 쓰레드에서 I/O없이 바로 결과를 평가하기 위해 내부적으로 상태를 관리합니다. 이를 위해 추가적인 리소스를 사용합니다. 모든 요청에 대해 새로운 인스턴스를 생성하지 않고, 이미 생성되어 있는 인스턴스를 사용합니다.

hackle_client 는 싱글톤(Singleton) 객체로 만들어져 있기 때문에, 다른 함수에서 사용할 때 hackle.Client()로 사용해도 재생성하지 않습니다.

from hackle import hackle

// YOUR_SERVER_SDK_KEY 자리에 SDK 키를 넣습니다.
hackle_client = hackle.Client(sdk_key=YOUR_SERVER_SDK_KEY)

3. 사용자 이벤트 전송

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

from hackle.model import HackleUser, HackleEvent


# "ae2182e0"라는 디바이스 식별자를 가진 사용자가 발생시킨 "purchase"라는 이벤트를 전송

user = HackleUser.builder() \
                 .device_id('ae2182e0') \
                 .build()

event = HackleEvent.builder('purchase') \
                   .property('pay_method', 'CARD') \
                   .property('discount_amount', 800) \
                   .property('is_discounted', True) \
                   .build()

hackle_client.track(event=event, user=user)

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

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

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

A/B 테스트

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

📘

테스트 그룹

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

variation

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

from hackle.model import HackleUser

# 실험 키가 42인 A/B 테스트에서
# "ae2182e0"라는 디바이스 식별자를 가진 사용자에게 노출할 테스트 그룹을 결정합니다.
# 결정하지 못하는 상황인 경우 테스트 그룹 A를 반환합니다.

user = HackleUser.builder() \
                 .device_id('ae2182e0') \
                 .build()

variation = hackle_client.variation(experiment_key=42, user=user)

# 할당받은 그룹에 대한 로직
if variation == 'A':
    # 그룹 A 로직
elif variation == 'B':
    # 그룹 B 로직

기능플래그

📘

기능 플래그는 SDK 버전 2.0.0 이상인 경우 사용 가능합니다.

기능 플래그를 사용하시는 경우 의존성 추가 시 SDK 버전을 2.0.0 이상으로 적용하시기 바랍니다.

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

isFeatureOn

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

from hackle.model import HackleUser

# 기능 키가 42인 기능 플래그에서
# "ae2182e0"라는 디바이스 식별자를 가진 사용자에게 노출할 테스트 그룹을 결정합니다.
# 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.

user = HackleUser.builder() \
                 .device_id('ae2182e0') \
                 .build()

feature_on = hackle_client.is_feature_on(feature_key=42, user=user)

# 할당받은 그룹에 대한 로직
if feature_on == True:
    # ON 기능
elif feature_on == False:
    # OFF 기능

분배결과 확인하기

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

5. 종료

hackle_client.close()

어플리케이션이 종료될 때 hackle_client.close() 메소드를 통해 hackle_client를 종료시켜야 합니다. 이를 통해 클라이언트가 사용 중인 리소스를 반납하고 남아있는 이벤트를 전송합니다. 이 과정없이 어플리케이션이 종료되면 이벤트가 누락될 수 있습니다.

Flask나 Django를 사용 중 이라면?

@atexit.register를 통해 어플리케이션 종료 시 자동으로 hackle_client를 종료시킬 수 있습니다.

import atexit

@atexit.register
def __exit__():
    hackle_client.close()