본문으로 건너뛰기

Ruby

최근 업데이트 2026. 08. 27.

이 가이드에서는 Ruby SDK를 사용하여 프로젝트에 연동하는 방법을 소개합니다.

최신 버전: v2.0.2

업데이트 시간: 2026-06-05

리소스 다운로드: 소스 코드

주의

이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 Ruby SDK 연동 가이드(V1)를 참고하십시오.

1. SDK 통합​

  1. gem 명령으로 SDK 패키지를 통합하십시오
# SDK 가져오기
gem install thinkingdata-ruby
  1. Logbus 설치

SDK+LogBus 방식으로 서버 측 데이터 수집 및 전송을 완료하는 것을 권장합니다. 다음 문서를 참고하여 Logbus를 설치할 수 있습니다: LogBus 사용 가이드

2. 초기화​

다음은 SDK 초기화 예시 코드입니다.

require 'thinkingdata-ruby'

consumer = ThinkingData::TDLoggerConsumer.new("LOG_DIRECTORY")
ta = ThinkingData::TDAnalytics.new(consumer)

LOG_DIRECTORY는 로컬에 기록할 폴더 경로입니다. LogBus의 모니터링 폴더 경로를 이 경로로 설정하기만 하면 LogBus로 데이터를 모니터링하고 업로드할 수 있습니다.

3. 자주 사용하는 기능​

게스트 ID와 계정 ID가 정상적으로 바인딩되도록, 게임에서 게스트 ID와 계정 ID를 모두 사용하는 경우 두 ID를 함께 전송할 것을 강력히 권장합니다. 그렇지 않으면 계정을 매칭할 수 없어 유저가 중복 집계될 수 있습니다. 구체적인 ID 바인딩 규칙은 유저 식별 규칙 장을 참고하십시오.

3.1 이벤트 전송​

track을 호출하여 이벤트를 업로드할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 다음은 이벤트 전송 예시 코드입니다:

DEMO_ACCOUNT_ID = '123'
DEMO_DISTINCT_ID = 'aaa'

properties = {
  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
  prop_date: Time.now,
  prop_double: 134.1,
  prop_string: 'hello world',
  prop_bool: true,
}

ta.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: properties)
  • 이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.
  • Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
  • Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

유저 속성의 요구 사항은 이벤트 속성과 같습니다

3.2 유저 속성 설정​

일반적인 유저 속성은 user_set을 호출하여 설정할 수 있습니다. 이 인터페이스로 업로드한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:

DEMO_ACCOUNT_ID = '123'
DEMO_DISTINCT_ID = 'aaa'

user_data = {
  array: ["str1", 11, 22.22],
  prop_date: Time.now,
  prop_double: 134.12,
  prop_string: 'hello',
  prop_int: 666,
}
ta.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_data)

3.3 데이터 전송​

TDLoggerConsumer를 사용하면 SDK가 수집한 데이터를 실시간으로 디스크에 기록하므로 flush() 메서드를 호출할 필요가 없습니다.

3.4 SDK 종료​

# SDK 종료 및 빠져나오기
ta.close

SDK를 종료하고 빠져나옵니다. 캐시 안의 데이터가 유실되지 않도록 서버를 종료하기 전에 이 인터페이스를 호출하십시오

4. 모범 사례​

다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다.

ThinkingData::set_stringent(false)
ThinkingData::set_enable_log(false)

consumer = ThinkingData::TDLoggerConsumer.new( 'LOG_DIRECTORY', 'hourly')
ta = ThinkingData::TDAnalytics.new(consumer, my_error_handler, uuid: true)

DEMO_ACCOUNT_ID = '123'
DEMO_DISTINCT_ID = 'aaa'

properties = {
  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
  prop_date: Time.now,
  prop_double: 134.1,
  prop_string: 'hello world',
  prop_bool: true,
}

ta.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: properties)

user_data = {
  array: ["str1", 11, 22.22],
  prop_date: Time.now,
  prop_double: 134.12,
  prop_string: 'hello',
  prop_int: 666,
}
ta.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_data)

user_append_data = {
  array: %w[33 44]
}
ta.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_append_data)

user_uniq_append_data = {
  array: %w[44 55]
}
ta.user_uniq_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_uniq_append_data)

user_set_once_data = {
  prop_int_new: 888,
}
ta.user_set_once(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_set_once_data)

ta.user_add(distinct_id: DEMO_DISTINCT_ID, properties: {prop_int: 10, prop_double: 15.88})

ta.user_unset(distinct_id: DEMO_DISTINCT_ID, property: [:prop_string, :prop_int])

ta.user_del(distinct_id: DEMO_DISTINCT_ID)
이 문서가 도움이 되었나요?
이 페이지의 내용