菜单

Lua

更新时间：2024-12-10
下载地址：最新版本
源码：GitHub
⚠️ 此 SDK 需搭配 FileScout 使用

一、集成 SDK

下载最新版本的 SDK：
根据使用环境下载对应的 *.src.rock 文件，并去掉前缀将其更名为 dt-lua-sdk-{version}.src.rock
- Lua 解释器版本 (lua51, lua52, lua53, lua54, ...),
- 操作系统 (Linux, macOS, Windows, ...),
- CPU 架构 (x86_64, aarch64, ...).

通过 Luarocks 安装 SDK：

bash 复制代码

luarocks install dt-lua-sdk-{version}.src.rock
# Example:
luarocks install dt-lua-sdk-1.0.0-1.src.rock

使用：dt = require("DataTowerSdk")

如果没有符合您环境的 rock 文件，请与我们联系

二、初始化

SDK 初始化示例代码

Lua 复制代码

dt = require("DataTowerSdk")

consumer = dt.DTLogConsumer("./log", 200, 10000)
sdk = dt(consumer, false)

三、基础功能

事件上报和用户属性的所有接口会对事件名/属性名/类型进行校验

如果校验通过会返回 true，并进行记录上报

未通过则会返回 false，不进行记录上报

3.1 设置事件上报

数据说明文档：当您将要上报的事件/属性在数据说明文档中已存在时，强烈建议您使用文档中的对应属性名，比如您要上报 APP 的操作系统属性，请使用文档里预置的属性名”#os”，不要自定义取名，避免跟客户端上报的预置属性不一致
用户识别规则：为了让访客 ID（dt_id）与帐号 ID（acid）能够顺利绑定，其中访客 ID（dt_id）为必填

该接口是使用最频繁的接口，通过调用 track 来上报自定义事件，在上报事件之前，建议您根据梳理的文档来设置事件属性，以下是示例代码：

lua 复制代码

acId = "account_id_111"
dt_id = "dt_id_222"

local properties = {}
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example.app"
properties["#os"] = "android"
properties["user_level"] = 20
properties["coin"] = 1000
properties["from"] = "entry"

sdk:track(acId, dt_id, "eventName", properties)

注意：

以#开头命名的事件/属性，必须按照预置事件/属性规则进行上报，否则将无法上报
以$开头的事件/属性都被视为非法字段，将无法上报

3.2 设置用户属性

DT 系统支持的用户属性设置类型总览说明如下

操作	对应事件名	处理规则
覆盖用户属性	`#user_set`	对用户表进行操作，覆盖用户的原有属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与覆盖操作传入属性的类型一致
初始化用户属性	`#user_set_once`	对用户表进行操作，初始化用户属性，如果该属性已有值存在，系统忽略本次操作
累加用户属性	`#user_add`	对用户表进行操作，对数值型的用户属性做累加计算，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值等同于相减操作
清空用户属性值	`#user_unset`	对用户表进行操作，清空用户属性的属性值，即设置成 NULL，如果被清空的属性不存在也不会新建该属性
追加列表型用户属性的元素	`#user_append`	对用户表进行操作，对列表类型的用户属性追加元素，如果被追加的列表属性不存在，系统将自动生成并进行追加
追加并去重列表类型用户属性的元素	`#user_uniq_append`	对用户表进行操作，对列表类型的用户属性值追加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变），如果被追加的列表属性不存在，系统将自动生成并进行追加再去重
删除用户	`#user_delete`	对用户表进行操作，删除对应用户，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

3.2.1 userSet

userSet 是常用的功能，您可以调用它来进行用户属性的设置，调用该操作时，会覆盖原有的属性值，如果用户不存在该属性，则会创建新用户属性，类型与传入属性的类型一致

lua 复制代码

properties = { "name" = "abc" }
-- 设置用户属性，"name" 的值为 "abc"
sdk:userSet(acid, dt_id, properties)

properties = { "name" = "xyz" }
-- 再次设置用户属性，此时 "name" 的值会被覆盖为 "xyz"
sdk:userSet(acid, dt_id, properties)

3.2.2 userSetOnce

如果您希望用户属性只设置一次，则可以调用 userSetOnce 进行设置，当该属性没有值时，则会创建该属性并赋值，但该属性已经有值时，将不会设置成功

lua 复制代码

properties = { "name" = "abc" }
-- 一次性设置用户属性，"name" 的值为 "abc"
sdk:userSetOnce(acid, dt_id, properties)

properties = { "name" = "xyz" }
-- 再次一次性设置用户属性，此时 "name" 的值不会被覆盖为 "xyz"
sdk:userSetOnce(acid, dt_id, properties)

3.2.3 userAdd

当您要对数值类型的属性进行累加操作时，可以调用 userAdd 来实现，如果该属性还没有被设置，则会赋值为 0 再进行计算，可传入负值等同于相减操作

lua 复制代码

properties = {
    "total_count" = 10,
    "level" = 3
}
-- 对用户属性进行累加，数据上传完成后，由于该属性还没有被设置，此时 "total_count" 的值为 10,"level" 的值为 3
sdk:userAdd(acid, dt_id, properties)

properties = { "total_count" = 20 }
-- 对用户属性进行累加，数据上传完成后，此时 "total_count" 的值为 30, "level" 的值为 3
sdk:userAdd(acid, dt_id, properties)

3.2.4 userUnset

当您要清空用户属性时，可以调用 userUnset 来实现，如果属性存在，则会删除属性，如果属性不存在，则不会做任何操作

lua 复制代码

