# 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_DIRECTORY
To 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_URI
For the uri that transfers data, APP_ID
For 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 track
to 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 track
to 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
table
object, where each element represents a property. - The value of Key is the name of the attribute, which is of
String
type. 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
,Date
andArray
.
# B) Set Public Event Properties
For some properties that need to appear in all events, you can call setSuperProperties
to 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
table
object, where each element represents an attribute. - The value of Key is the name of the attribute, which is of
String
type. 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
,Date
andArray
.
If you call setSuperProperties
to 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 track
upload 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 userSet
to 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 feature
set by the userSet is atable
object where each element represents an attribute.- The value of Key is the name of the attribute, which is of
string
type. 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
,Date
andArray
.
# b) UserSetOnce
If the user feature you want to upload only needs to be set once, you can call userSetOnce
to 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 userSetOnce
set user feature types and restrictions consistent with the userSet
.
# c) UserAdd
When you want to upload a numeric attribute, you can call userAdd
to 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 type
and 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 Array
property value, you can call userAppend
to 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 userAppend
only supports the Array
type, other types will be ignored.
# e) UserUnset
When you need to empty some properties, you can call userUnset
to 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 userDel
to 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