@thinkingai/ae-cli 1.0.28 → 6.0.16

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

@@ -0,0 +1,72 @@
+---
+code: golang_sdk_release_note
+name: "Release Notes"
+wikiToken: ZFjHwWkeciXZDnk0VTHcByVDnYc
+parentWikiToken: GVHiwdEmWixRWrk0ZdKcT2twnSn
+updateTime: 1774249262000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=golang_sdk_release_note
+---
+
+## v2.3.0
+**Date: 2026/03/17**
+**Notes:**
+- Improve file creation stability
+## v2.2.0
+**Date: 2025/01/22**
+**Notes:**
+- Improve file creation stability
+## v2.1.0
+**Date: 2024/12/19**
+**Notes:**
+- Improve file creation stability
+## v2.0.3
+**Date: 2024/10/15**
+**Notes:**
+- Support setting app id in data
+## v2.0.1
+**Date: 2024/01/04**
+**Notes:**
+- Add panic catch
+## v2.0.0
+**Date: 2023/09/22**
+**Notes:**
+- Use the SetLogLevel() method to enable log
+## v1.7.0
+**Date: 2023/07/24**
+**Notes:**
+- Throws an error when there is a problem with the method call
+## v1.6.9
+**Date: 2023/06/27**
+**Notes:**
+- Improve file creation stability
+## **v1.6.8**
+**Date：2023/02/23**
+**Notes：**
+- Clean up example program
+## **v1.6.7**
+**Date：2022/11/08**
+**Notes：**
+- Supports debug mode
+## **v1.6.6**
+**Date：2022/08/19**
+**Notes：**
+- Add log system
+## v1.6.4 
+**Date：2022/07/13**
+**Notes：**
+- Optimizing check properties
+## v1.6.3 
+**Date: 2022/06/16**
+**Notes：**
+- Modify the regular expression for time matching
+## v1.6.1 
+**Date: 2022/05/24**
+**Notes：**
+- Remove AsyncBatchConsumer 
+## v1.6.0
+**Date: 2022/05/16**
+**Notes：**
+- Supports setting dynamic public properties 
+- Supports UserUniqAppend 
+- Supports AsyncBatchConsumer 
+- Supports Track First Event

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

