Class: TDAnalytics::Tracker

Inherits:
Object
  • Object
show all
Defined in:
lib/thinkingdata-ruby/tracker.rb

Overview

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: (可选) 程序退出时用户可以主动调用此接口以保证安全退出

Constant Summary collapse

LIB_PROPERTIES = 
{
  '#lib' => 'ruby',
  '#lib_version' => TDAnalytics::VERSION,
}

Instance Method Summary collapse

Constructor Details

#initialize(consumer, error_handler = nil, uuid: false) ⇒ Tracker

SDK 构造函数，传入 consumer 对象

默认情况下，除参数不合法外，其他 Error 会被忽略，如果您希望自己处理接口调用中的 Error，可以传入自定义的 error handler. ErrorHandler 的定义可以参考 thinkingdata-ruby/errors.rb

uuid 如果为 true，每条数据都会被带上随机 UUID 作为 #uuid 属性的值上报，该值不会入库，仅仅用于后台做数据重复检测



34
35
36
37
38
39
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 34

def initialize(consumer, error_handler = nil, uuid: false)
  @error_handler = error_handler || ErrorHandler.new
  @consumer = consumer
  @super_properties = {}
  @uuid = uuid
end

Instance Method Details

#clear_super_properties ⇒ Object

清除公共事件属性



58
59
60
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 58

def clear_super_properties
  @super_properties = {}
end

#close ⇒ Object

退出前调用，保证 Consumer 安全退出



224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 224

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

#flush ⇒ Object

立即上报数据，对于 BatchConsumer 会触发上报



211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 211

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

#set_super_properties(properties, skip_local_check = false) ⇒ Object

设置公共事件属性，公共事件属性是所有事件都会带上的属性. 此方法会将传入的属性与当前公共属性合并. 如果希望跳过本地格式校验，可以传入值为 true 的 skip_local_check 参数



43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 43

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

#track(event_name: nil, distinct_id: nil, account_id: nil, properties: {}, time: nil, ip: nil, skip_local_check: false) ⇒ Object

上报事件. 每个事件都包含一个事件名和 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 表示是否跳过本地检测



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 70

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, )
    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] =  if 
  data[:time] = time if time
  data[:ip] = ip if ip
  data[:properties] = properties

  _internal_track(:track, data)
end

#user_add(distinct_id: nil, account_id: nil, properties: {}) ⇒ Object

累加用户属性, 如果用户属性不存在，则会设置为 0，然后再累加

distinct_id: (可选) 访客 ID
account_id: （可选) 账号ID distinct_id 和 account_id 不能同时为空
properties: （可选) Hash 数值类型的用户属性



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 179

def user_add(distinct_id: nil, account_id: nil, properties: {})
  begin
    _check_id(distinct_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: ,
                  properties: properties,
  )
end

#user_append(distinct_id: nil, account_id: nil, properties: {}) ⇒ Object

追加用户的一个或多个列表类型的属性



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 133

def user_append(distinct_id: nil, account_id: nil, properties: {})
  begin
    _check_id(distinct_id, )
    _check_properties(:user_append, properties)
  rescue TDAnalyticsError => e
    @error_handler.handle(e)
    return false
  end

  _internal_track(:user_append,
                  distinct_id: distinct_id,
                  account_id: ,
                  properties: properties,
                  )
end

#user_del(distinct_id: nil, account_id: nil) ⇒ Object

删除用户，用户之前的事件数据不会被删除



196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 196

def user_del(distinct_id: nil, account_id: nil)
  begin
    _check_id(distinct_id, )
  rescue TDAnalyticsError => e
    @error_handler.handle(e)
    return false
  end

  _internal_track(:user_del,
                  distinct_id: distinct_id,
                  account_id: ,
  )
end

#user_set(distinct_id: nil, account_id: nil, properties: {}, ip: nil) ⇒ Object

设置用户属性. 如果出现同名属性，则会覆盖之前的值.

distinct_id: (可选) 访客 ID
account_id: （可选) 账号ID distinct_id 和 account_id 不能同时为空
properties: （可选) Hash 用户属性。支持四种类型的值：字符串、数值、Time、boolean



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 97

def user_set(distinct_id: nil, account_id: nil, properties: {}, ip: nil)
  begin
    _check_id(distinct_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: ,
                  properties: properties,
                  ip: ip,
  )
end

#user_set_once(distinct_id: nil, account_id: nil, properties: {}, ip: nil) ⇒ Object

设置用户属性. 如果有重名属性，则丢弃, 参数与 user_set 相同



115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 115

def user_set_once(distinct_id: nil, account_id: nil, properties: {}, ip: nil)
  begin
    _check_id(distinct_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: ,
                  properties: properties,
                  ip: ip,
  )
end

#user_unset(distinct_id: nil, account_id: nil, property: nil) ⇒ Object

删除用户属性, property 可以传入需要删除的用户属性的 key 值，或者 key 值数组



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 150

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, )
    _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: ,
                  properties: properties,
  )
end