---
code: ruby_sdk_installation
name: "Ruby"
wikiToken: JQwMwwgRviGugBklAUJcBSSjnng
parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
updateTime: 1745310924000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ruby_sdk_installation
---
# Ruby

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

**最新版本为**：v2.0.0

**更新时间为**：2023-10-08

**资源下载****：**源代码

::: warning 注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Ruby SDK 接入指南（V1）

::: 

### 一、集成SDK

1. 请使用`gem`命令集成 SDK 包
```
# 获取 SDK
gem install thinkingdata-ruby
```

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

### 二、初始化

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

```
require 'thinkingdata-ruby'

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

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

### 三、常用功能

为了保证访客 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 个字符，对字母大小写不敏感,TE会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

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

#### 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
```

<!-- unsupported block: 34 -->

关闭并退出 SDK，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

### 四、最佳实践

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

```
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)
```
