目录
此内容是否有帮助?

# Ruby SDK使用ガイド

このガイドでは、Ruby SDKを使用してプロジェクトにアクセスする方法について説明します。にアクセスしてGitHub (opens new window)Ruby SDKのソースコードを入手できます。

最新バージョン: 1.2.0

更新時間は: 2020-08-28

# I.統合SDK

# 1.1 SDKのインストール

を使用してgemコマンドを使用してSDKパッケージ

# 获取 SDK
gem install thinkingdata-ruby

# 1.2 SDKインスタンスの作成

まずはコードブック冒頭にthinkingdata-rubyを導入導入:

require 'thinkingdata-ruby'

SDKを使用してデータをアップロードするには、まずTDAnalyticsTDAnalytics::Tracker必要があります。TDAnalytics::Trackerは、イベントデータとユーザー属性データを報告できるデータ報告のコアクラスです。作成Trackerオブジェクトの作成にはは、consumerconsumerオブジェクトが必要です（ローカルログブックに保存するかサービスにアップロードするか）。

# 创建Tracker对象
ta = TDAnalytics::Tracker.new(consumer)

# 上报数据
ta.track('your_event', distinct_id: 'distinct_id_of_user')

TDAnalyticsは3つの消費者実装を提供

(1)LoggerConsumer:データをリアルタイムでローカルテキストに書き込んで、テキストを日/時間で分割し、LogBusと組み合わせてデータアップロードを行う必要があり、本番環境での使用

# 默认写入当前目录的文件，按日期命名(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と受信側アドレスを初期化します。本番環境で使用しないように注意

# 创建 DebugConsumer
consumer = TDAnalytics::DebugConsumer.new(SERVER_URL, YOUR_APPID)

データを入庫したくない場合、データ形式をチェックしたい場合は、次のようにコードを初期化できます

# 创建 DebugConsumer
consumer = TDAnalytics::DebugConsumer.new(SERVER_URL, DEMO_APPID,false)

SERVER_URLは転送データのURL、YOUR_APPIDはプロジェクトのAPP ID

クラウドサービスを使用している場合は、次のURLを入力してください

http://ta-receiver.thinkingdata.io/

民営化された展開のバージョンを使用している場合は、次のURLを入力してください

http://数据采集地址

(3)BatchConsumer:一括でリアルタイムにTAサーバにデータを転送し、転送ツールを組み合わせる必要はない。ネットワークの状態が悪い場合、データの損失につながる可能性があるため、本番環境での多用は推奨されません着信プロジェクトのAPP IDと受信アドレスを初期化します。

BatchConsumerは最初にデータをバッファに格納し、データバーの数が設定されたバッファの最大値(max_buffer_length、デフォルトは20)を超えると報告をトリガーしますまた、SDKの初期化時に整数型のパラメータを渡してバッファサイズを設定することもできます

 # BatchConsumer，数据将先存入缓冲区，达到指定条数时上报，默认为 20 条
 consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, YOUR_APPID)

 # 创建指定缓冲区大小为 3 条的 BatchConsumer
 #consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, YOUR_APPID, 3)

 #设置是否压缩数据，默认true代表gzip压缩，内网可以这样设置
 #consumer = TDAnalytics::BatchConsumer.new(SERVER_URL, YOUR_APPID)
 #consumer._set_compress(false)

SERVER_URLは転送データのURL、YOUR_APPIDはプロジェクトのAPP ID

クラウドサービスを使用している場合は、次のURLを入力してください

http://ta-receiver.thinkingdata.io/

を使用している場合は、次のURLを入力してください

http://数据采集地址/

注:バージョン1.0.0次のURLを入力します。

http://ta-receiver.thinkingdata.io/logagent
http://数据采集地址/logagent

次のインターフェイスを実装するだけで、独自のConsumerを呼び出すこともできます

  • add(message):(必須)Hash型のデータオブジェクトを
  • flush:(オプション)バッファのデータを指定されたアドレス
  • close:(オプション)プログラムが終了すると、ユーザーはこのインターフェイスをアクティブに呼び出して安全に終了

# 二、データを報告する

SDKの初期化が完了すると、次のインターフェイスを使用してデータを報告

# 2.1送信イベント

を呼び出してtrackイベントをアップロードできます。事前に整理したドキュメントに基づいて、イベントのプロパティと情報を送信する条件を設定することをお勧めします。アップロードイベントの例は次のとおりです。

