@thinkingai/ae-cli 1.0.30 → 6.0.16

package/wiki/te-docs/raw/data-ingestion-guide/server-sdk/lua.md

@@ -0,0 +1,121 @@
+---
+code: lua_sdk_installation
+name: "Lua"
+wikiToken: CLL4wjPKtiEhkjkmbIqcrn3CnXd
+parentWikiToken: IKVPwn4NfiIhijk5EcAcMf6pn7e
+updateTime: 1774252018000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=lua_sdk_installation
+---
+::: tip
+Before you begin, please read [<text color="purple" underline="true">Preparation before Data Ingestion</text>](https://thinkingdata.feishu.cn/wiki/OhD8we9iai6Xk5kM1QNc8ITRnQe).
+ :::
+**Latest version:** v2.0.1
+**Update time:** 2026-01-08
+**Resource download: **[**Source Code**](https%3A%2F%2Fgithub.com%2FThinkingDataAnalytics%2Flua-sdk)
+::: warning Notice 
+Current documentation applies to v2.0.0 and later. For historical versions, see [Data Ingestion Guide - Lua (V1)](https%3A%2F%2Fdocs.thinkingdata.cn%2Fta-manual%2Fv4.1%2Fen%2Finstallation%2Finstallation_menu%2Fserver_sdk%2Flua_sdk_installation%2Flua_sdk_installation.html) 
+:::
+## **SDK**** Integration**
+1.1 You can download the SDK [source code](https%3A%2F%2Fgithub.com%2FThinkingDataAnalytics%2Flua-sdk) from GitHub and integrate it into your project. Just put `ThinkingDataSdk.lua` in the directory of your project.
+Use the `luarocks` management tool to install third-party libraries:
+```bash
+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
+```
+
+1.2 Logbus Integration
+We recommend using SDK+LogBus to track and report data on server. You can refer to the following documents to complete the installation of Logbus:[ LogBus User Guide](https://thinkingdata.feishu.cn/wiki/SlE6wOEK3isQvukzEbnc5V0inNa)
+## **Initialization**
+The following is the sample code for SDK initialization:
+```lua
+local tdAnalytics = require "ThinkingDataSdk"
+
+local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
+local sdk = tdAnalytics(consumer)
+```
+
+`LOG_DIRECTORY` is the local folder path.
+## **Common Features**
+In order to ensure that the distinct ID and account ID can be bound smoothly, if your game uses the distinct ID and account ID, we strongly recommend that you upload these two IDs at the same time, otherwise the account will not match, causing users to double count. For specific ID binding rules, please refer to the chapter on [User Identification Rules](https://thinkingdata.feishu.cn/wiki/Pov9wECdsi2QQsk4NN9cEPsvnyc).
+### 3.1 **Sending Events**
+ You can call `track` to upload events. It is suggested that you set event properties based on the data tracking plan drafted previously. Here is an example of a user buying an item:
+```lua
+local distinctId = "ABCDEFG123456789"
+local accountId = "TE_10001"
+local properties = {}
+properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
+properties["#ip"] = "192.168.1.1"
+properties["Product_Name"] = "card"
+properties["Price"] = 30
+properties["OrderId"] = "abc_123"
+
+sdk:track(accountId, distinctId, "payment", properties)
+```
+
+- Key is the name of the property and refers to the string type. It must start with a character, and contain numbers, characters (insensitive to case, and upper cases would be transformed into lower cases by TE) and underscores "_", with a maximum length of 50 characters. 
+- Value, the value of the property, supports string, numbers, Boolean, time, object, array object, and array
+<quote-container>
+**The requirements for event properties and user properties are the same as that for super properties**
+</quote-container>
+
+### 3.2** User Properties**
+You can set general user properties by calling `userSet` API. The original properties would be replaced by the properties uploaded via this API. If no user properties are set before, user properties will be newly created. The type of newly-created user properties must conform to that of the uploaded properties. User name setting is taken as the example here: 
+```lua
+local distinctId = "ABCDEFG123456789"
+local accountId = "TE_10001"
+
+local userSetProperties = {}
+userSetProperties["user_name"] = "ABC"
+sdk:userSet(accountId, distinctId, userSetProperties)
+userSetProperties = {}
+userSetProperties["user_name"] = "abc"
+
+sdk:userSet(accountId, distinctId, userSetProperties)
+```
+
+### 3.3 Reported data
+When using `TDLogConsumer`, the collected events are added to the cache array. Data is written to disk only when the number of array elements exceeds the set capacity. You need to set the value of `batchNum` when you initialize `TDLogConsumer`.
+You can call the `flush()` api to report data to the TE  immediately under certain service scenarios. However, frequent calls to `flush()` can result in degraded service performance.
+```lua
+sdk:flush()
+```
+
+### 3.4 Close  SDK
+```lua
+sdk:close()
+```
+
+<quote-container>
+Close and exit the SDK. Please call this api before closing the server to avoid data loss in the cache
+</quote-container>
+
+## **Best Practice**
+The following sample code covers all the above-mentioned operations. It is recommended that the codes be used in the following steps:
+```lua
+local tdAnalytics = require "ThinkingDataSdk"
+
+local consumer = tdAnalytics.TDLogConsumer("LOG_DIRECTORY", tdAnalytics.LOG_RULE.HOUR, 200, 500)
+local sdk = tdAnalytics(consumer)
+
+local distinctId = "ABCDEFG123456789"
+local accountId = "TE_10001"
+
+local properties = {}
+properties["#time"] = os.date("%Y-%m-%d %H:%M:%S")
+properties["Product_Name"] = "card"
+properties["Price"] = 30
+properties["OrderId"] = "abc_123"
+sdk:track(accountId, distinctId, "payment", properties)
+
+local userSetProperties = {}
+userSetProperties["user_name"] = "ABC"
+sdk:userSet(accountId, distinctId, userSetProperties)
+
+userSetProperties = {}
+userSetProperties["user_name"] = "abc"
+sdk:userSet(accountId, distinctId, userSetProperties)
+```

package/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs/nodejs-advanced/debugging-and-logging.md

@@ -0,0 +1,55 @@
+---
+code: nodejs_sdk_debug
+name: "Debugging and Logging"
+wikiToken: L75awACCVi9kCDksvh7clOMUnxe
+parentWikiToken: TZi3wWAOjiiSVckre7pcfTeknbg
+updateTime: 1774249268000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=nodejs_sdk_debug
+---
+::: warning Notice
+The SDK Debug mode is used only for access debugging. Do not apply it to the production environment.
+:::
+During the process of SDK Integration, you can perform real-time debugging by checking SDK logs in the IDE console or using the Debug function of TE.
+## Logging
+```javascript
+ThinkingData.enableLog(true);
+```
+
+## Debugging
+You need to follow the following two steps to enable the Debug mode:
+#### 2.1 Use DebugConsumer
+The sample code for enabling the Debug mode on the client side is as follows:
+```javascript
+// DebugConsumer: Data is reported one by one. When a problem occurs, the user will be prompted with logs and exceptions;
+// it is not recommended to use it in an online environment
+// The third parameter identifies whether to enter the warehouse, true indicates the warehouse, and false indicates not to enter the warehouse
+let teSDK = ThinkingData.initWithDebugMode('appId', 'serverUrl', {
+    dryRun: false, // report data to TE or not
+    deviceId: "123456789"
+});
+
+let trackEvent = {
+    accountId: '2222',
+    distinctId: '1111',
+    event: 'test_event',
+    time: new Date(),
+    ip: '202.38.64.1',
+    properties: {
+        prop_double: 134.1,
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.track(trackEvent)
+```
+
+#### 2.2 Add Device
+To avoid launching the Debug mode in the production environment, it is required that only specified device can enable Debug mode.  The Debug mode can only be enabled for devices whose ID has been configured in the "Debug data" sector on the "tracking management" page of the TE.
+
+<quote-container>
+It can only be used for data verification at the integration stage, and should not be used in the online environment.
+</quote-container>

package/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs/nodejs-advanced/preset-properties.md

@@ -0,0 +1,126 @@
+---
+code: nodejs_sdk_preset_properties
+name: "Preset Properties"
+wikiToken: G0ZUwnoy8i9mEikkCTEc2vJXnOe
+parentWikiToken: TZi3wWAOjiiSVckre7pcfTeknbg
+updateTime: 1774249270000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=nodejs_sdk_preset_properties
+---
+
+The following present properties are properties that all events in SDK would have.
+
+<lark-table rows="8" cols="4" column-widths="169,152,140,259">
+
+  <lark-tr>
+    <lark-td>
+      Property name
+    </lark-td>
+    <lark-td>
+      Display name
+    </lark-td>
+    <lark-td>
+      Property type
+    </lark-td>
+    <lark-td>
+      Instruction
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #ip
+    </lark-td>
+    <lark-td>
+      IP address
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      IP address of the user, based on which TE would get the geographical location of the user
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #country
+    </lark-td>
+    <lark-td>
+      Country
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The country where the user is located; generated based on the IP address
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #country_code
+    </lark-td>
+    <lark-td>
+      Country code
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The code of the country where the user is located (ISO 3166-1 alpha-2, two English characters in upper case); generated based on the IP address
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #province
+    </lark-td>
+    <lark-td>
+      Province
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The province where the user is located; generated based on the IP address
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #city
+    </lark-td>
+    <lark-td>
+      City
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The city where the user is located; generated based on the IP address
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #lib
+    </lark-td>
+    <lark-td>
+      SDK type
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The type of SDK which you integrate, e.g., Golang, etc.
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #lib_version
+    </lark-td>
+    <lark-td>
+      SDK version
+    </lark-td>
+    <lark-td>
+      Text
+    </lark-td>
+    <lark-td>
+      The version of the SDK which you integrate
+    </lark-td>
+  </lark-tr>
+</lark-table>

package/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs/nodejs-advanced.md

@@ -0,0 +1,225 @@
+---
+code: nodejs_sdk_advanced
+name: "Node.js-Advanced"
+wikiToken: TZi3wWAOjiiSVckre7pcfTeknbg
+parentWikiToken: OoIKwLEiNiPgzhksi3xcUBEknbb
+updateTime: 1774249266000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=nodejs_sdk_advanced
+---
+
+## **Sending Events**
+After SDK is initialized, you can track user behaviour data. In general, ordinary events could meet business requirements. You can also use the First/Updatable Event based on your own business requirements.
+### 1.1 **Ordinary Events**
+ You can call `track` to upload events. It is suggested that you set event properties  based on the document about data tracking drafted previously. Procurement of a commodity by a user is taken as the example here:
+```javascript
+let trackEvent = {
+    accountId: '2222',
+    distinctId: '1111',
+    event: 'test_event',
+    time: new Date(),
+    ip: '202.38.64.1',
+    properties: {
+        prop_double: 134.1,
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.track(trackEvent)
+```
+
+### 1.2 **First Events**
+The First Events refers to events that would only be recorded once for the ID of a certain device or other dimensions.   For example, under certain scenarios, you may want to record the activation event on a certain device.   In this case, you can perform data tracking with the First Event.
+If you want to judge whether an event is the First Event from other dimensions, you can define a first_check_id for the First Event:
+```javascript
+let trackFirstEvent = {
+    accountId: '2222',
+    distinctId: '1111',
+    event: 'test_event',
+    firstCheckId: 'first_check_id',
+    time: new Date(),
+    properties: {
+        prop_date: new Date(),
+        prop_double: 134.1,
+        prop_string: 'hello world',
+        prop_int: 67,
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.trackFirst(trackFirstEvent);
+```
+
+<quote-container>
+Note: Since the server has to check whether the event is the First Event, the First Event will be put in storage one hour later by default.
+</quote-container>
+
+### 1.3 ** Updatable Events**
+You can meet the requirements for event data modification under specific scenarios through Updatable Event. The TE would determine the data to be updated according to the event name and event ID.
+```javascript
+let trackUpdateEvent = {
+    accountId: '2222',
+    distinctId: '1111',
+    event: 'test_event',
+    eventId: 'event_id',
+    time: new Date(),
+    properties: {
+        prop_date: new Date(),
+        prop_double: 134.1,
+        prop_string: 'hello world',
+        prop_int: 67,
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.trackUpdate(trackUpdateEvent);
+```
+
+### 1.4 **Overwritable Event****s**
+Despite the similarity with Updatable Event, Overwritable Event would cover all historical data with the latest data. Looking from the perspective of effect, such a process is equivalent to the behavior of deleting the previous data while putting the latest data in storage. The TE would determine the data to be updated according to the event name and event ID.
+```javascript
+let trackOverwriteEvent = {
+    accountId: '2222',
+    distinctId: '1111',
+    event: 'test_event',
+    eventId: 'event_id',
+    time: new Date(),
+    properties: {
+        prop_date: new Date(),
+        prop_double: 134.1,
+        prop_string: 'hello world',
+        prop_int: 67,
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.trackOverWrite(trackOverwriteEvent);
+```
+
+## **User Properties**
+User property setting APIs supported by the TE  include: `userSet`, `userSetOnce`, `userAdd`, `userAppend`, `userUniqAppend`, `userUnset`, `userDel`.
+### 2.1 userSet
+You can call `userSet` to set general user properties. The original properties would be replaced if the properties uploaded via the API are used. If  user properties are not set before, user properties will be created. The type of newly-created user properties must conform to that of the uploaded properties. User name setting is taken as the example here:
+```javascript
+let userSetData = {
+    accountId: 'node_test',
+    properties: {
+        prop_date: new Date(),
+        prop_double: 134.12,
+        prop_string: 'hello',
+        prop_int: 666,
+        prop_array: ['str1', 'str2'],
+    },
+    callback(e) {
+        if (e) {
+            console.log(e);
+        }
+    }
+};
+
+teSDK.userSet(userSetData);
+```
+
+### 2.2 userSetOnce
+If the user property you want to upload only needs to be set once, you can call `userSetOnce` to set the property. If such property had been set before, this message would be ignored. Let's take the setting of the first payment time as an example:：
+```javascript
+teSDK.userSetOnce({
+    accountId: 'node_test',
+    properties: {
+        setOnceProperty: "set_once",
+    }
+});
+```
+
+### 2.3 userAdd
+When you want to upload numeric property for cumulative operation, you can call `userAdd`.
+If the property has not been set, it would be given a value of 0 before computing. A negative value could be uploaded, which is equivalent to subtraction operation. Let's take the accumulative payment amount as an example:
+```javascript
+teSDK.userAdd({
+    accountId: 'node_test',
+    properties: {
+        prop_double: 0.6,
+        prop_int: 222,
+    }
+});
+```
+
+<quote-container>
+The property key is a string, and the value is only allowed to be a numeric value.
+</quote-container>
+
+### 2.4 userAppend
+You can call `userAppend` to add user properties of array type.
+```javascript
+teSDK.userAppend({
+    accountId: 'node_test',
+    properties: {
+        prop_array: ['str3', 'str4']
+    }
+});
+```
+
+### 2.5 userUniqAppend
+You can delete duplicated user property by calling `userUniqAppend` API. If you call `userAppend` API, duplicated user property might not be deleted.
+```javascript
+teSDK.userUniqAppend({
+    accountId: 'node_test',
+    properties: {
+        prop_array: ['str3', 'str4']
+    }
+});
+```
+
+### 2.6 userUnset
+When you need to clear the user properties of users, you can call `userUnset` to clear specific properties. `userUnset` would not create properties that have not been created in the cluster.
+```javascript
+teSDK.userUnset({
+    accountId: 'node_test',
+    property: 'set_once_property'
+});
+```
+
+### 2.7 userDel
+You can call `userDel` to delete a user. After deleting the user, you would no longer be able to inquire about its user property, but could still query the events triggered by the user.
+```javascript
+teSDK.userDel({
+  accountId: "node_test",
+  distinctId: "node_distinct_id"
+});
+```
+
+## **Other**
+### 3.1 BatchConsumer
+::: warning Notice
+When the amount of data is too large or the network is abnormal, there is a risk of data loss. And it is not recommended to use it in a production environment
+:::
+Batches transmit data to the TE in real time, without the need for a transmission tool. 
+```javascript
+let teSDK = ThinkingData.initWithBatchMode('APP_ID', 'SERVER_URL', {
+    batchSize: 2,
+    compress: false // enable compress or not, default true
+});
+```
+
+Instruction on parameters:
+- `APPID`: The APPID of your project, which can be found on the project management page of  TE.
+- `SERVER_URL`: 
+  - If you are using a SaaS version, please check the receiver URL on this page
+<image token="LgHWb0IVPoYRwXxhux6ci6tLnTb" width="1674" height="1318" align="center"/>
+
+- If you use the private deployment version, you can customize the data tracking URL .

package/wiki/te-docs/raw/data-ingestion-guide/server-sdk/nodejs/release-notes.md

@@ -0,0 +1,45 @@
+---
+code: nodejs_sdk_release_note
+name: "Release Notes"
+wikiToken: DcjJwtnIKi9BDNkkvdoccsyTnJb
+parentWikiToken: OoIKwLEiNiPgzhksi3xcUBEknbb
+updateTime: 1774249272000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=nodejs_sdk_release_note
+---
+
+## v1.5.0
+**Date: 2024/03/26**
+**Notes：**
+- Replace log4js with winston
+## v1.4.1
+**Date: 2023/10/27**
+**Notes：**
+- Compatible with lower versions of Node.js
+## v1.4.0
+**Date: 2023/10/20**
+**Notes：**
+- Formatted SDK files name
+## v1.3.9
+**Date: 2023/08/02**
+**Notes：**
+- Configure the Cluster mode switch
+## v1.3.8
+**Date: 2023/03/24**
+**Notes：**
+- Compatible with log4js library
+## v1.3.6
+**Date: 2022/11/10**
+**Notes：**
+- Support debug model on the TE console
+## v1.3.5
+**Date：2022/10/20**
+**Notes：**
+- Add the.d.ts header file
+## v1.3.4
+**Date：2022/10/13**
+**Notes：**
+- Compatible with log4js library
+## v1.3.1
+**Date：2022/09/16**
+**Notes：**
+- Support for complex data types