thinkingdata-ruby 1.2.0 → 2.0.0

data/README.md

@@ -1,202 +1,11 @@
-# ThinkingData Analytics API for Ruby
-
-thinkingdata-ruby 是数数科技提供给客户，方便客户导入用户数据的 Ruby 接口实现, 支持 Ruby 2.0 以上版本。如需了解详细信息，请参考 [数数科技官方网站](https://www.thinkingdata.cn).
-
-### 一、集成 SDK
-
-#### 1. 安装 SDK
-
-```sh
-# 获取 SDK
-gem install thinkingdata-ruby
-```
-#### 2. 创建 SDK 实例
-首先在代码文件开头引入 `thinkingdata-ruby`:
-```ruby
-require 'thinkingdata-ruby'
-```
-
-使用 SDK 上传数据，需要首先创建 `TDAnalytics::Tracker` 对象. `TDAnalytics::Tracker` 是数据上报的核心类，使用此类上报事件数据和更新用户属性. 创建 `Tracker` 对象需要传入 consumer 对象，consumer 决定了如何处理格式化的数据（存储在本地日志文件还是上传到服务端).
-  
-```ruby
-ta = TDAnalytics::Tracker.new(consumer)
-ta.track('your_event', distinct_id: 'distinct_id_of_user')
-```
-TDAnalytics 提供了三种 consumer 实现:
-
-**(1) LoggerConsumer**: 将数据实时写入本地文件，文件以 天/小时 切分，并需要与 LogBus 搭配使用进行数据上传.
-```ruby
-# 默认写入当前目录的文件，按日期命名(daily)，例如: tda.log.2019-11-15
-consumer = TDAnalytics::LoggerConsumer.new
-
-# 也可以修改配置，如下配置会创建 LoggerConsumer，并将数据写入: /path/to/log/demolog.2019-11-15-18 (18 为小时)
-consumer = TDAnalytics::LoggerConsumer.new('/path/to/log', 'hourly', prefix: 'demolog')
-```
-
-**(2) DebugConsumer**: 逐条实时向 TA 服务器传输数据，当数据格式错误时会返回详细的错误信息。建议先使用 DebugConsumer 校验数据格式。初始化传入项目 APP ID 和接收端地址.
-```ruby
-# 创建 DebugConsumer
-consumer = TDAnalytics::DebugConsumer.new(SERVER_URL, YOUR_APPID)
-```
-
-**(3) BatchConsumer**: 批量实时地向 TA 服务器传输数据，不需要搭配传输工具。在网络条件不好的情况下有可能会导致数据丢失，因此不建议在生产环境中大量使用. 初始化传入项目 APP ID 和接收端地址.
-
-BatchConsumer 会先将数据存放在缓冲区中，当数据条数超过设定的缓冲区最大值(max_buffer_length, 默认为20)，触发上报. 您也可以在初始化 SDK 时传入整数类型的参数配置缓冲区大小:
-```ruby
- # BatchConsumer，数据将先存入缓冲区，达到指定条数时上报，默认为 20 条
- consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, YOUR_APPID)
-
- # 创建指定缓冲区大小为 3 条的 BatchConsumer
- consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, YOUR_APPID, 3)
-```
-  
-您也可以传入自己实现的 Consumer，只需实现以下接口:
-- add(message): (必须) 接受 Hash 类型的数据对象
-- flush: (可选) 将缓冲区的数据发送到指定地址
-- close: (可选) 程序退出时用户可以主动调用此接口以保证安全退出
-
-#### 3. 上报数据
-SDK 初始化完成后，后续即可使用 ta 的接口来上报数据.
-
-### 使用示例
-
-#### a. 发送事件
-您可以调用 track 来上传事件，建议您根据预先梳理的文档来设置事件的属性以及发送信息的条件。上传事件示例如下：
-```ruby
-# 定义事件数据
-event = {
-  # 事件名称 （必填)
-  event_name: 'test_event',
-  # 账号 ID （可选)
-  account_id: 'ruby_test_aid',
-  # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-  distinct_id: 'ruby_distinct_id',
-  # 事件时间 (可选) 如果不填，将以调用接口时的时间作为事件时间
-  time: Time.now,
-  # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
-  ip: '202.38.64.1',
-  # 事件属性 (可选)
-  properties: {
-    prop_date: Time.now,
-    prop_double: 134.1,
-    prop_string: 'hello world',
-    prop_bool: true,
-  },
-  # 跳过本地格式校验 (可选)
-  # skip_local_check: true,
-}
-
-# 上传事件
-ta.track(event)
-```
-
-参数说明：
-* 事件的名称只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感
-* 事件的属性是 Hash 类型，其中每个元素代表一个属性
-* 事件属性的 Key 值为属性的名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感
-* 事件属性的 Value 值为该属性的值，支持 String、数值类型、bool、Time
-
-SDK 会在本地对数据格式做校验，如果希望跳过本地校验，可以在调用 track 接口的时候传入 skip_local_check 参数.
-
-#### 2. 设置公共事件属性
-公共事件属性是每个事件都会包含的属性. 也可以设置动态公共属性。如果有相同的属性，则动态公共属性会覆盖公共事件属性。
-
-```ruby
-# 定义公共属性
-super_properties = {
-  super_string: 'super_string',
-  super_int: 1,
-  super_bool: false,
-  super_date: Time.rfc2822("Thu, 26 Oct 2019 02:26:12 +0545") 
-}
-
-# 设置公共事件属性，公共事件属性会添加到每个事件中
-ta.set_super_properties(super_properties)
-
-# 清空公共事件属性
-ta.clear_super_properties
-```
-
-#### 3. 设置用户属性
-对于一般的用户属性，您可以调用 user_set 来进行设置. 使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性:
-```ruby
-# 定义用户属性数据
-user_data = {
-	# 账号 ID （可选)
-	account_id: 'ruby_test_aid',
-	# 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-	distinct_id: 'ruby_distinct_id',
-	# 用户属性
-  properties: {
-    prop_date: Time.now,
-    prop_double: 134.12,
-    prop_string: 'hello',
-    prop_int: 666,
-	},
-}
-
-# 设置用户属性
-ta.user_set(user_data);
-```
-如果您要上传的用户属性只要设置一次，则可以调用 user_set_once 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息:
-```ruby
-# 设置用户属性，如果已有同名属性，则忽略新设置属性
-ta.user_set_once(user_data);
-```
-当您要上传数值型的属性时，可以调用 user_add 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算:
-```ruby
-# 对数值类型的属性进行累加操作
-ta.user_add(distinct_id: 'ruby_distinct_id', properties: {prop_int: 10, prop_double: 15.88})
-```
-
-当您需要删除某个用户属性的值时，可以调用 user_unset.
-```ruby
-# 删除某个用户属性
-ta.user_unset(distinct_id: 'ruby_distinct_id', property: :prop_string)
-
-# 删除一组用户属性
-ta.user_unset(distinct_id: 'ruby_distinct_id', property: Array.[](:prop_a, :prop_b, :prob_c))
-```
-
-如果您要删除某个用户，可以调用 user_del 将这名用户删除. 之后您将无法再查询该用户的用户属性，但该用户产生的事件仍然可以被查询到:
-```ruby
-# 删除用户
-ta.user_del(
-	# 账号 ID （可选)
-	account_id: 'ruby_test_aid',
-	# 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-	distinct_id: 'ruby_distinct_id',
-);
-```
-
-#### 4. 立即进行数据 IO
-此操作与具体的 Consumer 实现有关. 在收到数据时, Consumer 可以先将数据存放在缓冲区, 并在特定情况下触发真正的数据 IO 操作, 以提高整体性能. 在某些情况下需要立即提交数据，可以调用 flush 接口:
-```ruby
-# 立即提交数据到相应的接收端
-ta.flush
-```
-
-#### 5. 关闭 SDK
-请在退出程序前调用本接口，以避免缓存内的数据丢失:
-```ruby
-# 关闭并退出 SDK
-ta.close
-```
-
-#### 6 其他说明
-默认情况下，除初始化参数不合法外，其他 Error 会被忽略，如果您希望自己处理接口调用中的 Error，可以传入自定义的 error handler.
-
-```ruby
-# (可选) 定义一个错误处理器，当出现 Error 时会调用
-class MyErrorHandler < TDAnalytics::ErrorHandler
-  def handle(error)
-      puts error
-      raise error
-  end
-end
-my_error_handler = MyErrorHandler.new
-
-# 创建 TA 实例, 第一个参数为任意一种 Consumer， 第二个参数可选，如果设定了会在出错时调用
-ta = TDAnalytics::Tracker.new(consumer, my_error_handler, uuid: true)
-```
-uuid 如果为 true，每条数据都会被带上随机 UUID 作为 #uuid 属性的值上报，该值不会入库，仅仅用于后台做数据重复检测.
+# ThinkingData SDK for Ruby
+
+<img src="https://user-images.githubusercontent.com/53337625/205621683-ed9b97ef-6a52-4903-a2c0-a955dddebb7d.png" alt="logo" width="50%"/>
+
+This is the [ThinkingData](https://www.thinkingdata.cn)™ SDK for Ruby. Documentation is available on our help center in the following languages:
+
+- [English](https://docs.thinkingdata.cn/ta-manual/latest/en/installation/installation_menu/server_sdk/ruby_sdk_installation/ruby_sdk_installation.html)
+- [中文](https://docs.thinkingdata.cn/ta-manual/latest/installation/installation_menu/server_sdk/ruby_sdk_installation/ruby_sdk_installation.html)
+- [日本語](https://docs.thinkingdata.io/ta-manual/v4.0/ja/installation/installation_menu/server_sdk/ruby_sdk_installation/ruby_sdk_installation.html)
+
+---

data/demo/demo.rb

@@ -1,142 +1,104 @@
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
-
-require 'thinkingdata-ruby'
-require 'time'
-#require 'pry'
-
-if __FILE__ == $0
-  # 替换 DEMO_APPID 为您项目的 APP ID
-  DEMO_APPID = 'APPID'
-  # 替换 SERVER_URL 为您项目的 URL
-  SERVER_URL = 'https://sdk.tga.thinkinggame.cn'
-  # 账号 ID
-  DEMO_ACCOUNT_ID = 'ruby_demo_aid'
-  # 访客 ID
-  DEMO_DISTINCT_ID = 'ruby_demo_did'
-
-  # (可选) 定义一个错误处理器，当出现 Error 时会调用
-  class MyErrorHandler < TDAnalytics::ErrorHandler
-    def handle(error)
-      puts error
-      raise error
-    end
-  end
-  my_error_handler = MyErrorHandler.new
-
-  # 定义 consumer: consumer 实现了 add、flush、close 等接口，将经过 SDK 格式化的数据以不同的方式存储或者发送到接收端
-  consumer = nil
-  $ARGV = 1
-  case $ARGV
-  when 0
-    # LoggerConsumer，数据将写入本地文件(当前目录，按小时切分，前缀为 demolog)，需要配合 Logbus 上传数据到 TA 服务器
-    consumer = TDAnalytics::LoggerConsumer.new '.', 'hourly', prefix: 'demolog'
-  when 1
-    # DebugConsumer，数据将被逐条同步的上报到 TA 服务器。出错时会返回详细的错误信息
-    consumer = TDAnalytics::DebugConsumer.new(SERVER_URL, DEMO_APPID)
-    # 如果不想上传到TA，只想校验数据格式，可以如下初始化
-    # consumer = TDAnalytics::DebugConsumer.new(SERVER_URL, DEMO_APPID,false)
-  when 2
-    # BatchConsumer，数据将先存入缓冲区，达到指定条数时上报，默认为 20 条
-    consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, DEMO_APPID, 30)
-    #设置是否压缩数据，默认gzip压缩，内网可以这样设置
-    #consumer._set_compress(false)
-  else
-    # LoggerConsumer，数据将写入本地文件(当前目录，按天切分，前缀为 tda.log)，需要配合 Logbus 上传数据到 TA 服务器
-    consumer = TDAnalytics::LoggerConsumer.new
-  end
-
-  # 创建 TA 实例, 第一个参数为任意一种 Consumer， 第二个参数可选，如果设定了会在出错时调用
-  ta = TDAnalytics::Tracker.new(consumer, my_error_handler, uuid: true)
-
-  # 定义公共属性
-  super_properties = {
-      super_string: 'super_string',
-      super_int: 1,
-      super_bool: false,
-      super_date: Time.rfc2822("Thu, 26 Oct 2019 02:26:12 +0545")
-  }
-
-  # 设置公共事件属性，公共事件属性会添加到每个事件中
-  ta.set_super_properties(super_properties)
-
-  # 定义事件数据
-  event = {
-      # 事件名称 （必填)
-      event_name: 'test_event',
-      # 账号 ID （可选)
-      account_id: DEMO_ACCOUNT_ID,
-      # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-      distinct_id: DEMO_DISTINCT_ID,
-      # 事件时间 (可选) 如果不填，将以调用接口时的时间作为事件时间
-      time: Time.now,
-      # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
-      ip: '202.38.64.1',
-      # 事件属性 (可选)
-      properties: {
-          array: ["str1", "11", "22.22", "2020-02-11 17:02:52.415"],
-          prop_date: Time.now,
-          prop_double: 134.1,
-          prop_string: 'hello world',
-          prop_bool: true,
-      },
-  }
-
-  # 上报事件
-  5.times do
-    ta.track(event)
-    ta.clear_super_properties
-  end
-
-  # 定义用户属性数据
-  user_data = {
-      # 账号 ID （可选)
-      account_id: DEMO_ACCOUNT_ID,
-      # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-      distinct_id: DEMO_DISTINCT_ID,
-      # 用户属性
-      properties: {
-          array: ["str1", 11, 22.22],
-          prop_date: Time.now,
-          prop_double: 134.12,
-          prop_string: 'hello',
-          prop_int: 666,
-      },
-  }
-  # 设置用户属性, 覆盖同名属性
-  ta.user_set(user_data)
-
-  #追加user的一个或者多个列表的属性
-  user_data_arr = {
-      # 账号 ID （可选)
-      account_id: DEMO_ACCOUNT_ID,
-      # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
-      distinct_id: DEMO_DISTINCT_ID,
-      # 用户属性
-      properties: {
-          array: ["33", "44"],
-      },
-  }
-
-  ta.user_append(user_data_arr)
-
-  # 设置用户属性，不会覆盖已经设置的同名属性
-  user_data[:properties][:prop_int_new] = 800
-  ta.user_set_once(user_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)
-
-  #binding.pry
-
-  # 退出前调用此接口
-  ta.close
-end
-
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'thinkingdata-ruby'
+require 'time'
+
+if __FILE__ == $0
+
+  class MyErrorHandler < ThinkingData::TDErrorHandler
+    def handle(error)
+      puts error
+      raise error
+    end
+  end
+
+  def logger_consumer
+    ThinkingData::TDLoggerConsumer.new('./log', 'hourly')
+  end
+
+  def debug_consumer
+    ThinkingData::TDDebugConsumer.new("serverUrl", "appId", device_id: "123456789")
+  end
+
+  def batch_consumer
+    consumer = ThinkingData::TDBatchConsumer.new("serverUrl", "appId", 50)
+    consumer._set_compress(false)
+    consumer
+  end
+
+  ThinkingData::set_stringent(false)
+  ThinkingData::set_enable_log(true)
+  my_error_handler = MyErrorHandler.new
+
+  td_sdk = ThinkingData::TDAnalytics.new(logger_consumer, my_error_handler, uuid: false)
+  # td_sdk = ThinkingData::TDAnalytics.new(debug_consumer, my_error_handler, uuid: true)
+  # td_sdk = ThinkingData::TDAnalytics.new(batch_consumer, my_error_handler, uuid: true)
+
+  DEMO_ACCOUNT_ID = '123'
+  DEMO_DISTINCT_ID = 'aaa'
+
+  super_properties = {
+      super_string: 'super_string',
+      super_int: 1,
+      super_bool: false,
+      super_date: Time.rfc2822("Thu, 26 Oct 2019 02:26:12 +0545"),
+      '#app_id': "123123123123123"
+  }
+
+  td_sdk.set_super_properties(super_properties)
+
+  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,
+    '#ip': '123.123.123.123',
+  }
+
+  td_sdk.set_dynamic_super_properties do
+    {:dynamic_time => Time.now}
+  end
+
+  td_sdk.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: properties)
+
+  td_sdk.clear_dynamic_super_properties
+  td_sdk.clear_super_properties
+
+  td_sdk.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,
+  }
+  td_sdk.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_data)
+
+  user_append_data = {
+    array: %w[33 44]
+  }
+  td_sdk.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_append_data)
+
+  user_uniq_append_data = {
+    array: %w[44 55]
+  }
+  td_sdk.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,
+  }
+  td_sdk.user_set_once(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_set_once_data)
+
+  td_sdk.user_add(distinct_id: DEMO_DISTINCT_ID, properties: {prop_int: 10, prop_double: 15.88})
+
+  td_sdk.user_unset(distinct_id: DEMO_DISTINCT_ID, property: [:prop_string, :prop_int])
+
+  td_sdk.user_del(distinct_id: DEMO_DISTINCT_ID)
+
+  td_sdk.flush
+
+  td_sdk.close
+end
+