del_set = { "name" = 0,"actime_time" = 0 }
-- 设置后，会删除 name 和 actime_time 两个用户属性
sdk::userUnset(acid, dt_id, del_set)

3.2.5 userAppend

当您要追加列表类型用户属性元素时，可以调用 userAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加

lua 复制代码

properties = {
    "pet" = {"cat", "dog"}
}
-- 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
sdk::userSet(acid, dt_id, properties)

properties = {
    "pet" = {"ratbbit"}
}
-- 对用户列表类型属性追加元素，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit"]
sdk::userAppend(acid, dt_id, properties)

3.2.6 userUniqAppend

当您要追加列表类型用户属性元素并去重时，可以调用 userUniqAppend 来实现，如果被追加的列表属性不存在，系统将自动生成并进行追加和去重

lua 复制代码

properties = {
    "pet" = {"cat", "dog"}
}
-- 设置用户属性，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog"]
sdk:userSet(acid, dt_id, properties)

properties = {
    "pet" = {"ratbbit", "dot"}
}
-- 对用户列表类型属性追加元素并去重，数据上传完成后，此时用户属性 "pet" 的值为 ["cat", "dog", "rabbit]
sdk:userUniqAppend(acid, dt_id, properties)

3.2.7 userDelete

如果您要删除某个用户，可以调用 userDelete 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

lua 复制代码

sdk:userDelete(acid, dt_id)

四、进阶功能

4.1 设置用户ip地址

在服务端上报数据时，如果您想设置用户的ip地址,可以通过在properties中添加#ip属性，DT会根据您上报的IP地址解析用户的地理位置信息。

注：如果是用户事件，仅userSetOnce可上报#ip属性

lua 复制代码

properties["#ip"] = "127.0.0.1"

五、数据传输

可能使用的数据传输方式：

DTLogConsumer：写入文件 + 通过 FileScout 传输

如果生产的数据都是调试数据，建议您开启 debug 标志，当 debug 标志开启时，数据将不会进入生产环境

5.1 DTLogConsumer

参数（按顺序）：

log 文件的文件夹路径
最大单次写入条数
单个文件的最大大小（单位：Byte）
log 文件的前缀（可选）

lua 复制代码

consumer = dt.DTLogConsumer("./log", 200, 10000, "dt")
-- 开启 debug 标志
sdk = dt(consumer, true)
-- 关闭 debug 标志
-- sdk = dt(consumer, false)

5.2 提交数据

如果您期望数据立即上报到 DT 服务器，可以通过 flsuh 完成

lua 复制代码

-- 立即上报数据
sdk:flush()

5.3 关闭 SDK

请在退出程序前调用本接口，以避免缓存的数据丢失（重要！)

lua 复制代码

sdk:close()

六、完整示例

从 SDK 初始化、上报到关闭，整个上报流程示例

lua 复制代码

package.path = package.path .. ";../?.lua"
local dt = require("src.DataTowerSdk")

local function getLogConsumer()
    return dt.DTLogConsumer("./log", 200, 10000)
end

dt.enableLog(true)

local consumer = getLogConsumer()

--- init SDK with consumer
local sdk = dt(consumer, false)

local dt_id = "1234567890987654321"
local acId = nil

-- set dynamic super properties
sdk:setDynamicSuperProperties(function ()
    local properties = {}
    properties["DynamicKey"] = "DynamicValue"
    return properties
end)

-- set super properties
local superProperties = {}
superProperties["super_key_sex"] = "male"
superProperties["super_key_age"] = 23
sdk:setSuperProperties(superProperties)
superProperties = nil

local properties = {}
properties["productNames"] = { "Lua", "hello" }
properties["productType"] = "Lua book"
properties["producePrice"] = 80
properties["shop"] = "aShop"
properties["#os"] = "1.1.1.1"
properties["date"] = os.date()
properties["date1"] = os.date("%Y-%m-%d %H:%M:%S")
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"

sdk:track(acId, dt_id, "eventName", properties)

sdk:clearSuperProperties()

sdk:track(acId, dt_id, "eventName", properties)

properties = {}
properties["productNames"] = { "Lua", "hello" }
properties["productType"] = "Lua book"
properties["producePrice"] = 80
properties["shop"] = "aShop"
properties["#os"] = "1.1.1.1"
properties["date"] = os.date()
properties["date1"] = os.date("%Y-%m-%d %H:%M:%S")
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"
sdk:track(acId, dt_id, "purchasing", properties)

local properties = {}
properties["#city"] = "beijing"
properties["#province"] = "beijing"
properties["name"] = "nammy"
properties["userLevel"] = 0
properties["userPoint"] = 0
properties["#os"] = "1.2.3"
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"
local itemList = { "pen", "tissue", "key", "fork" }
properties["items"] = itemList
sdk:userSet(acId, dt_id, properties)
properties = nil

local properties = {}
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"

properties["setOnceKey"] = "1st"
sdk:userSetOnce(acId, dt_id, properties)

properties["setOnceKey"] = "2nd"
sdk:userSetOnce(acId, dt_id, properties)

properties = {}
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"
properties["userPoint"] = 100
sdk:userAdd(acId, dt_id, properties)

properties = {}
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"
properties["append"] = { "append_one" }
sdk:userAppend(acId, dt_id, properties)

properties = {}
properties["#app_id"] = "appid_1234567890"
properties["#bundle_id"] = "com.example"
properties["append"] = {"append_one", "append_two"}
sdk:userUniqAppend(acId, dt_id, properties)

sdk:flush()
sdk:close()

上一个

Python

下一个

Java

最近修改: 2024-12-10

大纲