@thinkingai/ae-cli 1.0.28 → 6.0.16

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

@@ -0,0 +1,173 @@
+---
+code: php_sdk_installation
+name: "PHP"
+wikiToken: G0BrwOPbXiAtIikbcv3cMEyonTf
+parentWikiToken: IKVPwn4NfiIhijk5EcAcMf6pn7e
+updateTime: 1774252016000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=php_sdk_installation
+---
+
+::: tip
+Before you begin, please read [<text color="purple" underline="true">Preparation before Data Ingestion</text>](https://thinkingdata.feishu.cn/wiki/OhD8we9iai6Xk5kM1QNc8ITRnQe).
+The minimum compatible PHP version is 5.5
+ :::
+**Latest version**: v3.1.1
+**Update time**: 2024-07-24
+**Resource download: **[**Source Code**](https%3A%2F%2Fgithub.com%2FThinkingDataAnalytics%2Fphp-sdk)
+::: warning Notice 
+Current documentation applies to v3.0.0 and later. For historical versions, see [Data Ingestion Guide - PHP (V2)](https%3A%2F%2Fdocs.thinkingdata.cn%2Fta-manual%2Fv4.1%2Fen%2Finstallation%2Finstallation_menu%2Fserver_sdk%2Fphp_sdk_installation%2Fphp_sdk_installation.html) 
+:::
+## **SDK**** Integration**
+1.1 With the Composer integration SDK, place the following dependency information in the `composer.json` file (recommended):
+```json
+{
+    "require": {
+        "thinkinggame/ta-php-sdk": "v3.1.1"
+    }
+}
+```
+
+1.2 You can also download the SDK [source code](https%3A%2F%2Fgithub.com%2FThinkingDataAnalytics%2Fphp-sdk) from GitHub and integrate it into your project. Just put `TaPhpSdk.php` in the directory of your project.
+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:
+```php
+require_once "vendor/autoload.php";
+
+use Exception;
+use ThinkingData\TDLog;
+use ThinkingData\TDAnalytics;
+use ThinkingData\TDFileConsumer;
+use ThinkingData\TDDebugConsumer;
+use ThinkingData\TDBatchConsumer;
+use ThinkingData\ThinkingDataException;
+
+TDLog::$enable = true;
+
+$consumer = new TDFileConsumer("LOG_DIRECTORY", 200, true, "LOG_FILE_PREFIX");
+$teSDK = new TDAnalytics($consumer, true);
+```
+
+`LOG_DIRECTORY` is the path of the folder written to the local directory. You need to set the `LogBus` listening folder address to this address in order to use `LogBus` for data listening upload.
+`LOG_FILE_PREFIX` Indicates the prefix of the log file name.
+## **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:
+```php
+$account_id = 2121;
+$distinct_id = 'SJ232d233243';
+$properties = array();
+$properties['age'] = 20;
+$properties['Product_Name'] = 'c';
+$properties['update_time'] = date('Y-m-d H:i:s', time());
+$json = array();
+$json['a'] = "a";
+$json['b'] = "b";
+$jsonArray = array();
+$jsonArray[0] = $json;
+$jsonArray[1] = $json;
+$properties['json'] = $json;
+$properties['jsonArray'] = $jsonArray;
+
+try {
+    $teSDK->track($distinct_id, $account_id, "viewPage", $properties);
+} catch (Exception $e) {
+    echo $e;
+}
+```
+
+- 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 `user_set` 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: 
+```php
+$properties = array();
+$properties['once_key'] = 'twice';
+$properties['age'] = 10;
+$properties['money'] = 300;
+$properties['array1'] = ['str1', 'str2'];
+try {
+    $teSDK->user_set('distinct_id', 'account_id', $properties);
+} catch (Exception $e) {
+    //handle except
+    echo $e;
+}
+```
+
+### 3.3 Reported data
+When using `TDFileConsumer`, the captured events are converted to json strings and then added to the cache array. Data is written to disk only when the number of array elements exceeds the set capacity. The default capacity is 100.
+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.
+```php
+$te->flush();
+```
+
+### 3.4 Close  SDK
+```php
+try{
+  $te->close();
+}catch (Exception $e){
+    echo $e;
+}
+```
+
+<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:
+```php
+require_once "vendor/autoload.php";
+
+use Exception;
+use ThinkingData\TDLog;
+use ThinkingData\TDAnalytics;
+use ThinkingData\TDFileConsumer;
+use ThinkingData\TDDebugConsumer;
+use ThinkingData\TDBatchConsumer;
+use ThinkingData\ThinkingDataException;
+
+TDLog::$enable = true;
+
+$consumer = new TDFileConsumer("LOG_DIRECTORY", 200, true, "te");
+$teSDK = new TDAnalytics($consumer, true);
+
+$account_id = 2121;
+$distinct_id = 'SJ232d233243';
+$properties = array();
+$properties['age'] = 20;
+$properties['Product_Name'] = 'c';
+$properties['update_time'] = date('Y-m-d H:i:s', time());
+$json = array();
+$json['a'] = "a";
+$json['b'] = "b";
+$jsonArray = array();
+$jsonArray[0] = $json;
+$jsonArray[1] = $json;
+$properties['json'] = $json;
+$properties['jsonArray'] = $jsonArray;
+
+try {
+    $teSDK->track($distinct_id, $account_id, "viewPage", $properties);
+} catch (Exception $e) {
+    echo $e;
+}
+
+$properties = array();
+$properties['once_key'] = 'twice';
+$properties['age'] = 10;
+$properties['money'] = 300;
+$properties['array1'] = ['str1', 'str2'];
+try {
+    $teSDK->user_set($distinct_id, $account_id, $properties);
+} catch (Exception $e) {
+    //handle except
+    echo $e;
+}
+```

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

@@ -0,0 +1,40 @@
+---
+code: python_sdk_debug
+name: "Debugging and Logging"
+wikiToken: A9VMwEVbTita7OkZ5TYczfF4nvh
+parentWikiToken: XX8ZwpG3ziIdr2kuJ3Vcx7m7n7b
+updateTime: 1774249278000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=python_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
+```python
+TDAnalytics.enableLog(isPrint=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:
+```python
+te = TDAnalytics(TDDebugConsumer("https://receiver-ta-demo.thinkingdata.cn", "appId", device_id="123456789"))
+distinct_id = "ABD"
+account_id = "11111"
+try:
+    te.track(account_id=account_id, event_name='event_name', properties={'level': 0})
+except Exception as e:
+    print(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="Drhnbw8E4ohg5uxXU1JcrdBlnHf" 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/python/python-advanced/preset-properties.md

@@ -0,0 +1,126 @@
+---
+code: python_sdk_preset_properties
+name: "Preset Properties"
+wikiToken: Nqb9wjvJbi9kd0kSjvtctMeentW
+parentWikiToken: XX8ZwpG3ziIdr2kuJ3Vcx7m7n7b
+updateTime: 1774249280000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=python_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/python/python-advanced.md

@@ -0,0 +1,206 @@
+---
+code: python_sdk_advanced
+name: "Python-Advanced"
+wikiToken: XX8ZwpG3ziIdr2kuJ3Vcx7m7n7b
+parentWikiToken: YoPdwzGBMiRyS7kTY5pcmWHpnjf
+updateTime: 1774249276000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=python_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:
+```python
+distinct_id = "ABCDEF123456"
+account_id = "TE10001"
+properties = {
+    "#time": datetime.datetime.now(),
+    "#ip": "192.168.1.1",
+    "Product_Name": "商品名",
+    "Price": 30,
+    "OrderId": "订单号abc_123"
+}
+
+try:
+    te.track(distinct_id, account_id, "Payment", properties)
+except Exception as e:
+    print(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:
+```python
+try:
+    properties = {'name': 'hello'}
+    te.track_first(account_id="account_id", distinct_id="distinct_id", event_name='first_event', first_check_id='first_flag_id', properties=properties)
+except Exception as e:
+    raise TDIllegalDataException(e)
+```
+
+<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.
+```python
+distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
+account_id = "123"
+event_name = "UPDATABLE_EVENT"
+event_id = "123"
+properties = {
+    "price": 100,
+    "status": 3
+}
+
+te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
+                properties=properties)
+
+new_properties = {
+    "status": 5
+}
+te.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
+                properties=new_properties)
+```
+
+### 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.
+```python
+distinct_id = "65478cc0-275a-4aeb-9e6b-861155b5aca7"
+account_id = "123"
+event_name = "OVERWRITE_EVENT"
+event_id = "123"
+properties = {
+    "price": 100,
+    "status": 3
+}
+
+te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
+                   properties=properties)
+
+new_properties = {
+    "status": 5
+}
+te.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id,
+                   properties=new_properties)
+```
+
+## **User Properties**
+User property setting APIs supported by the TE  include: `user_set`, `user_setOnce`, `user_add`, `user_append`, `user_uniq_append`, `user_unset`, `user_delete`.
+### 2.1 user_set
+You can call `user_set` 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:
+```python
+properties = {"user_name": "ABC"}
+try:
+    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
+    properties = {"user_name": "XYZ"}
+    te.user_set(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    print(e)
+```
+
+### 2.2 user_setOnce
+If the user property you want to upload only needs to be set once, you can call `user_setOnce` 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:：
+```python
+properties = {"user_name": "ABC"}
+try:
+    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    print(e)
+    
+properties = {
+    "user_name": "XYZ",
+    "user_age": 18
+}
+try:
+    te.user_setOnce(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    print(e)
+```
+
+### 2.3 user_add
+When you want to upload numeric property for cumulative operation, you can call `user_add`.
+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:
+```python
+properties = {
+    "total_revenue": 30,
+    "vip_level": 1
+}
+te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)
+
+properties = {"total_revenue": 90}
+try:
+    te.user_add(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    print(e)
+```
+
+<quote-container>
+The property key is a string, and the value is only allowed to be a numeric value.
+</quote-container>
+
+### 2.4 user_append
+You can call `user_append` to add user properties of array type.
+```python
+list1 = ['Google']
+properties = {'arrKey1': list1, 'arrKey2': ['11', '22']}
+try:
+    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    print(e)
+```
+
+### 2.5 user_uniq_append
+You can delete duplicated user property by calling `user_uniq_append` interface. If you call `user_append` interface, duplicated user property might not be deleted.
+```python
+arrayValue = ['Google', 'True', '2.222']
+properties = {'arrKey4': arrayValue, 'arrKey3': ['appendList', '222'], 'dict1': {'name': 'Tom', 'Age': 28}}
+try:
+    te.user_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    raise TDIllegalDataException(e)
+
+properties = {'arrKey4': ['addValue', 'True'], 'arrKey3': ['appendList', '222']}
+try:
+    te.user_uniq_append(account_id="account_id", distinct_id="distinct_id", properties=properties)
+except Exception as e:
+    raise TDIllegalDataException(e)
+```
+
+### 2.6 user_unset
+When you need to clear the user properties of users, you can call `user_unset` to clear specific properties. `user_unset` would not create properties that have not been created in the cluster.
+```python
+try:
+    te.user_unset("distinct_id", "account_id", ["string1", "lastTime"])
+except Exception as e:
+    print(e)
+```
+
+### 2.7 user_del
+You can call `user_del` 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.
+```python
+try:
+    te.user_del(account_id="account_id", distinct_id="distinct_id")
+except Exception as e:
+    print(e)
+```
+
+## **Other**
+### 3.1 TDBatchConsumer
+::: 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.
+```python
+te = TDAnalytics(TDBatchConsumer("SERVER_URL", "APP_ID"))
+```
+
+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="GadIbWzPAoPOBwx1Sbbcwa2BnBb" 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/python/release-notes.md

@@ -0,0 +1,51 @@
+---
+code: python_sdk_release_note
+name: "Release Notes"
+wikiToken: J30hwY6JOiFI3lknMssc7KBrnte
+parentWikiToken: YoPdwzGBMiRyS7kTY5pcmWHpnjf
+updateTime: 1774249282000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=python_sdk_release_note
+---
+## v3.0.0
+**Date：2023/09/21**
+**Notes：**
+- Warning: Class name replacement, incompatible with older versions
+## v2.1.3
+**Date：2023/03/02**
+**Notes：**
+- Bugfix: fix dynamic wrong type
+## v2.1.1
+**Date：2023/03/01**
+**Notes：**
+- Clean up example program
+## v2.1.0
+**Date：2022/12/22**
+**Notes：**
+- Add debug model in TE
+## v2.0.0
+**Date：****2022/08/03**
+**Notes：**
+- Add test cases
+## v1.8.0
+**Date：****2022/04/26**
+**Notes：**
+- Supports First Event
+## v1.7.0
+**Date：****2021/12/29**
+**Notes：**
+- Added support for complex structure types
+## v1.6.2
+**Date：****2021/08/05**
+**Notes：**
+- Fix the problem that the flush method does not refresh the file date
+## v1.6.1
+**Date：****2021/06/04**
+**Notes：**
+- Modify LoggingConsumer's default write file condition to write 5 pieces of data once
+- Modify the default maximum buffer limit of BatchConsumer to 50 batches
+## v1.6.0
+**Date：****2021/03/22**
+**Notes：**
+- Added network failure retry mechanism
+- Increase the buffer area, retry 3 times to send failed data will be stored in the buffer area, the cache data exceeds the upper limit will discard the early data
+- Support #app_id attribute