目录
此内容是否有帮助?

# Lua SDK 使用ガイド

このガイドでは、Lua SDK を使用してプロジェクトにアクセスする方法を説明し (opens new window)ます。

**最新バージョン:**バージョン: 1.2.0

更新時間は、2021-03-12です

# 1.統合準備

# a)SDK のダウンロード

公式のアドレスで ThinkingDataSdk.lua と Util.lua テキストをダウンロードします

# b)統合 SDK

ダウンロードした SDK テキストを package.path に入れると、直接参照できます

# 2.SDK の初期化

SDK インスタンスを取得するには、次の 3 つの方法があります(他の Consumer コンストラクタのオーバーロードは API ドキュメントを参照してください)

# a)LogConsumer

**LogConsumer:**一括でローカルテキストを書き、テキストは日や時間で区切られ、LogBus と一緒にアップロードする必要が

--LogConsumer
local TdSDK = require "ThinkingDataSdk"
local LOG_DIRECTORY = "/tmp/data" --必传，本地文件路径
local fileNamePrefix = "td" --可选参数，生成的文件前缀，生成的文件格式为td.log.%Y-%m-%d-%H_0，默认格式为log.%Y-%m-%d-%H_0
local batchNum = 15 --可选参数，设置每次保存的条数，即每15条保存一次，默认值为10
local fileSize = 15 --可选参数，每个文件大小上限，单位为M，默认不设上限
local rule = TdSDK.LOG_RULE.HOUR --可选参数，分隔文件的方式，可选为HOUR或DAY，即按小时划分或按天划分，默认按天划分
local consumer = TdSDK.LogConsumer(LOG_DIRECTORY, rule, batchNum, fileSize, fileNamePrefix)
local td = TdSDK(consumer)

LOG_DIRECTORYローカルフォルダアドレスを書き込むには、LogBus のフォルダアドレスをここに設定するだけで、LogBus を使用してデータをアップロードできます。

# b)バッチコンシューマー

**BatchConsumer:**一括で TA サーバーにデータを転送するため、転送ツールは必要ありません。アップロードごとの最大数(デフォルト 20)とキャッシュの最大バッチ数(デフォルト 50)を設定できます。デフォルトの最大キャッシュ数は 20*50 本です。長時間ネットワークが中断した場合、データが失われるリスクがある。

--BatchConsumer
local TdSDK = require "ThinkingDataSdk"
local APP_ID = "APPKEY"
local SERVER_URI = "http://host:port"
local consumer = TdSDK.BatchConsumer(SERVER_URI, APP_ID)
local td = TdSDK(consumer)

# c)Debug Consumer

**DebugConsumer:**データを TA サーバーに 1 つずつ転送し、データ検証エラー時に例外をスローしてデータデバッグ

--DebugConsumer
local TdSDK = require "ThinkingDataSdk"
local APP_ID = "APPKEY"
local SERVER_URI = "http://host:port"
local consumer = TdSDK.DebugConsumer(SERVER_URI, APP_ID)
local td = TdSDK(consumer)

SERVER_URIは転送データの uri、APP_IDはプロジェクトの APP ID

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

http://ta-receiver.thinkingdata.io

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

http://数据采集地址

# 3.送信イベント

SDK の初期化が完了すると、trackを呼び出してイベントをアップロードできます。通常、ダースから数百の異なるイベントをアップロードする必要があります。TGA のバックグラウンドを初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

どのようなイベントを送信する必要があるか疑問がある場合は、クイッククイックガイドください。

# a)送信イベント

を呼び出してtrackイベントをアップロードすることができます。イベントの属性と情報を送信する条件を設定することをお勧めします。

--初始化SDK
local TdSDK = require "ThinkingDataSdk"
local APP_ID = "APPKEY"
local SERVER_URI = "http://host:port"
local consumer = TdSDK.BatchConsumer(SERVER_URI, APP_ID)
local td = TdSDK(consumer)

--设置访客ID"ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"

--设置账号ID"TA_10001"
local accountId = "TA_10001"

--设置事件属性
local properties = {}

