# Lua SDK User Guide

This guide will show you how to use the Lua SDK to access your project. You can access the source code of the Lua SDK in GitHub (opens new window).

**The latest version is: **1.2.0

**Updated: **2021-03-12

# 1. Integration Preparation

# A) Download SDK

Download ThinkingDataS dk.lua and til.lua files under the official address

# B) Integrated SDK

Put the downloaded SDK file into the package.path and you can directly reference it

# 2. Initialize the SDK

You can get an SDK instance in three ways (see API doc for overloads of other Consumer constructors):

# a) LogConsumer

**LogConsumer: **write local files in batches, the files are separated by day or hour, and need to be uploaded with LogBus

--LogConsumer
local TdSDK = require "ThinkingDataSdk"
local LOG_DIRECTORY = "/tmp/data" --Mandatory, Local File Path
local fileNamePrefix = "td" --Optional parameters, generated file prefix, generated file format td. Log.% Y-%m-%d-%H_ 0, default format is log.% Y-%m-%d-%H_ 0
local batchNum = 15 --Optional parameter to set the number of bars saved each time, i.e. every 15 bars saved, with a default of 10
local fileSize = 15 --Optional parameter, upper limit per file size in M, no upper limit by default
local rule = TdSDK.LOG_RULE.HOUR --Optional parameters, file separation, HOUR or DAY, i.e. by hour or by day, default by day
local consumer = TdSDK.LogConsumer(LOG_DIRECTORY, rule, batchNum, fileSize, fileNamePrefix)
local td = TdSDK(consumer)

LOG_DIRECTORYTo write to the local folder address, you only need to set the listening folder address of LogBus to the address here, and you can use LogBus to monitor and upload data.

# b) BatchConsumer

**BatchConsumer: **batch data transfer to the TA server, do not need to match the transfer tool, you can set the maximum number of uploads per time (default 20) and cache maximum batch number (default 50), that is, the default maximum cache number is 20 * 50. In the case of prolonged network outages, there is a risk of data loss.

--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) DebugConsumer

**DebugConsumer: **Transfer data one by one to the TA server, and throw exceptions when data validation errors occur for data debugging.

--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_URIFor the uri that transfers data, APP_IDFor the APP ID of your project.

If you are using Cloud as a Service, enter the following URL:

http://receiver.ta.thinkingdata.cn

If you are using the version of private deployment, enter the following URL:

http://Data Acquisition Address

# 3. Send Events

After the SDK initialization is completed, you can call trackto upload events. In general, you may need to upload more than a dozen to hundreds of different events. If you are using the TGA background for the first time, we recommend You upload a few key events first.

If you have doubts about what kind of events you need to send, you can check the Quick Use Guide for more information.

# A) Send Event

You can call trackto upload events. It is recommended that you set the attributes of the event and the conditions for sending information according to the previously combed doc. Here, take player payment as an example:

--Initialise 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)

--Set Visitor ID "ABCDEFG123456789"
local distinctId = "ABCDEFG123456789"

--Set account ID "TA_10001"
local accountId = "TA_10001"

--Set Event Properties
local properties = {}

--Set the time when the event occurred, if not, the default is the current time
properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")

--Set the user's IP address, the TA system will interpret the user's geographic location information based on the IP address, if not, it will default to not report
properties["#ip"] = "192.168.1.1"

properties["Product_Name"] = "monthly pass"
properties["Price"] = 30
properties["OrderId"] = "abc_123"

--Upload event, including user's visitor ID and account ID, please note the order of account ID and visitor ID
sdk:track(distinctId, accountId, "payment", properties)
properties = nil

**Note: **In order to ensure that the guest ID and account ID can be bound smoothly, if you will use the guest ID and account ID in your game, we strongly recommend that you upload the two IDs at the same time, otherwise the account will not match, resulting in the user Double calculation, the specific ID binding rules can refer to the user identification rules chapter.

The name of the event is of type String, can only begin with a letter, can contain numbers, letters and an underscore "_", is up to 50 characters in length, and is not case sensitive to letters.
The property of the event is a tableobject, where each element represents a property.
The value of Key is the name of the attribute, which is of Stringtype. It is stipulated that it can only be a preset attribute , or start with a letter, contain numbers, letters and underscore "_", and the maximum length is 50 characters. It is not sensitive to letter case.
Value is the value of the property and supports String, Number, Boolean, Dateand Array.

# B) Set Public Event Properties

For some properties that need to appear in all events, you can call setSuperPropertiesto set these properties as public event properties, which will be added to all events uploaded using track.

local superProperties = {}
--Set Common Properties: Server Name
superProperties["server_name"] = "S10001"
--Set Common Properties: Server Version
superProperties["server_version"] = "1.2.3"
--Setting Common Event Properties
sd:setSuperProperties(superProperties)
superProperties = nil

local properties = {}
--Set Event Properties
properties["Product_Name"] = "monthly pass"
properties["Price"] = 30
--Upload an event with the common attributes and the attributes of the event
sd:track(accountId, distinctId, "payment", properties)
properties = nil

The public event attribute is also a tableobject, where each element represents an attribute.
The value of Key is the name of the attribute, which is of Stringtype. It is stipulated that it can only be a preset attribute , or start with a letter, contain numbers, letters and underscore "_", and the maximum length is 50 characters. It is not sensitive to letter case.
Value is the value of the property and supports String, Number, Boolean, Dateand Array.

