# Ruby

本指南将会为您介绍如何使用 Ruby SDK 接入您的项目。

最新版本为：1.2.0

更新时间为：2020-08-28

# 一、集成SDK

请使用gem命令集成 SDK 包

# 获取 SDK
gem install thinkingdata-ruby

安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

# 二、初始化

以下是SDK初始化的示例代码:

require 'thinkingdata-ruby'
consumer = TDAnalytics::LoggerConsumer.new(LOG_DIRECTORY)
ta = TDAnalytics::Tracker.new(consumer)

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

# 三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

# 3.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

# 定义事件数据
event = {
  # 事件名称 （必填)
  'event_name' => 'test_event',
  'account_id' =>'ruby_test_aid',
  # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
  'distinct_id'=>'ruby_distinct_id',
  # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
  'ip' => '202.38.64.1',
  # 事件属性 (可选)
  'properties' =>{
    'prop_string' =>'hello world',
  },
  # 跳过本地格式校验 (可选)
  # skip_local_check: true,
}
# 上传事件
ta.track(event)

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TA会统一转化为小写字母
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

用户属性的要求与事件属性保持一致

# 3.2 设置用户属性

对于一般的用户属性，您可以调用 user_set 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

# 定义用户属性数据
user_data = {
	# 账号 ID （可选)
   'account_id' =>'ruby_test_aid',
   # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
    'distinct_id' => 'ruby_distinct_id',
   # 用户属性
  properties => {
    'user_name' => 'ta'
  }
}
# 设置用户属性
ta.user_set(user_data);

# 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

require 'thinkingdata-ruby'
consumer = TDAnalytics::LoggerConsumer.new(LOG_DIRECTORY)
ta = TDAnalytics::Tracker.new(consumer)

# 定义事件数据
event = {
  # 事件名称 （必填)
  'event_name' => 'test_event',
  'account_id' =>'ruby_test_aid',
  # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
  'distinct_id'=>'ruby_distinct_id',
  # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
  'ip' => '202.38.64.1',
  # 事件属性 (可选)
  'properties' =>{
    'prop_string' =>'hello world',
  },
  # 跳过本地格式校验 (可选)
  # skip_local_check: true,
}
# 上传事件
ta.track(event)

# 定义用户属性数据
user_data = {
	# 账号 ID （可选)
   'account_id' =>'ruby_test_aid',
   # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
    'distinct_id' => 'ruby_distinct_id',
   # 用户属性
  properties => {
    'user_name' => 'ta'
  }
}
# 设置用户属性
ta.user_set(user_data);

# 调用flush接口数据会立即写入文件，生产环境注意避免频繁调用flush引发IO或网络开销问题
ta.flush