Lua

最近更新 2026/10/03

本指南将会为您介绍如何使用 Lua SDK 接入您的项目。

最新版本为：v2.0.1

更新时间为：2026-01-08

资源下载: 源代码

注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Lua SDK 接入指南（V1）

一、集成SDK

1. 下载源代码，把下载的ThinkingDataSdk.lua文件放入您的工程目录下
2. 使用 luarocks 管理工具安装第三方库：

 luarocks install uuid 0.3-1
 
 # 安装 luasec 库需要指定 OPENSSL_DIR 路径
 luarocks install luasec OPENSSL_DIR=[PATH]
 
 luarocks install lua-cjson

3. 安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

二、初始化

以下是SDK初始化的示例代码:

local tdAnalytics = require "ThinkingDataSdk"

local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
local sdk = tdAnalytics(consumer)

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

三、常用功能

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

3.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

--设置访客ID"ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--设置账号ID"AE_10001"
local accountId = "AE_10001"
--设置事件属性
local properties = {}
--设置事件发生的时间，如果不设置的话，则默认使用为当前时间
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

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

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--上传事件，包含用户的访客ID与账号ID，请注意账号ID与访客ID的顺序
sdk:track(accountId, distinctId, "payment", properties)

• 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
• Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,AE会统一转化为小写字母
• Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

用户属性的要求与事件属性保持一致

3.2 设置用户属性

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

--设置访客ID"ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--设置账号ID"AE_10001"
local accountId = "AE_10001"

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--上传用户属性
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--再次上传用户属性，此时"user_name"的值会被覆盖为"abc"
sdk:userSet(accountId, distinctId, userSetProperties)

3.3 数据上报

使用 TDLogConsumer 时，采集到的事件会添加到缓存数组中。当数组元素个数超出设置的容量时才会将数据写入磁盘。初始化 TDLogConsumer 时需要显式的传入 batchNum 的值。

在某些业务场景下，如果您期望数据立即上报到AE服务器，可以通过调用flush()接口完成。需要注意，频繁调用flush()会导致服务性能下降。

sdk:flush()

3.4 关闭SDK

sdk:close()

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

四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

local tdAnalytics = require "ThinkingDataSdk"

local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
local sdk = tdAnalytics(consumer)

--设置访客ID"ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--设置账号ID"AE_10001"
local accountId = "AE_10001"
--设置事件属性
local properties = {}
--设置事件发生的时间，如果不设置的话，则默认使用为当前时间
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

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

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--上传事件，包含用户的访客ID与账号ID，请注意账号ID与访客ID的顺序
sdk:track(accountId, distinctId, "payment", properties)

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--上传用户属性
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--再次上传用户属性，此时"user_name"的值会被覆盖为"abc"
sdk:userSet(accountId, distinctId, userSetProperties)