# 定义事件数据
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、数値型、String、数値型、bool、Time、配列型

SDKはローカルでデータ形式をチェックします。ローカルチェックをスキップする場合は、trackインターフェイスを呼び出すときにskip_local_checkパラメーターを渡します

# 2.2パブリックイベントプロパティの設定

共通イベントプロパティは、各イベントに含まれるプロパティです。通常の共通プロパティは固定値です。イベントに値を入力してイベントに追加する動的共通プロパティも設定できます。同じプロパティがある場合、動的共通プロパティは共通イベントプロパティを上書きします。

# 定义公共属性
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

# 2.3ユーザー属性

# 2.3.1 user_set

一般的なユーザープロパティでは、user_setを呼び出して設定できますこのインターフェイスを使用してアップロードされたプロパティは、元のプロパティ値を上書きします(受信したプロパティは変更されません。以下同じです)。

# 定义用户属性数据
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);

# 2.3.2 user_set_once

アップロードするユーザープロパティが一度だけ設定されている場合は、user_set_onceを呼び出して設定することができます。プロパティに値がある場合は、この情報を無視して、受信値が最初に受信された値であることを確認します。

# 设置用户属性，如果该用户的该属性有值，则忽略新设置属性
ta.user_set_once(user_data);

# 2.3.3 user_add

数値型のプロパティをアップロードするときは、user_addを呼び出してプロパティを累積的に操作できます。プロパティが設定されていない場合は、0を割り当ててから計算します

# 对数值类型的属性进行累加操作
ta.user_add(distinct_id: 'ruby_distinct_id', properties: {prop_int: 10, prop_double: 15.88})

# 2.3.4 user_unset

ユーザーのユーザープロパティの値を空にする必要がある場合は、user_unsetを呼び出して空にすることができます

# 清空某个用户的某个用户属性
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))

# 2.3.5 user_append

ユーザープロパティの値をarray型に追加する場合は、user_appendを呼び出して、指定したプロパティを追加でき。、プロパティを

 #追加user的一个或者多个列表的属性
 user_data_arr = {
     # 账号 ID （可选)
     account_id: ACCOUNT_ID,
     # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
     distinct_id: DISTINCT_ID,
     # 用户属性
     properties: {//key-array形式上传，array里面数据最后都会toString
         array: ["11", "22"],
     },
 }
 ta.user_append(user_data_arr)

# 2.3.6 user_del

# 删除用户
ta.user_del(
	# 账号 ID （可选)
	account_id: 'ruby_test_aid',
	# 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
	distinct_id: 'ruby_distinct_id',
);

ユーザーを削除する場合は、user_delを呼び出してユーザーを削除できますその後、ユーザーのユーザー属性を照会することはできませんが、ユーザーが生成したイベントは引き続き照会でき

# 删除用户
ta.user_del(
	# 账号 ID （可选)
	account_id: 'ruby_test_aid',
	# 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空
	distinct_id: 'ruby_distinct_id',
);

# 三、高度な機能

v1.2.0以降、SDKでは、更新可能イベントと書き換え可能イベントの2種類のイベントの報告がサポートされています。両方のイベントは、TAシステム2.8以降のバージョンで使用する必要があります。特殊事件は特定の場面でしか適用されないので、数科学技術の顧客成功とアナリストの助けを得て、特殊事件を使ってデータを報告してください。

# 3.1更新可能イベント

更新可能なイベントを使用すると、特定のシナリオでイベントデータを変更する必要がある要件を満たすことができます。更新可能なイベントには、イベントを識別するIDを指定し、更新可能なイベントオブジェクトを作成するときに着信する必要があります。TAバックグラウンドは、イベント名とイベントIDに基づいて更新するデータを決定します。

// 示例： 上报可被更新的事件，假设事件名为 event_update
event_name = 'event_update'
event_id = '123'
account_id = '123'
distinct_id: '65478cc0-275a-4aeb-9e6b-861155b5aca7'
prop = {
          price: 100,
          status: 3,
      }
      // 上报后事件属性 status 为 3, price 为 100
 event_update = {
      # 事件名称 （必填) string
      event_name:event_name,
      # 事件ID (必填) string
      event_id: event_id,
      # 账号 ID （可选)string
      account_id:account_id,
      # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空 string
      distinct_id: distinct_id,
      # 事件时间 (可选) 如果不填，将以调用接口时的当前时间作为事件时间
      time: Time.now,
      # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
      ip: '202.38.64.1',
      # 事件属性 (可选)
      properties: prop,
  }
 ta.track_update(event_update)

