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:

您也可以传入自己实现的 Consumer，只需实现以下接口:

add(message):

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 安全退出



293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 293

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 会触发上报



280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 280

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, first_check_id: nil, skip_local_check: false) ⇒ Object

上报事件. 每个事件都包含一个事件名和 Hash 对象的时间属性. 其参数说明如下:

event_name: (


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

def track(event_name: nil, distinct_id: nil, account_id: nil, properties: {}, time: nil, ip: nil,first_check_id: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[:first_check_id] = first_check_id if first_check_id
  data[:properties] = properties

  _internal_track(:track, data)
end

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

上报事件数据可进行更新. 每个事件都包含一个事件名和事件ID以及 Hash 对象的时间属性. 其参数说明如下:

event_name: (


103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 103

def track_overwrite(event_name: nil,event_id: nil, distinct_id: nil, account_id: nil, properties: {}, time: nil, ip: nil, skip_local_check: false)
  begin
    _check_name event_name
    _check_event_id event_id
    _check_id(distinct_id, )
    unless skip_local_check
      _check_properties(:track_overwrite, properties)
    end
  rescue TDAnalyticsError => e
    @error_handler.handle(e)
    return false
  end

  data = {}
  data[:event_name] = event_name
  data[:event_id] = event_id
  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_overwrite, data)
end

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

上报事件数据可进行覆盖. 每个事件都包含一个事件名和事件ID以及 Hash 对象的时间属性. 其参数说明如下:

event_name: (


138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 138

def track_update(event_name: nil,event_id: nil, distinct_id: nil, account_id: nil, properties: {}, time: nil, ip: nil, skip_local_check: false)
  begin
    _check_name event_name
    _check_event_id event_id
    _check_id(distinct_id, )
    unless skip_local_check
      _check_properties(:track_update, properties)
    end
  rescue TDAnalyticsError => e
    @error_handler.handle(e)
    return false
  end

  data = {}
  data[:event_name] = event_name
  data[:event_id] = event_id
  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_update, data)
end

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

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

distinct_id: (


248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 248

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

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



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 202

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

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



265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 265

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: (


166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 166

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 相同



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 184

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 值数组



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/thinkingdata-ruby/tracker.rb', line 219

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