이 문서는 Ruby SDK를 사용하기 위한 정보를 제공하고 설명합니다.

📘

Before You Read

• SDK 연동이 처음이라면, SDK 문서를 참고해주세요.

• 문서에서 언급되는 몇 가지 키가 있습니다. 각 키 개념 및 키를 확인하는 방법에 대해서는 SDK에서 사용되는 키 문서를 읽어주시기 바랍니다.

개요

Ruby SDK 기능

SDK는 두 가지 주요 기능이 있습니다.

• 테스트 그룹 분배
  A/B 테스트에서 사용하는 기능으로, 사용자를 A, B, C 등 특정 테스트 그룹으로 분배하여 할당하고 분배된 그룹을 반환합니다. 사용자가 A/B 테스트에 노출되었음을 기록하기 위해 할당된 그룹 정보를 핵클로 전송합니다.

• 사용자 이벤트 전송
  A/B 테스트 목표 계산 및 데이터 분석에서 사용하는 기능으로, 사용자의 행동을 분석하기 위해 이벤트를 전송합니다.

사용자 식별자 관리

사용자 식별자는 A/B 테스트에서 사용자를 고유하게 식별하는 데 사용됩니다. 테스트 그룹 분배, 사용자 이벤트 전송 기능을 사용할 때 사용자 식별자를 같이 전달해야 됩니다.

사용자 식별자에 대한 자세한 정보는 사용자 식별자 관리하기에서 확인할 수 있습니다.

작업 순서

SDK 연동

SDK 기능을 적용하기 위해 SDK 연동 작업이 필요합니다.
1단계 및 2단계가 이에 해당되며, 최초 연동 시 반드시 거쳐야 합니다.

A/B test or Data Analytics?

핵클 플랫폼 연동의 목적이 A/B 테스트인지 혹은 데이터 분석인지에 따라 적용해야 할 SDK 기능에 차이가 있습니다.

• A/B 테스트: 3단계 → 4단계 순으로 적용합니다.
  (1) A/B 테스트를 진행할 곳에 테스트 그룹 분배 기능을 적용합니다.
  (2) A/B 테스트의 목표를 추적할 곳에 사용자 이벤트 전송 기능을 적용합니다.
• 데이터 분석: 4단계를 적용합니다.
  분석할 이벤트가 발생하는 곳에 사용자 이벤트 전송 기능을 적용합니다.

SDK 연동

1 단계 : 의존성 추가

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

2 단계 : SDK 초기화

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

인스턴스화

require 'hackle-ruby-sdk'

# <YOUR_SERVER_SDK_KEY> 자리에 SDK 키를 넣습니다.
hackle_client = Hackle.client(sdk_key: '<YOUR_SERVER_SDK_KEY>')

[SDK 연동 정보] 에서 SDK 종류/환경 별 SDK 키를 확인 후 Server SDK 키를 복사하여 사용하세요.

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

❗️

hackle_client는 반드시 싱글톤이어야 합니다.

hackle_client는 호출 쓰레드를 블록킹 하지 않고 바로 테스트 그룹을 분배하기 위해 내부적으로 상태를 관리합니다. 이를 위해 추가적인 리소스를 사용합니다. 모든 요청에 대해 새로운 클라이언트를 인스턴스화 하지 않고 어플리케이션 생명주기 동안 싱글 인스턴스로 관리 되어야 합니다.

종료

hackle_client.close

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

Rails에서 Hackle Ruby SDK 사용하기

Rails application에서 SDK를 사용하려면 아래 코드를 통해 hackle_client를 설정할 수 있습니다.

# config/initializers/hackle_client.rb
# YOUR_SERVER_SDK_KEY 자리에 SDK 키를 넣습니다.
$hackle_client = Hackle.client(sdk_key: 'YOUR_SERVER_SDK_KEY')
at_exit { $hackle_client.close }

컨트롤러에서 아래 코드를 통해 hackle_client에 접근 할 수 있습니다.

class OrdersController 
  def show
    $hackle_client.variation(...)
  end
end

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

Unicorn
클러스터 모드에서 Unicorn을 사용하는 경우 아래 설정이 추가 되어야 합니다.

# config/unicorn.rb
# <YOUR_SERVER_SDK_KEY> 자리에 SDK 키를 넣습니다.
after_fork do |server, worker|
    $hackle_client = Hackle.client(sdk_key: '<YOUR_SERVER_SDK_KEY>')
end

Puma
클러스터 모드에서 Puma를 사용하는 경우 아래 설정이 추가 되어야 합니다.

# config/puma.rb
# <YOUR_SERVER_SDK_KEY> 자리에 SDK 키를 넣습니다.
on_worker_boot do
    $hackle_client = Hackle.client(sdk_key: '<YOUR_SERVER_SDK_KEY>')
end

SDK 기능 적용

• 주의: SDK 연동이 완료된 후 SDK 기능을 적용할 수 있습니다.

3 단계 : 테스트 그룹 분배

A/B 테스트 전용 단계입니다.
특정 실험 키에 속한 테스트 그룹을 대상으로 사용자를 분배하고, 각 테스트 그룹에 해당하는 로직을 작성합니다.

📘

테스트 그룹

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

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

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

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

📘

노출 이벤트 중복 제거

Ruby SDK를 사용하는 경우 동일한 사용자가 1분 이내에 연속으로 발생시킨 동일한 A/B 테스트 분배결과에 대한 노출 이벤트를 제거합니다. 1분 이내의 이벤트는 1회로 계산됩니다.

4 단계 : 사용자 이벤트 전송

결과 측정 및 분석을 위해 사용자 이벤트를 전송합니다.

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

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

활용 사례에 대해서는 아래 예시를 참고합니다.

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

# 예시 1: 이벤트 키만 전송
event = Hackle.event(key: 'purchase')
user = Hackle.user(id: 'ae2182e0')
hackle_client.track(event: event, user: user)

# 예시 2: 이벤트 키와 숫자 값을 함께 전송
event = Hackle.event(
  key: 'purchase',
  value: 32000.0      # 이벤트 키와 함께 수집할 숫자 값을 value에 넣는다
)
user = Hackle.user(id: 'ae2182e0')
hackle_client.track(event: event, user: user)

사용자가 구매하기 버튼을 눌렀을 때 이벤트를 수집하기 위해 purchase 라는 이벤트 키를 정의했다고 가정합니다.
예시 1에서는 이벤트 키만 전송하고 있으며, 예시 2에서는 구매 금액을 함께 수집하기 위해 value에 구매 금액을 넣은 사례를 보여주고 있습니다.