Lua SDK 使用指南

本指南将会为您介绍如何使用 Lua SDK 接入您的项目，您可以在访问GitHub (opens new window)获取 Lua SDK 的源代码。

最新版本为： 1.4.0

更新时间为： 2022-04-26

1. 集成准备

1.1 下载 SDK

下载官方提供的地址下的 ThinkingDataSdk.lua 和 Util.lua 文件

1.2 集成 SDK

把下载的 SDK 文件放入 package.path 下即可直接引用

2. 初始化 SDK

您可以通过三种方式获得 SDK 实例（其他 Consumer 构造器的重载请参考 API 文档）：

2.1 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 进行数据的监听上传。

2.2BatchConsumer

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)

2.3DebugConsumer

DebugConsumer： 逐条向 TA 服务器传输数据，在数据校验出错时会抛出异常，用于数据调试

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

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

3. 发送事件

在 SDK 初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TGA 后台，我们推荐您先上传几个关键事件。

如果您对需要发送什么样的事件有疑惑，可以查看快速使用指南了解更多信息。

3.1 发送事件

您可以调用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(accountId, distinctId, "payment", properties)
properties = nil

注： 为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

• 事件的名称是String类型，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
• 事件的属性是一个table对象，其中每个元素代表一个属性。
• Key 的值为属性的名称，为String类型，规定只能是预置属性，或以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
• Value 为该属性的值，支持String、Number、Boolean、Date、Table和Array；Table中的内容可以包含String、Number、Boolean、Date以及Array(其中内容为字符串)； Array 中的内容可以包含Table和String

4. 用户属性

TGA 平台目前支持的用户属性设置接口为 userSet、userUnset、userSetOnce、userAdd、userDel、userAppend。

4.1 userSet

对于一般的用户属性，您可以调用userSet来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以玩家设置用户名为例：

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

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
//再次上传用户属性，此时"user_name"的值会被覆盖为"abc"
sdk:userSet(accountId, distinctId, userSetProperties)

属性格式要求与事件属性保持一致。

4.2 userSetOnce

如果您要上传的用户属性只要设置一次，则可以调用userSetOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，再以设置玩家用户名为例：

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

属性格式要求与事件属性保持一致。

4.3 userAdd

当您要上传数值型的属性时，您可以调用userAdd来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：

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

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

设置的属性key为字符串，Value 只允许为数值。

4.4 userAppend

当您需要为Array属性值添加元素时，您可以调用userAppend来对该列表进行添加操作，如果该属性还未在集群中被创建，则 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"]
sdk: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"]
sdk:userAppend(accountId, distinctId, userAppendProperties)

userAppend设置的用户属性类型仅支持Array类型，其他类型会被忽略。

4.5 userUnset

当您需要清空某些属性时，可以调用userUnset将这些属性清空（即设置成 NULL），如果某个属性不存在不会新建该属性。

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

userUnset: 的传入值为被清空属性的 Key 值。

4.6 userDel

如果您要删除某个用户，可以调用userDel将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到，该操作可能产生不可逆的后果，请慎用

sdk:userDel(accountId, distinctId)

4.7 userUniqueAppend

从v1.4.0开始，您可以通过userUniqueAppend为Array添加元素，和userAppend不同的是，userUniqueAppend会对Array内元素进行去重处理。

local profiles_append = {}
--执行之后用户属性append为["test_append"]
profiles_append["append"] = "test_append"
sdk:userAppend(accountId, distinctId, profiles_append)

local profiles_uniq_append = {}
--执行之后用户属性append为["test_append", "test_append1"]
--如果使用userAppend 则结果为["test_append", "test_append", "test_append1"]
profiles_uniq_append["append"] = {"test_append", "test_append1"}
sdk:userUniqueAppend(accountId, distinctId, profiles_uniq_append)

5. 其他操作

5.1 立即提交数据

sdk:flush()

立即提交数据到相应的接收器

5.2 关闭 sdk

sdk:close()

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

6、进阶功能

SDK 支持上报两种特殊类型事件: 可更新事件、可重写事件。这两种事件需要配合 TA 系统 2.8

及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

6.1 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

--可更新
properties = {}
properties["shop"] = "网上书城xxx"
sdk:trackUpdate(accountId, distinctId, "Payment", "事件ID", properties)
//事件ID == "事件ID"的事件"Payment"中的键为"shop"的属性值变为"网上书城xxx"，其他属性不变

6.2 可重写事件

您可以通过可重写事件实现特定场景下需要覆盖原有事件数据的需求。可重写事件需要指定标识该事件的 ID，并在创建可重写事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要覆盖的数据。

--可重写
properties = {}
properties["orderId"] = "ORDER_54321"
properties["productName"] = "Thinking in Lua hahaha"
properties["shop"] = "网上书城xxx"
sdk:trackOverwrite(accountId, distinctId, "Payment", "事件ID", properties)
//事件ID == "事件ID"的事件"Payment"的属性值变为以上设置的properties，之前的properties被清空

6.3 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

properties = {}
properties["firstKey"] = "firstValue"
sdk:trackFirst(accountId, distinctId, "first_event_test", nil, properties)

首次事件默认使用distinctId作为维度ID，如果您想设置其他维度ID可以通过参数来传入指定的firstCheckId。

properties = {}
properties["firstKey"] = "firstValue"
sdk:trackFirst(accountId, distinctId, "first_event_test", "test_first_check_id", properties)

ChangeLog

v1.4.0 2022/04/26

• 支持创建默认事件uuid
• 支持动态公共属性
• 支持首次事件
• 新增user_uniq_append事件

v1.3.0 2022/02/28

• 支持上传复杂结构类型

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 版本上线