@@ -0,0 +1,148 @@
+---
+code: golang_sdk_installation
+name: "Golang"
+wikiToken: GVHiwdEmWixRWrk0ZdKcT2twnSn
+parentWikiToken: IKVPwn4NfiIhijk5EcAcMf6pn7e
+updateTime: 1774252008000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=golang_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: **2.3.0
+**Update time: **2026-03-17
+**Resource download: **[**Source Code**](https%3A%2F%2Fgithub.com%2FThinkingDataAnalytics%2Fgo-sdk)
+::: warning Notice 
+Current documentation applies to v2.0.0 and later. For historical versions, see [Data Ingestion Guide - Golang (V1)](https%3A%2F%2Fdocs.thinkingdata.cn%2Fta-manual%2Fv4.1%2Fen%2Finstallation%2Finstallation_menu%2Fserver_sdk%2Fgolang_sdk_installation%2Fgolang_sdk_installation.html) 
+:::
+## **SDK**** Integration**
+1.1 Execute the following command to get the latest version of Golang SDK:
+```shell
+# install SDK
+go get github.com/ThinkingDataAnalytics/go-sdk/v2
+
+# update SDK
+go get -u github.com/ThinkingDataAnalytics/go-sdk/v2
+```
+
+1.2 used Module
+```go
+//Introduce thinkingdata at the beginning of the code file
+import "github.com/ThinkingDataAnalytics/go-sdk/v2/src/thinkingdata"
+
+# Pull out the latest SDK module
+go mod tidy
+```
+
+1.3 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:
+```go
+config := thinkingdata.TDLogConsumerConfig {
+    Directory: "LOG_DIRECTORY",
+}
+consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
+te := thinkingdata.New(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:
+```go
+accountId := "te_account_id"
+distinctId := "te_distinct_id"
+properties := map[string]interface{}{
+   "channel": "te",      
+   "age": 1,        
+   "is_success": true,     
+   "birthday": time.Now(),
+   "object": map[string]interface{}{
+      "key": "value",
+   }, 
+   "objectArr": []interface{}{
+      map[string]interface{}{
+         "key": "value",
+      },
+   },
+   "arr": []string{"value"},
+}
+
+err := te.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: 
+```go
+err := te.UserSet("accountId", "distinctId", map[string]interface{}{
+   "user_name": "TA",
+})
+err = te.UserSet("accountId", "distinctId", map[string]interface{}{
+   "user_name": "TE",
+})
+```
+
+### 3.3 Reported data
+When `TDLogConsumer` is used, the SDK writes the collected data to the disk in real time.
+Internally, the `Flush()` method of the `TDAnalytics` object synchronizes the default memory cache in the file system to disk in real time. You generally do not need to call the `Flush()` method manually.
+### 3.4 Close  SDK
+```go
+te.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:
+```go
+config := thinkingdata.TDLogConsumerConfig {
+    Directory: "./log_directory",
+}
+consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
+te := thinkingdata.New(consumer)
+
+accountId := "te_account_id"
+distinctId := "te_distinct_id"
+properties := map[string]interface{}{
+    "channel":   "te",     
+    "age":       1,         
+    "isSuccess": true,       
+    "birthday":  time.Now(), 
+    "object": map[string]interface{}{
+       "key": "value",
+    },
+    "objectArr": []interface{}{
+       map[string]interface{}{
+          "key": "value",
+       },
+    },
+    "arr":     []string{"value"},
+}
+
+err := te.Track(accountId, distinctId, "payment", properties)
+if err != nil {
+    fmt.Println(err)
+}
+
+err = te.UserSet("accountId", "distinctId", map[string]interface{}{
+    "user_name": "TE",
+})
+if err != nil {
+    fmt.Println(err)
+}
+
+//Calling the flush API will immediately write the data to the file. 
+//In the production environment, pay attention to avoid IO or network overhead caused by frequent calls to flush
+te.Flush()
+```

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

@@ -0,0 +1,49 @@
+---
+code: java_sdk_debug
+name: "Debugging and Logging"
+wikiToken: ItSrwhrGIiXRYrkEGXxcOov5n6g
+parentWikiToken: T4JmwitDgi3rCQkygsNcysKRn2e
+updateTime: 1774249237000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=java_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
+```java
+TDAnalytics.enableLog(true);
+```
+
+<quote-container>
+After enabling the log, you can observe the data tracking of SDK in IDE.
+</quote-container>
+
+## 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:
+```java
+/*
+DebugConsumer: Data is reported item by item. 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
+ */
+TDAnalytics te = new TDAnalytics(new TDDebugConsumer("serverUrl","appId","deviceId"));
+
+Map<String,Object> properties = new HashMap<String,Object>();
+properties.put("name", "shoes");
+try {
+     te.track("account_id","distinct_id","payment",properties);
+} catch (Exception e) {
+     System.out.println("except:"+e);
+}
+```
+
+#### 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.
+<image token="RlS7bVxlzob1iNxv6jZckVz6nrd" width="1280" height="590" align="center"/>
+
+<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/java/java-advanced/preset-properties.md

@@ -0,0 +1,126 @@
+---
+code: java_sdk_preset_properties
+name: "Preset Properties"
+wikiToken: H1SLwTyv4i5pZUkb3Pdc0JdYnZd
+parentWikiToken: T4JmwitDgi3rCQkygsNcysKRn2e
+updateTime: 1774249239000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=java_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/java/java-advanced.md

@@ -0,0 +1,223 @@
+---
+code: java_sdk_advanced
+name: "Java-Advanced"
+wikiToken: T4JmwitDgi3rCQkygsNcysKRn2e
+parentWikiToken: BuVmwRcFsi4Oq5knoDDcgJ3fnSN
+updateTime: 1774249235000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=java_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:
+```java
+Map<String,Object> properties = new HashMap<String,Object>();
+properties.put("product_name","goodsName");
+try {
+     te.track("account_id","distinct_id","product_buy",properties);
+} catch (Exception e) {
+     System.out.println("except:"+e);
+}
+```
+
+### 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:
+```java
+Map<String, Object> properties = new HashMap<>();
+properties.put("price",100);
+properties.put("status",3);
+properties.put("#first_check_id","device_id");
+te.trackFirst("account_id", "distinct_id", "device_activation", properties);
+```
+
+<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 Event****s**
+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.
+```java
+Map<String, Object> properties = new HashMap<>();
+properties.put("price",100);
+properties.put("status",3);
+te.trackUpdate("account_id","distinct_id","UPDATABLE_EVENT","test_event_id",properties);
+
+Map<String, Object> protertiesNew = new HashMap<>();
+protertiesNew.put("status",5);
+te.trackUpdate("account_id", "distinct_id", "UPDATABLE_EVENT", "test_event_id", protertiesNew);
+```
+
+### 1.4 **Overwritable Events**
+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.
+```java
+Map<String, Object> properties = new HashMap<>();
+properties.put("price",100);
+properties.put("status",3);
+te.trackOverwrite("account_id","distinct_id", "OVERWRITE_EVENT","test_event_id", properties);
+
+Map<String, Object> protertiesNew = new HashMap<>();
+protertiesNew.put("status",5);
+te.trackOverwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "test_event_id", protertiesNew);
+```
+
+## **User Properties**
+User property setting APIs supported by the TE  include: `userSet`, `userSetOnce`, `userAdd`, `userAppend`, `userUniqAppend`, `userUnset`, `userDelete`.
+### 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:
+```java
+Map<String,Object> userProperties = new HashMap<String,Object>();
+userProperties.put("user_name", "TA");
+try {
+   te.userSet("account_id","distinct_id",userProperties);
+} catch (Exception e) {
+  System.out.println("except:"+e);
+}
+ 
+Map<String,Object> newUserProperties = new HashMap<String,Object>();
+newUserProperties.put("user_name", "TE");
+try {
+   te.userSet("account_id","distinct_id",newUserProperties);
+} catch (Exception e) {
+  System.out.println("except:"+e);
+}
+```
+
+### 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:
+```java
+Map<String,Object> userProperties = new HashMap<String,Object>();
+userProperties.put("first_payment_time","2018-01-01 01:23:45.678");
+try {
+     te.userSetOnce("account_id","distinct_id",userProperties);
+} catch (Exception e) {
+     System.out.println("except:"+e);
+}
+ 
+Map<String,Object> newUserProperties = new HashMap<String,Object>();
+newUserProperties.put("first_payment_time","2018-12-31 01:23:45.678");
+try {
+     te.userSetOnce("account_id","distinct_id",newUserProperties);
+} catch (Exception e) {
+     System.out.println("except:"+e);
+}
+```
+
+### 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:
+```java
+Map<String,Object> userProperties = new HashMap<String,Object>();
+userProperties.put("total_revenue",30);
+try {
+     te.userAdd("account_id","distinct_id",userProperties);
+} catch (Exception e) {
+     System.out.println("except:"+e);
+}
+
+Map<String,Object> newUserProperties = new HashMap<String,Object>();
+newUserProperties.put("total_revenue",648);
+try {
+    te.userAdd("account_id","distinct_id",newUserProperties);
+} catch (Exception e) {
+    System.out.println("except:"+e);
+}
+```
+
+<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.
+```java
+Map<String,Object> properties = new HashMap<String,Object>();
+List<String> list = new ArrayList<>();
+list.add("apple");
+list.add("ball");
+properties.put("user_list",list);
+ try{
+    te.userAppend("account_id", "distinct_id", properties);
+ } catch (Exception e) {
+    System.out.println("except:"+e);
+ }
+```
+
+### 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.
+```java
+Map<String,Object> properties = new HashMap<String,Object>();
+List<String> list = new ArrayList<>();
+list.add("apple");
+list.add("ball");
+properties.put("user_list",list);
+ 
+Map<String,Object> newProperties = new HashMap<String,Object>();
+List<String> newList = new ArrayList<>();
+newList.add("apple");
+newList.add("cube");
+newProperties.put("user_list", newList);
+try{
+   te.userAppend("account_id", "distinct_id", properties);
+   te.userAppend("account_id", "distinct_id",newProperties);
+   te.userUniqAppend("account_id", "distinct_id",newProperties);
+} catch (Exception e) {
+    System.out.println("except:"+e);
+}
+```
+
+### 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.
+```java
+try {
+    te.userUnset("account_id", "distinct_id", "key1", "key2", "key3");
+} catch (Exception e) {
+    System.out.println("except:"+e);
+}
+```
+
+### 2.7 userDelete
+You can call `userDelete` 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.
+```java
+try{
+   te.userDelete("account_id","distinct_id");
+} catch (Exception e) {
+   System.out.println("except:"+e);
+}
+```
+
+
+## **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. When the transmission fails due to network problems, it will retry 3 times. If it still fails, the data will be stored in the cache area. The size of the cache area can be set. The default is 50, that is, the cache area The maximum total number of reserved data is 50*20 (20 is the batch value for each upload, which can be set). 
+```java
+TDAnalytics te = null;
+try {
+    te = new TDAnalytics(new TDBatchConsumer("SERVER_URL", "APPID"));
+} catch (Exception ignored){
+
+}
+```
+
+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="DXcVbpVlgoMpTpxfItYcWRRnnbe" width="1674" height="1318" align="center"/>
+
+- If you use the private deployment version, you can customize the data tracking URL .
+### 3.2 Timed refresh
+By default, the SDK will only automatically report data based on the current data size. The SDK supports the scheduled refresh function, and you can configure the interval and autoFlush parameters in Config to enable the function of regularly reporting data.
+```java
+TDAnalytics te = null;
+try {
+    TDBatchConsumer.Config config = new TDBatchConsumer.Config();
+    config.setAutoFlush(true);
+    config.setInterval(10);
+    te = new TDAnalytics(new TDBatchConsumer("url", "appId", config));
+} catch (Exception ignored){}
+```