thinkingdata-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8675f2f2b9e9e65ef523eb61d868ab087a048105
+  data.tar.gz: a469f38692b16bcff8d1564b954a8691b3161cbf
+SHA512:
+  metadata.gz: 48b4d1a412fe55788a7be4a5bbb357ff6613669126ce03799b4a999bb647135266b363aef32ed002163bbb551b82b675199b10e3f6ceeceb8b0abdc61276f6c4
+  data.tar.gz: 407c50cf1a0e731ca71b3c786d645cf389c16fa5bc82a13e9e708c5b718eab3edbf1a949aa229300580d4ec5e7acf0f80436660cfbd955d35a5b89e8726e784c

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+**v1.0.0** (2019-11-20)
+- 支持三种模式的上报: DebugConsumer, BatchConsumer, LoggerConsumer.
+- 支持事件上报和用户属性上报.
+- 支持公共事件属性.

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# gem "rails"

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2019 thinking-analytics / data-collector / server-sdk
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,202 @@
+# 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 属性的值上报，该值不会入库，仅仅用于后台做数据重复检测.

data/demo/demo.rb

@@ -0,0 +1,120 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'thinkingdata-ruby'
+require 'time'
+#require 'pry'
+
+if __FILE__ == $0
+  # 替换 DEMO_APPID 为您项目的 APP ID
+  DEMO_APPID = 'b2a61feb9e56472c90c5bcb320dfb4ef'
+  # 替换 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
+  case ARGV[0]
+  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)
+  when '2'
+    # BatchConsumer，数据将先存入缓冲区，达到指定条数时上报，默认为 20 条
+    consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, DEMO_APPID, 3)
+  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: {
+		  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: {
+      prop_date: Time.now,
+      prop_double: 134.12,
+      prop_string: 'hello',
+      prop_int: 666,
+    },
+  }
+  # 设置用户属性, 覆盖同名属性
+  ta.user_set(user_data)
+
+  # 设置用户属性，不会覆盖已经设置的同名属性
+  user_data[:properties][:prop_int_new] = 800
+  ta.user_set_once(user_data)
+
+  # 删除某个用户属性
+  # ta.user_unset(distinct_id: DEMO_DISTINCT_ID, property: :prop_string)
+
+  # 累加用户属性
+  ta.user_add(distinct_id: DEMO_DISTINCT_ID, properties: {prop_int: 10, prop_double: 15.88})
+
+  # 删除用户。此操作之前的事件数据不会被删除
+  # ta.user_del(distinct_id: DEMO_DISTINCT_ID)
+
+  #binding.pry
+
+  # 退出前调用此接口
+  ta.close
+end
+

data/lib/thinkingdata-ruby/batch_consumer.rb