--设置事件发生的时间，如果不设置的话，则默认使用为当前时间
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--设置用户的ip地址，TA系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "月卡"
properties["Price"] = 30
properties["OrderId"] = "abc_123"

--上传事件，包含用户的访客ID与账号ID，请注意账号ID与访客ID的顺序
sdk:track(distinctId, accountId, "payment", properties)
properties = nil

**注:**ビジター ID とアカウント ID がスムーズにバインドされることを保証するために、ゲームにビジター ID とアカウント ID が使用される場合は、この 2 つの ID を同時にアップロードすることを強くお勧めします。そうしないと、アカウントが一致しない状況が発生し、ユーザーが計算を繰り返すことになります。具体的な ID バインドルールはユーザー識別ルールの章を参考ユーザー識別ルールにしてください。

  • イベントの名前はString型で、文字のみで始まり、数字、文字、下線「_」を含めることができ、最大 50 文字の長さで、文字の大文字と小文字には敏感ではない。
  • イベントのプロパティはtableオブジェクトで、各要素はプロパティを表します。
  • Key の値はプロパティの名前で、String型で、指定はプリセットプロパティ、または文字で始まり、数字、文字、下線「_」を含み、最大 50 文字で、文字の大文字と小文字には敏感ではない。
  • Value は、String、String、Number、Boolean、DateをArray。

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

すべてのイベントに表示する必要があるいくつかのプロパティについては、setSuperPropertiesトラックを使用してアップロードされたすべてのトラックできます。

local superProperties = {}
--设置公共属性：服务器名称
superProperties["server_name"] = "S10001"
--设置公共属性：服务器版本
superProperties["server_version"] = "1.2.3"
--设置公共事件属性
sd:setSuperProperties(superProperties)
superProperties = nil

local properties = {}
--设置事件属性
properties["Product_Name"] = "月卡"
properties["Price"] = 30
--上传事件，此时事件中将带有公共属性以及该事件的属性
sd:track(accountId, distinctId, "payment", properties)
properties = nil
  • 共通イベントプロパティもtableオブジェクトで、各要素はプロパティを表します。
  • Key の値はプロパティの名前で、String型で、指定はプリセットプロパティ、または文字で始まり、数字、文字、下線「_」を含み、最大 50 文字で、文字の大文字と小文字には敏感ではない。
  • Value は、String、String、Number、Boolean、DateをArray。

を呼び出し呼び出し以前に設定された共通イベントプロパティを設定すると、以前のプロパティ値が上書きされます。パブリックイベントプロパティとtrackuploadイベントのプロパティの Key が重複する場合、イベントのプロパティはパブリックイベントプロパティを上書きします

local superProperties = {}
superProperties["server_name"] = "S10001"
superProperties["server_version"] = "1.2.3"
--设置公共事件属性
sd:setSuperProperties(superProperties)
superProperties = {}
superProperties["server_name"] = "Q12345"
--再次设置公共事件属性，此时"server_name"被覆盖，值为"Q12345"
sd:setSuperProperties(superProperties)

local properties = {}
properties["Product_Name"] = "月卡"
--设置与公共事件属性重复的属性
superProperties["server_version"] = "1.2.4"
--上传事件，此时"server_version"的属性值会被覆盖为"1.2.4"，"server_name"的值为"Q12345"
sd:track(accountId, distinctId, "payment", properties)

すべてのパブリックイベントプロパティを空にする場合は、clearSuperProperties を呼び出します。

# 4.ユーザープロパティ

TGA プラットフォームで現在サポートされているユーザープロパティ設定インターフェイスは userSet、userUnset、userSetOnce、userAdd、userDel、userAppend です。

# a)ユーザーセット

