Lua

Last updated 10/03/2026

This guide shows you how to integrate the Lua SDK into your project.

Latest version: v2.0.1

Update time: 2026-01-08

Downloads: Source code

Note

This document applies to v2.0.0 and later. For earlier versions, see Lua SDK Integration Guide (V1)

1. Integrate the SDK

1. Download the source code and put the downloaded ThinkingDataSdk.lua file in your project directory
2. Use the luarocks package manager to install third-party libraries:

 luarocks install uuid 0.3-1
 
 # To install the luasec library, specify the OPENSSL_DIR path
 luarocks install luasec OPENSSL_DIR=[PATH]
 
 luarocks install lua-cjson

3. Install Logbus

We recommend using SDK + LogBus to collect and report server-side data. To install Logbus, see the following document: LogBus user guide

2. Initialization

The following sample code initializes the SDK:

local tdAnalytics = require "ThinkingDataSdk"

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

LOG_DIRECTORY is the path of the local folder that data is written to. Set the folder that LogBus monitors to this path, and LogBus monitors and uploads the data.

3. Common features

To make sure that the distinct ID and account ID can be bound correctly, if your game uses both the distinct ID and the account ID, we strongly recommend that you upload both IDs. Otherwise, accounts may fail to match and users may be counted more than once. For details on ID binding rules, see User identification rules.

3.1 Send events

You can call track to upload events. We recommend setting event properties and the conditions for sending events based on the document you prepared earlier. The following sample code sends an event:

--Set the distinct ID "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--Set the account ID "AE_10001"
local accountId = "AE_10001"
--Set event properties
local properties = {}
--Set the time when the event occurred. If you don't set it, the current time is used by default
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--Set the user's IP address. The AE system parses the user's geographic location from the IP address. If you don't set it, it is not reported by default
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--Upload the event with the user's distinct ID and account ID. Note the order of the account ID and the distinct ID
sdk:track(accountId, distinctId, "payment", properties)

• The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.
• Key is the name of the property and is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive. AE converts it to lowercase
• Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

User properties have the same requirements as event properties

3.2 Set user properties

For general user properties, you can call userSet to set them. Properties uploaded through this API overwrite the original property values. If the user property doesn't exist yet, a new user property is created with the same type as the value passed in. The following example sets the username:

--Set the distinct ID "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--Set the account ID "AE_10001"
local accountId = "AE_10001"

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--Upload user properties
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--Upload user properties again. The value of "user_name" is overwritten with "abc"
sdk:userSet(accountId, distinctId, userSetProperties)

3.3 Send data

When you use TDLogConsumer, collected events are added to a cache array. Data is written to disk only when the number of elements in the array exceeds the configured capacity. When you initialize TDLogConsumer, you must explicitly pass in the value of batchNum.

In some business scenarios, if you want data to be reported to the AE server immediately, you can call flush(). Note that calling flush() frequently degrades service performance.

sdk:flush()

3.4 Shut down the SDK

sdk:close()

Shuts down and exits the SDK. Call this API before you shut down the server to avoid losing data in the cache

4. Best practices

The following sample code includes all of the operations above. We recommend using them in the following order:

local tdAnalytics = require "ThinkingDataSdk"

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

--Set the distinct ID "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"
--Set the account ID "AE_10001"
local accountId = "AE_10001"
--Set event properties
local properties = {}
--Set the time when the event occurred. If you don't set it, the current time is used by default
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--Set the user's IP address. The AE system parses the user's geographic location from the IP address. If you don't set it, it is not reported by default
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "card"
properties["Price"] = 30
properties["OrderId"] = "abc_123"
--Upload the event with the user's distinct ID and account ID. Note the order of the account ID and the distinct ID
sdk:track(accountId, distinctId, "payment", properties)

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
--Upload user properties
sdk:userSet(accountId, distinctId, userSetProperties)
userSetProperties = {}
userSetProperties["user_name"] = "abc"
--Upload user properties again. The value of "user_name" is overwritten with "abc"
sdk:userSet(accountId, distinctId, userSetProperties)