@@ -0,0 +1,105 @@
+require 'base64'
+require 'json'
+require 'net/http'
+
+module TDAnalytics
+  # BatchConsumer 批量同步的发送数据.
+  # 有数据时，首先会加入本地缓冲区，当条数到达上限后会发起上报
+  class BatchConsumer
+    # 默认缓冲区大小
+    MAX_LENGTH = 20
+
+    def initialize(server_url, app_id, max_buffer_length=MAX_LENGTH)
+      @server_uri = URI.parse(server_url)
+      @server_uri.path = '/logagent'
+      @app_id = app_id
+      @max_length = [max_buffer_length, MAX_LENGTH].min
+      @buffers = []
+    end
+
+    def add(message)
+      @buffers << message
+      flush if @buffers.length >= @max_length
+    end
+
+    def close
+      flush
+    end
+
+    def flush
+      begin
+        @buffers.each_slice(@max_length) do |chunk|
+          wio = StringIO.new("w")
+          gzip_io = Zlib::GzipWriter.new(wio)
+          gzip_io.write(chunk.to_json)
+          gzip_io.close
+          data = Base64.encode64(wio.string).gsub("\n", '')
+
+          headers = {'Content-Type' => 'application/plaintext', 'appid' => @app_id}
+          request = CaseSensitivePost.new(@server_uri.request_uri, headers)
+          request.body = data
+
+          begin
+            response_code, response_body = _request(@server_uri, request)
+          rescue => e
+            raise ConnectionError.new("Could not connect to TA server, with error \"#{e.message}\".")
+          end
+    
+          result = {}
+          if response_code.to_i == 200
+            begin
+              result = JSON.parse(response_body.to_s)
+            rescue JSON::JSONError
+              raise ServerError.new("Could not interpret TA server response: '#{response_body}'")
+            end
+          end
+    
+          if result['code'] != 0
+            raise ServerError.new("Could not write to TA, server responded with #{response_code} returning: '#{response_body}'")
+          end
+        end
+      rescue
+        raise
+      end
+      @buffers = []
+    end
+
+    private
+    def _request(uri, request)
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme === 'https' ? true : false
+      client.open_timeout = 10
+      client.continue_timeout = 10
+      client.read_timeout = 10
+      client.ssl_timeout = 10
+
+      response = client.request(request)
+      [response.code, response.body]
+    end
+  end
+
+  # 内部使用，为了兼容老版本服务端，将 Header 名称限定为小写
+  class CaseSensitivePost < Net::HTTP::Post
+    def initialize_http_header(headers)
+      @header = {}
+      headers.each{|k,v| @header[k.to_s] = [v] }
+    end
+  
+    def [](name)
+      @header[name.to_s]
+    end
+  
+    def []=(name, val)
+      if val
+        @header[name.to_s] = [val]
+      else
+        @header.delete(name.to_s)
+      end
+    end
+  
+    def capitalize(name)
+      name
+    end
+  end
+
+end

data/lib/thinkingdata-ruby/debug_consumer.rb

@@ -0,0 +1,56 @@
+require 'json'
+require 'net/http'
+
+module TDAnalytics
+  # DebugConsumer 逐条、同步地向服务端上报数据
+  # DebugConsumer 会返回详细的报错信息，建议在集成阶段先使用 DebugConsumer 调试接口
+  class DebugConsumer
+
+    def initialize(server_url, app_id)
+      @server_uri = URI.parse(server_url)
+      @server_uri.path = '/sync_data'
+      @app_id = app_id
+    end
+
+    def add(message)
+      puts message.to_json
+      form_data = {"data" => message.to_json, "appid" => @app_id, "debug" => 1}
+      begin
+        response_code, response_body = request(@server_uri, form_data)
+      rescue => e
+        raise ConnectionError.new("Could not connect to TA server, with error \"#{e.message}\".")
+      end
+
+      result = {}
+      if response_code.to_i == 200
+        begin
+          result = JSON.parse(response_body.to_s)
+        rescue JSON::JSONError
+          raise ServerError.new("Could not interpret TA server response: '#{response_body}'")
+        end
+      end
+
+      puts result
+
+      if result['code'] != 0
+        raise ServerError.new("Could not write to TA, server responded with #{response_code} returning: '#{response_body}'")
+      end
+    end
+
+    def request(uri, form_data)
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request.set_form_data(form_data)
+
+      client = Net::HTTP.new(uri.host, uri.port)
+      client.use_ssl = uri.scheme === 'https' ? true : false
+      client.open_timeout = 10
+      client.continue_timeout = 10
+      client.read_timeout = 10
+      client.ssl_timeout = 10
+
+      response = client.request(request)
+      [response.code, response.body]
+    end
+  end
+
+end

data/lib/thinkingdata-ruby/errors.rb

