가이드 문서
Go to Docs (EN)Sign in to Dashboard

SDK 연동

Suggest Edits

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

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

1. 의존성 추가

gem install hackle-ruby-sdk -v '~> 2.0.0'

2. SDK 초기화

SDK를 사용하기 위해서 Hackle::Client를 초기화 해야 합니다. Hackle::Client를 초기화 하기 위해 SDK 키가 필요합니다.

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

hackle_client = Hackle::Client.create(sdk_key: 'YOUR_SERVER_SDK_KEY')

Rails 및 클러스터 모드를 사용하는 경우, 가이드 하단을 참고해주세요.

❗️

Hackle::Client는 반드시 싱글톤이어야 합니다.

Hackle::Client는 네트워크 호출 없이 바로 A/B 테스트, 기능플래그 결과를 분배하기 위해 내부적으로 상태를 관리합니다. 이를 위해 추가적인 리소스를 사용합니다. 모든 요청에 대해 새로운 인스턴스를 생성하지 않고, 어플리케이션 생명주기 동안 싱글 인스턴스로 관리 되어야 합니다.

3. 이벤트 전송

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

require 'hackle-ruby-sdk'

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

user = Hackle::User.builder
                   .device_id('ae2182e0')
                   .build

event = Hackle::Event.builder('purchase')
                     .property('amount', 4200)
                     .property('pay_method', 'CARD')
                     .property('is_discount', false)
                     .property('product_ids', [42, 43])
                     .build

hackle_client.track(event, user)

전송한 이벤트 확인하기

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

4. A/B 테스트

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

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

require 'hackle-ruby-sdk'

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

user = Hackle::User.builder
                   .device_id('ae2182e0')
                   .build

variation = hackle_client.variation(42, user)

if variation == 'A'
  # 그룹 A 로직
elsif variation == 'B'
  # 그룹 B 로직
end

5. 기능 플래그

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

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

require 'hackle-ruby-sdk'

# 기능 키가 42인 기능 플래그에서
# 'ae2182e0'라는 식별자를 가진 사용자의 기능 on/off 상태를 결정합니다.
# 결정하지 못하는 상황인 경우 false(꺼짐 상태)를 반환합니다.

user = Hackle::User.builder
                   .device_id('ae2182e0')
                   .build

feature_on = hackle_client.is_feature_on(42, user)

if feature_on
  # ON 기능
else
  # OFF 기능
end

6. 종료

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

hackle_client.close

Rails에서 SDK 사용하기

# config/initializers/hackle_client.rb

$hackle_client = Hackle::Client.create(sdk_key: 'YOUR_SERVER_SDK_KEY')
at_exit { $hackle_client.close }

클러스터 모드

Application이 시작되면 SDK는 여러 쓰레드를 생성합니다. 각 쓰레드는 백그라운드에서 이벤트를 일괄 처리 및 전달 하고 A/B테스트 정보를 가져오는 무한 루프가 있습니다. 여러 하위 프로세스를 생성하는 웹서버에서 SDK를 사용하는 경우(예: Puma, Unicorn / workers > 0) application 서버는 하위 프로세스를 생성하지만 상위 프로세스에 존재하는 쓰레드를 다시 생성하지 않습니다. 따라서 Unicorn, Puma 등에서 클러스터 모드로 실행이 되는 경우 하위 프로세스 또는 Worker가 생성 된 후 SDK를 추가로 생성해야 합니다.

Unicorn

# config/unicorn.rb

after_fork do |server, worker|
  $hackle_client = Hackle::Client.create(sdk_key: 'YOUR_SERVER_SDK_KEY')
end

Puma

# config/puma.rb

on_worker_boot do
  $hackle_client = Hackle::Client.create(sdk_key: 'YOUR_SERVER_SDK_KEY')
end

Updated 6 months ago