目录
此内容是否有帮助?

# 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.
  • イベントの報告とユーザー属性の報告をサポートします
  • サポートパブリックイベントプロパティ.