@@ -0,0 +1,35 @@
+module TDAnalytics
+
+  # TD Analytics SDK 的错误
+  TDAnalyticsError = Class.new(StandardError)
+
+  # 参数不合法
+  IllegalParameterError = Class.new(TDAnalyticsError)
+  
+  # 网络连接错误
+  ConnectionError = Class.new(TDAnalyticsError)
+  
+  # 服务器返回错误
+  ServerError = Class.new(TDAnalyticsError)
+
+
+  # 默认情况下，所有异常都不会被抛出。如果希望自己处理异常，可以实现继承自 ErrorHandler 的
+  # 错误处理类，并在初始化 SDK 的时候作为参数传入.
+  # 例如: 
+  #    class MyErrorHandler < TDAnalytics::ErrorHandler
+  #      def handle(error)
+  #          puts error
+  #          raise error
+  #      end
+  #    end
+  #
+  #    my_error_handler = MyErrorHandler.new
+  #    tracker = TDAnalytics::Tracker.new(consumer, my_error_handler)
+  class ErrorHandler
+
+    # Override #handle to customize error handling
+    def handle(error)
+      false
+    end
+  end
+end

data/lib/thinkingdata-ruby/logger_consumer.rb

@@ -0,0 +1,57 @@
+require 'logger'
+require 'thinkingdata-ruby/errors'
+
+module TDAnalytics
+  # 将数据写入本地文件, 需配合 LogBus 将数据上传到服务器
+  # 由于 LogBus 有完善的失败重传机制，因此建议用户首先考虑此方案
+  class LoggerConsumer
+    # LoggerConsumer 构造函数
+    #   log_path: 日志文件存放目录
+    #   mode: 日志文件切分模式，可选 daily/hourly
+    #   prefix: 日志文件前缀，默认为 'tda.log', 日志文件名格式为: tda.log.2019-11-15
+    def initialize(log_path='.', mode='daily', prefix:'tda.log')
+      case mode
+      when 'hourly'
+        @suffix_mode = '%Y-%m-%d-%H'
+      when 'daily'
+        @suffix_mode = '%Y-%m-%d'
+      else
+        raise IllegalParameterError.new("#{mode} is unsupported for LoggerConsumer. Replaced it by daily or hourly")
+      end
+
+      raise IllegalParameterError.new("prefix couldn't be empty") if prefix.nil? || prefix.length == 0
+
+      @current_suffix = Time.now.strftime(@suffix_mode)
+
+      @full_prefix = "#{log_path}/#{prefix}."
+
+      _reset
+    end
+
+    def add(msg)
+      unless Time.now.strftime(@suffix_mode) == @current_suffix
+        @logger.close
+        @current_suffix = Time.now.strftime(@suffix_mode)
+        _reset
+      end
+      @logger.info(msg.to_json)
+    end
+  
+    # 关闭 logger
+    def close
+      @logger.close
+    end
+
+    private
+
+    # 重新创建 logger 对象. LogBus 判断新文件会同时考虑文件名和 inode，因此默认的切分方式会导致数据重传
+    def _reset
+      @logger = Logger.new("#{@full_prefix}#{@current_suffix}")
+      @logger.level = Logger::INFO
+      @logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{msg}\n"
+      end
+    end
+
+  end
+end

data/lib/thinkingdata-ruby/tracker.rb