// 上报后同样event_name + event_id 的事件属性 status 被更新为 5, price 不变
_new_proterties = {
  status: 5,
}
 event_update = {
      event_name:event_name,
      event_id: event_id,
      account_id:account_id,
      distinct_id: distinct_id,
      time: Time.now,
      ip: '202.38.64.1',
      properties: _new_proterties,
  }
ta.track_update(event_update)

# 3.2書き換え可能イベント

書き換え可能イベントは更新可能イベントと類似しており、書き換え可能イベントは最新のデータで履歴データを完全にカバーし、効果的には前のデータを削除し、最新のデータを入庫することに相当する。TAバックグラウンドは、イベント名とイベントIDに基づいて更新するデータを決定します。

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
event_name = 'event_overwrite'
event_id = '123'
account_id = '123'
distinct_id: '65478cc0-275a-4aeb-9e6b-861155b5aca7'
prop = {
          price: 100,
          status: 3,
      }
      // 上报后事件属性 status 为 3, price 为 100
 event_overwrite = {
      # 事件名称 （必填) string
      event_name:event_name,
      # 事件ID (必填) string
      event_id: event_id,
      # 账号 ID （可选)string
      account_id:account_id,
      # 访客 ID （可选)，账号 ID 和访客 ID 不可以都为空 string
      distinct_id: distinct_id,
      # 事件时间 (可选) 如果不填，将以调用接口时的当前时间作为事件时间
      time: Time.now,
      # 事件 IP (可选) 当传入 IP 地址时，后台可以解析所在地
      ip: '202.38.64.1',
      # 事件属性 (可选)
      properties: prop,
  }
 ta.track_overwrite(event_overwrite)

// 上报后同样event_name + event_id 的事件属性 status 被更新为 5, price 属性被删除

_new_prop = {
  status: 5,
}
 event_overwrite = {
      event_name:event_name,
      event_id: event_id,
      account_id:account_id,
      distinct_id: distinct_id,
      time: Time.now,
      ip: '202.38.64.1',
      properties: _new_prop,
  }
ta.track_overwirte(event_overwrite)

# 四、その他の操作

# 4.1即時のデータIO

この操作は、特定のConsumer実装に関連しています。データを受信すると、Consumerは最初にデータをバッファに格納し、特定の状況で実際のデータIO操作をトリガーして、全体的なパフォーマンスを向上させることができます。場合によっては、すぐにデータを送信する必要があり、flushインターフェイスを呼び出すことができます

# 立即提交数据到相应的接收端
ta.flush

# 4.2 SDKのシャットダウン

プログラムを終了する前にこのインターフェイスを呼び出して、キャッシュ内のデータが失われないようにしてください

# 关闭并退出 SDK
ta.close

# 4.3例外処理

デフォルトでは、初期化パラメーターが有効でない場合を除き、他のエラーは無視されます。インターフェイス呼び出しでエラーを処理する場合は、カスタムエラーハンドラを呼び出すことができます

# (可选) 定义一个错误处理器，当出现 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属性の値として報告されます。この値はライブラリに格納されず、バックグラウンドでのデータ重複検出にのみ使用されます

# チェンジログ

# v1.2.0 (2020/08/28)

  • 更新可能なイベントをサポートする新しいtrack_updateインターフェイス
  • 新しいtrack_overwriteインターフェイス、書き換え可能イベント

# v1.1.0 (2020/02/11)

  • データ型はarray型
  • ユーザーの配列型の属性追加をサポートするuser_appendインターフェイスを追加
  • BatchConsumerパフォーマンスの最適化:圧縮するかどうかの選択をサポートします。Base64エンコーディング
  • DebugConsumer最適化:サービス側でデータをより完全かつ正確に検証

# v1.0.0 (2019-11-20)

  • 3つのモードをサポート: DebugConsumer, BatchConsumer, LoggerConsumer.
  • イベントの報告とユーザー属性の報告をサポートします
  • サポートパブリックイベントプロパティ.

← LogBus 利用ガイド →