1. Ruby SDK 使用说明

在使用前，请先阅读数据模型 的介绍。

2. 集成神策分析 SDK

在 Ruby 脚本中集成神策分析 SDK，使用神策分析采集并分析用户数据。

我们推荐使用 RubyGem 管理 Ruby 项目并获取神策分析 SDK：

gem install sensors_analytics_sdk

CODE

如果不使用 RubyGem，也可以从 GitHub 下载神策分析 SDK 的源代码。

2.1. 初始化神策分析 SDK

2.1.1. 获取配置信息

如下图所示获取数据接收地址：

2.1.2. 在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例：

Ruby

require 'sensors_analytics_sdk.rb'

# 从神策分析配置页面中获取的数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'

# 初始化一个 Consumer，用于数据发送
consumer = SensorsAnalytics::DefaultConsumer.new(SA_SERVER_URL)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)

# 记录用户登录事件
distinct_id = 'ABCDEF123456'
sa.track(distinct_id, 'UserLogin')

CODE

其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 close() 方法显式关闭，否则可能丢失部分缓存的数据。

至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制神策分析 SDK 一节。

3. 设置神策分析 SDK

Ruby SDK 主要由以下两个组件构成:

SensorsAnalytics：用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer：Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer：

DebugConsumer
DefaultConsumer
BatchConsumer

3.1. DebugConsumer（测试使用）

用于校验数据导入是否正确，关于 Debug 调试模式的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。

初始化接口为

# server_url 是接收端的 url
# writeData表示是否校验数据
# writeData为
# true - 校验数据，并将数据导入到神策分析中
# false - 校验数据，但不进行数据导入
def initialize(server_url, write_data)

end

CODE

例子

require 'sensors_analytics_sdk.rb'

# 从神策分析配置页面中获取的数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'
# Debug 模式下，是否将数据导入神策分析
# true - 校验数据，并将数据导入到神策分析中
# false - 校验数据，但不进行数据导入
SA_DEBUG_WRITE_DATA = true

# 初始化 Debug Consumer
consumer = SensorsAnalytics::DebugConsumer.new(SA_SERVER_URL, SA_DEBUG_WRITE_DATA)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)

CODE

3.2. DefaultConsumer

通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。普通 Consumer，实现，逐条、同步的发送数据给接收服务器。

初始化接口

# server_url 是接收端的 url
def initialize(server_url)
  
end

CODE

例子

require 'sensors_analytics_sdk.rb'

# 从神策分析配置页面中获取的数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'

# 初始化一个 Consumer，用于数据发送
consumer = SensorsAnalytics::DefaultConsumer.new(SA_SERVER_URL)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)

CODE

3.3. BatchConsumer

通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。

初始化接口

# server_url 是接收端的 url
# flush_bulk 最大缓存条数
def initialize(server_url, flush_bulk = MAX_FLUSH_BULK)

end

CODE

例子

require 'sensors_analytics_sdk.rb'

# 从神策分析配置页面中获取的数据接收的 URL
SA_SERVER_URL = 'YOUR_SERVER_URL'
# 当缓存的数据量达到参数值时，批量发送数据
SA_BULK_SIZE = 100

# 初始化 Batch Consumer
consumer = SensorsAnalytics::BatchConsumer.new(SA_SERVER_URL, SA_BULK_SIZE)
sa = SensorsAnalytics::SensorsAnalytics.new(consumer)

# 程序结束前调用 flush() ，通知 Consumer 发送所有缓存数据
consumer.flush()

CODE

4. API 接口

针对 API 接口的使用文档，参照基础 API 使用文档介绍。