@@ -0,0 +1,313 @@
+require 'securerandom'
+require 'thinkingdata-ruby/errors'
+require 'thinkingdata-ruby/version'
+
+module TDAnalytics
+  # TDAnalytics::Tracker 是数据上报的核心类，使用此类上报事件数据和更新用户属性.
+  # 创建 Tracker 类需要传入 consumer 对象，consumer 决定了如何处理格式化的数据（存储在本地日志文件还是上传到服务端).
+  #
+  #   ta = TDAnalytics::Tracker.new(consumer)
+  #   ta.track('your_event', distinct_id: 'distinct_id_of_user')
+  #
+  # TDAnalytics 提供了三种 consumer 实现:
+  #   LoggerConsumer: 数据写入本地文件
+  #   DebugConsumer: 数据逐条、同步的发送到服务端，并返回详细的报错信息
+  #   BatchConsumer: 数据批量、同步的发送到服务端
+  #
+  # 您也可以传入自己实现的 Consumer，只需实现以下接口:
+  #   add(message): 接受 hash 类型的数据对象
+  #   flush: (可选) 将缓冲区的数据发送到指定地址
+  #   close: (可选) 程序退出时用户可以主动调用此接口以保证安全退出
+  class Tracker
+
+    LIB_PROPERTIES = {
+      '#lib' => 'ruby',
+      '#lib_version' => TDAnalytics::VERSION,
+    }
+
+    # SDK 构造函数，传入 consumer 对象
+    #
+    # 默认情况下，除参数不合法外，其他 Error 会被忽略，如果您希望自己处理接口调用中的 Error，可以传入自定义的 error handler.
+    # ErrorHandler 的定义可以参考 thinkingdata-ruby/errors.rb
+    #
+    # uuid 如果为 true，每条数据都会被带上随机 UUID 作为 #uuid 属性的值上报，该值不会入库，仅仅用于后台做数据重复检测
+    def initialize(consumer, error_handler=nil, uuid: false)
+      @error_handler = error_handler || ErrorHandler.new
+      @consumer = consumer
+      @super_properties = {}
+      @uuid = uuid
+    end
+
+    # 设置公共事件属性，公共事件属性是所有事件都会带上的属性. 此方法会将传入的属性与当前公共属性合并.
+    # 如果希望跳过本地格式校验，可以传入值为 true 的 skip_local_check 参数
+    def set_super_properties(properties, skip_local_check = false)
+      unless skip_local_check || _check_properties(:track, properties)
+        @error_handler.handle(IllegalParameterError.new("Invalid super properties"))
+        return false
+      end
+      properties.each do |k, v|
+        if v.is_a?(Time)
+          @super_properties[k] = _format_time(v)
+        else
+          @super_properties[k] = v
+        end
+      end
+    end
+
+    # 清除公共事件属性
+    def clear_super_properties
+      @super_properties = {}
+    end
+
+    # 上报事件. 每个事件都包含一个事件名和 Hash 对象的时间属性. 其参数说明如下:
+    #   event_name: (必须) 事件名 必须是英文字母开头，可以包含字母、数字和 _, 长度不超过 50 个字符.
+    #   distinct_id: (可选) 访客 ID
+    #   account_id: （可选) 账号ID distinct_id 和 account_id 不能同时为空
+    #   properties: （可选) Hash 事件属性。支持四种类型的值：字符串、数值、Time、boolean
+    #   time: （可选）Time 事件发生时间，如果不传默认为系统当前时间
+    #   ip: (可选) 事件 IP，如果传入 IP 地址，后端可以通过 IP 地址解析事件发生地点
+    #   skip_local_check: (可选) boolean 表示是否跳过本地检测
+    def track(event_name:nil, distinct_id:nil, account_id:nil, properties:{}, time:nil, ip:nil, skip_local_check: false)
+      begin
+        _check_name event_name
+        _check_id(distinct_id, account_id)
+        unless skip_local_check
+          _check_properties(:track, properties)
+        end
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      data = {}
+      data[:event_name] = event_name
+      data[:distinct_id] = distinct_id if distinct_id
+      data[:account_id] = account_id if account_id
+      data[:time] = time if time
+      data[:ip] = ip if ip
+      data[:properties] = properties
+
+      _internal_track(:track, data)
+    end
+
+    # 设置用户属性. 如果出现同名属性，则会覆盖之前的值.
+    #   distinct_id: (可选) 访客 ID
+    #   account_id: （可选) 账号ID distinct_id 和 account_id 不能同时为空
+    #   properties: （可选) Hash 用户属性。支持四种类型的值：字符串、数值、Time、boolean
+    def user_set(distinct_id:nil, account_id:nil, properties:{}, ip:nil)
+      begin
+        _check_id(distinct_id, account_id)
+        _check_properties(:user_set, properties)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      _internal_track(:user_set,
+        distinct_id: distinct_id,
+        account_id: account_id,
+        properties: properties,
+        ip: ip,
+      )
+    end
+
+    # 设置用户属性. 如果有重名属性，则丢弃, 参数与 user_set 相同
+    def user_set_once(distinct_id:nil, account_id:nil, properties:{}, ip:nil)
+      begin
+        _check_id(distinct_id, account_id)
+        _check_properties(:user_setOnce, properties)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      _internal_track(:user_setOnce,
+        distinct_id: distinct_id,
+        account_id: account_id,
+        properties: properties,
+        ip: ip,
+      )
+    end
+
+    # 删除用户属性, property 可以传入需要删除的用户属性的 key 值，或者 key 值数组
+    def user_unset(distinct_id:nil, account_id:nil, property:nil)
+      properties = {}
+      if property.is_a?(Array)
+        property.each do |k|
+          properties[k] = 0
+        end
+      else
+        properties[property] = 0
+      end
+
+      begin
+        _check_id(distinct_id, account_id)
+        _check_properties(:user_unset, properties)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      _internal_track(:user_unset,
+        distinct_id: distinct_id,
+        account_id: account_id,
+        properties: properties,
+      )
+    end
+
+    # 累加用户属性, 如果用户属性不存在，则会设置为 0，然后再累加
+    #   distinct_id: (可选) 访客 ID
+    #   account_id: （可选) 账号ID distinct_id 和 account_id 不能同时为空
+    #   properties: （可选) Hash 数值类型的用户属性
+    def user_add(distinct_id:nil, account_id:nil, properties:{})
+      begin
+        _check_id(distinct_id, account_id)
+        _check_properties(:user_add, properties)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      _internal_track(:user_add,
+        distinct_id: distinct_id,
+        account_id: account_id,
+        properties: properties,
+      )
+    end
+
+    # 删除用户，用户之前的事件数据不会被删除
+    def user_del(distinct_id:nil, account_id:nil)
+      begin
+        _check_id(distinct_id, account_id)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        return false
+      end
+
+      _internal_track(:user_del,
+        distinct_id: distinct_id,
+        account_id: account_id,
+      )
+    end
+
+    # 立即上报数据，对于 BatchConsumer 会触发上报
+    def flush
+      return true unless defined? @consumer.flush
+      ret = true
+      begin
+        @consumer.flush
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+      ret
+    end
+
+    # 退出前调用，保证 Consumer 安全退出
+    def close
+      return true unless defined? @consumer.close
+      ret = true
+      begin
+        @consumer.close
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+      ret
+    end
+
+    private
+
+    # 出现异常的时候返回 false, 否则 true
+    def _internal_track(type, properties:{}, event_name:nil, account_id:nil, distinct_id:nil, ip:nil, time:Time.now)
+      if account_id == nil && distinct_id == nil
+        raise IllegalParameterError.new('account id or distinct id must be provided.')
+      end
+
+      if type == :track
+        raise IllegalParameterError.new('event name is empty for track') if event_name == nil
+        properties = {'#zone_offset': time.utc_offset / 3600.0}.merge(LIB_PROPERTIES).merge(@super_properties).merge(properties)
+      end
+
+      # 格式化 Time 类型
+      properties.each do |k, v|
+       if v.is_a?(Time)
+         properties[k] = _format_time(v)
+       end
+      end
+
+      data = {
+        '#type' => type,
+        '#time' => _format_time(time),
+        'properties' => properties,
+      }
+
+      data['#event_name'] = event_name if type == :track
+      data['#account_id'] = account_id if account_id
+      data['#distinct_id'] = distinct_id if distinct_id
+      data['#ip'] = ip if ip
+      data['#uuid'] =  SecureRandom.uuid if @uuid
+
+      ret = true
+      begin
+        @consumer.add(data)
+      rescue TDAnalyticsError => e
+        @error_handler.handle(e)
+        ret = false
+      end
+
+      ret
+    end
+
+    # 将 Time 类型格式化为数数指定格式的字符串
+    def _format_time(time)
+      time.strftime("%Y-%m-%d %H:%M:%S.#{((time.to_f * 1000.0).to_i % 1000).to_s.rjust(3, "0")}")
+    end
+
+    # 属性名或者事件名检查
+    def _check_name(name)
+      raise IllegalParameterError.new("the name of event or property cannot be nil") if name.nil?
+
+      unless name.instance_of?(String) || name.instance_of?(Symbol)
+        raise IllegalParameterError.new("#{name} is invalid. It must be String or Symbol")
+      end
+
+      unless name =~ /^[a-zA-Z][a-zA-Z0-9_]{1,49}$/
+        raise IllegalParameterError.new("#{name} is invalid. It must be string starts with letters and contains letters, numbers, and _ with max length of 50")
+      end
+      true
+    end
+
+    # 属性类型检查
+    def _check_properties(type, properties)
+      unless properties.instance_of? Hash
+        return false
+      end
+
+      properties.each do |k, v|
+        _check_name k
+        unless v.is_a?(Integer) || v.is_a?(Float) || v.is_a?(Symbol) || v.is_a?(String) || v.is_a?(Time) || !!v == v
+          raise IllegalParameterError.new("The value of properties must be type in Integer, Float, Symbol, String, and Time")
+        end
+
+        if type == :user_add
+          raise IllegalParameterError.new("Property value for user add must be numbers") unless v.is_a?(Integer) || v.is_a?(Float)
+        end
+      end
+      true
+    end
+
+    # 检查用户 ID 合法性
+    def _check_id(distinct_id, account_id)
+      raise IllegalParameterError.new("account id or distinct id must be provided.") if distinct_id.nil? && account_id.nil?
+
+      unless distinct_id.nil?
+        raise IllegalParameterError.new("The length of distinct id should in (0, 64]")  if distinct_id.to_s.length < 1 || distinct_id.to_s.length > 64
+      end
+
+      unless account_id.nil?
+        raise IllegalParameterError.new("The length of account id should in (0, 64]")  if account_id.to_s.length < 1 || account_id.to_s.length > 64
+      end
+    end
+  end
+end