一般的なユーザープロパティでは、userSetて設定できます。このインターフェイスを使用してアップロードされたプロパティは、元のプロパティ値を上書きします。ユーザープロパティが以前に存在しなかった場合は、新しいユーザープロパティが作成されます。ユーザープロパティのタイプは、受信プロパティのタイプと一致します。たとえば、プレイヤーがユーザー名を設定します

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性
sd:userSet(accountId, distinctId, userSetProperties)

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
//再次上传用户属性，此时"user_name"的值会被覆盖为"abc"
sd:userSet(accountId, distinctId, userSetProperties)
  • userSet設定のユーザープロパティはtableオブジェクトで、各要素はプロパティを表します。
  • Key の値はプロパティの名前で、string型で、文字で始まることができ、数字、文字、下線「_」を含み、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない。
  • Value は、String、String、Number、Boolean、DateをArray。

# b)ユーザー SetOnce

アップロードするユーザープロパティが一度設定されている場合は、userSetOnce を呼び出して設定することができます。プロパティに値がある場合は、この情報を無視して、たとえばプレイヤーユーザー名を設定します

local userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "ABC"
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，新建"user_name"，值为"ABC"
sd:userSetOnce(accountId, distinctId, userSetOnceProperties)

userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "abc"
userSetOnceProperties["user_age"] = 18
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--再次上传用户属性，此时"user_name"的值不会被覆盖，仍为"ABC"，"user_age"的值为18
sd:userSetOnce(accountId, distinctId, userSetOnceProperties)

userSetOnce設定のユーザープロパティの種類と制限はuserSet一致します。

# c）userAdd

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

local userAddProperties = {}
userAddProperties["total_revenue"] = 30
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，此时"total_revenue"的值为30
sd:userAdd(accountId, distinctId, userAddProperties)

userAddProperties = {}
userAddProperties["total_revenue"] = 60
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--再次上传用户属性，此时"total_revenue"的值会累加为90
sd:userAdd(accountId, distinctId, userAddProperties)

userAdd設定のユーザープロパティの種類と制限はuserSet一致しますが、渡された数値型のユーザープロパティのみがサポートされます。

# d)userAppend

に要素をArrayプロパティ値に要素を追加する必要がある場合は、userAppend を呼び出してリストに追加操作を行うことができます。ここでは装備リストを例にとる

local equips = {}
equips[1] = "weapon"
equips[2] = "hat"
local userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--上传用户属性，此时"equips"的值为["weapon", "hat"]
sd:userAppend(accountId, distinctId, userAppendProperties)

equips = {}
equips[1] = "clothes"
userAppendProperties = {}
userAppendProperties["equips"] = "clothes"
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--再次上传用户属性，此时"equips"的值会增加一个"clothes":["weapon", "hat", "clothes"]
sd:userAppend(accountId, distinctId, userAppendProperties)

userAppend設定のユーザープロパティタイプは Array タイプのみをサポートArrayタイプのみをサポートし、他のタイプは無視されます。

# e）userUnset

プロパティを空にする必要がある場合は、userUnsetを呼び出して空にする(つまり NULL に設定する)ことができます。

local userUnsetProperties = {}
userUnsetProperties[1] = "total_revenue"
userUnsetProperties[2] = "equips"
--上传用户属性，此时将会重置"total_revenue"和"equips"两个属性
sd:userUnset(accountId, distinctId, userUnsetProperties)

# f)userDel

を削除する場合、userDel を呼び出して削除すると、そのユーザーのユーザー属性を照会することはできませんが、そのユーザーが発生したイベントはまだ照会できます。この操作は不可逆的な結果を生む可能性がありますので、注意してください

sd:userDel(accountId, distinctId)

# 5.その他の操作

# a）データの即時提出

sd:flush()

すぐに対応する受信機にデータを送信

# b)SDK を閉じる

sd:close()

sdk を閉じて終了するには、サーバーを閉じる前にこのインターフェイスを呼び出して、キャッシュ内のデータが失わ

# チェンジログ

# v1.2.0 2021/03/12

  • BatchConsumer モードを追加すると、最大キャッシュ値

# v1.1.1 2021/02/23

  • DebugConsumer モードの debugOnly 機能を追加
  • BatchConsumer モードは、ネットワークの問題で送信に失敗した場合、データを削除

# v1.1.0 2021/01/13

  • 指定されたテキストサイズでテキストを生成できないエラーを修正

# v1.0.0 2020/11/20

  • Lua SDK バージョン 1.0.0 オンライン