If you call setSuperPropertiesto set a previously set public event property, the previous property value is overwritten. If the public event property and the Key of a property in the trackupload event duplicate, the property of the event overrides the public event property:

local superProperties = {}
superProperties["server_name"] = "S10001"
superProperties["server_version"] = "1.2.3"
--Set Common Event Properties
sd:setSuperProperties(superProperties)
superProperties = {}
superProperties["server_name"] = "Q12345"
--Set the public event properties again, when "server_name" is overwritten and the value is "Q12345"
sd:setSuperProperties(superProperties)

local properties = {}
properties["Product_Name"] = "monthly pass"
--Set properties that repeat the attributes of a public event
superProperties["server_version"] = "1.2.4"
--Upload event, at this time the attribute value of "server_version" will be overwritten with "1.2.4" and the value of "server_name" will be "Q12345".
sd:track(accountId, distinctId, "payment", properties)

If you want to empty all public event properties, you can call clearSuperProperties.

# 4. User Features

TGA platform currently supports the user feature setting interface for userSet, userUnset, userSetOnce, userAdd, userDel, userAppend.

# a) UserSet

For general user features, you can call userSetto set it. The attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the new user feature will be created. The type is the same as the type of the incoming attribute. Here, take the user name set by the player as an example:

local userSetProperties = {}
userSetProperties["user_name"] = "ABC"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload User Properties
sd:userSet(accountId, distinctId, userSetProperties)

userSetProperties = {}
userSetProperties["user_name"] = "abc"
userSetProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
//Upload the user property again, and the value of "user_name" will be overwritten with "abc"
sd:userSet(accountId, distinctId, userSetProperties)

The user featureset by the userSet is a tableobject where each element represents an attribute.
The value of Key is the name of the attribute, which is of stringtype. It is stipulated that it can only start with letters, contain numbers, letters and underscore "_", and is up to 50 characters in length. It is not sensitive to case of letters.
Value is the value of the property and supports String, Number, Boolean, Dateand Array.

# b) UserSetOnce

If the user feature you want to upload only needs to be set once, you can call userSetOnceto set it. When the attribute already has a value before, this information will be ignored. Take setting the player username as an example:

local userSetOnceProperties = {}
userSetOnceProperties["user_name"] = "ABC"
userSetOnceProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user properties and create a new "user_name" with the value "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")
--Upload the user property again, at which point the value of "user_name" will not be overwritten, it will still be "ABC" and the value of "user_age" will be 18
sd:userSetOnce(accountId, distinctId, userSetOnceProperties)

The userSetOnceset user feature types and restrictions consistent with the userSet.

# c) UserAdd

When you want to upload a numeric attribute, you can call userAddto accumulate the attribute. If the attribute has not been set, a value of 0 will be assigned before calculation. Negative values can be passed in, which is equivalent to subtraction operations. Take the accumulated payment amount as an example:

local userAddProperties = {}
userAddProperties["total_revenue"] = 30
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user attributes with a value of 30 for "total_revenue"
sd:userAdd(accountId, distinctId, userAddProperties)

userAddProperties = {}
userAddProperties["total_revenue"] = 60
userAddProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user attributes again, when the value of "total_revenue" accumulates to 90
sd:userAdd(accountId, distinctId, userAddProperties)

The user feature typeand restrictions set by userAdd are consistent with userSet, but only incoming numeric user features are supported.

# d) UserAppend

When you need to add an element to the Arrayproperty value, you can call userAppendto add the list, or create the property if it is not already created in the cluster. Take the equipment list as an example:

local equips = {}
equips[1] = "weapon"
equips[2] = "hat"
local userAppendProperties = {}
userAppendProperties["equips"] = equips
userAppendProperties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
--Upload user attributes, where the value of "equips" is ["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")
--Upload user attributes again, and the value of "equips" adds a "clothes": ["weapon", "hat", "clothes"]
sd:userAppend(accountId, distinctId, userAppendProperties)

The user feature type set by userAppendonly supports the Arraytype, other types will be ignored.

# e) UserUnset

When you need to empty some properties, you can call userUnsetto empty them (that is, set to NULL). If a property does not exist, the property will not be created.

local userUnsetProperties = {}
userUnsetProperties[1] = "total_revenue"
userUnsetProperties[2] = "equips"
--Upload user attributes, at which point the two attributes "total_revenue" and "equips" will be reset
sd:userUnset(accountId, distinctId, userUnsetProperties)

# f) UserDel

If you want to delete a user, you can call userDelto delete the user. You will no longer be able to query the user features of the user, but the events generated by the user can still be queried. This operation may have irreversible consequences. Please use with caution.

sd:userDel(accountId, distinctId)

# 5. Other Operations

# A) Submit Data Immediately

sd:flush()

Submit data to the appropriate receiver immediately.

# B) Close sdk

sd:close()

Close and exit sdk, please call this interface before shutting down the server to avoid data loss in the cache.

# ChangeLog

# v1.2.0 2021/03/12

BatchConsumer mode increased to set maximum cache value

# v1.1.1 2021/02/23

Added debugOnly function for DebugConsumer mode
BatchConsumer mode does not delete data when sending fails due to network problems

# v1.1.0 2021/01/13

Fix the bug that the file cannot be generated when the file size is specified

# v1.0.0 2020/11/20

Lua SDK version 1.0.0 is online

← Java SDK User Guide Node.js SDK User Guide →