data/lib/thinkingdata-ruby/version.rb

@@ -0,0 +1,3 @@
+module TDAnalytics
+  VERSION = '1.0.0'
+end

data/lib/thinkingdata-ruby.rb

@@ -0,0 +1,5 @@
+require 'thinkingdata-ruby/logger_consumer'
+require 'thinkingdata-ruby/debug_consumer'
+require 'thinkingdata-ruby/batch_consumer'
+require 'thinkingdata-ruby/tracker'
+require 'thinkingdata-ruby/errors'

data/thinkingdata-ruby.gemspec

@@ -0,0 +1,16 @@
+require File.join(File.dirname(__FILE__), 'lib/thinkingdata-ruby/version.rb')
+
+spec = Gem::Specification.new do |spec|
+  spec.name = 'thinkingdata-ruby'
+  spec.version = TDAnalytics::VERSION
+  spec.files = Dir.glob(`git ls-files`.split("\n"))
+  spec.require_paths = ['lib']
+  spec.summary = 'Official ThinkingData Analytics API for ruby'
+  spec.description = 'The official ThinkingData Analytics API for ruby'
+  spec.authors = [ 'ThinkingData' ]
+  spec.email = 'sdk@thinkingdata.cn'
+  spec.homepage = 'https://github.com/ThinkingDataAnalytics/ruby-sdk'
+  spec.license = 'Apache-2.0'
+
+  spec.required_ruby_version = '>= 2.0.0'
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: thinkingdata-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ThinkingData
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-20 00:00:00.000000000 Z
+dependencies: []
+description: The official ThinkingData Analytics API for ruby
+email: sdk@thinkingdata.cn
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- demo/demo.rb
+- lib/thinkingdata-ruby.rb
+- lib/thinkingdata-ruby/batch_consumer.rb
+- lib/thinkingdata-ruby/debug_consumer.rb
+- lib/thinkingdata-ruby/errors.rb
+- lib/thinkingdata-ruby/logger_consumer.rb
+- lib/thinkingdata-ruby/tracker.rb
+- lib/thinkingdata-ruby/version.rb
+- thinkingdata-ruby.gemspec
+homepage: https://github.com/ThinkingDataAnalytics/ruby-sdk
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.3
+signing_key: 
+specification_version: 4
+summary: Official ThinkingData Analytics API for ruby
+test_files: []