Sensors Data Analytics

https://manual.sensorsdata.cn/sa/docs
Admin
Sensors Data Analytics is a comprehensive data analytics platform that enables user behavior...
Tokens:1,193,295
Snippets:13,011
Trust Score:9.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### SDK Initialization Example

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_c_install

Example demonstrating the initialization of the SALoggingConsumer and the Sensors Analytics SDK, followed by basic usage and cleanup.

```APIDOC
## SDK Initialization and Usage Example

### Description
This example shows how to initialize the logging consumer and the SDK, perform operations, flush data, and free resources.

### Code
```c
// Initialize Logging Consumer
SALoggingConsumer* consumer = NULL;
if (SA_OK != sa_init_logging_consumer("./demo.out", &consumer)) {
    fprintf(stderr, "Failed to initialize the consumer.");
    return 1;
}

SensorsAnalytics *sa = NULL;
if (SA_OK != sa_init(consumer, &sa)) {
    fprintf(stderr, "Failed to initialize the SDK.");
    return 1;
}

// ... Use Sensors Analytics for various operations

// Synchronize cached data to file or Sensors Analytics
sa_flush(sa);
// Free the Sensors Analytics instance
sa_free(sa);
```
```

--------------------------------

### Start LogAgent

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logagent

Execute the start script to run the LogAgent service.

```bash
bin/start
```

--------------------------------

### Track Event Examples

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_go_idm2

Examples demonstrating how to track user events like 'ViewProduct' and 'PaidOrder' with custom properties.

```APIDOC
## Track Event Examples

### Example 1: Tracking a Product View Event

This example shows how to track a user viewing a product, including system properties like timestamp and IP address, along with product-specific details.

```go
distinct_id := "ABCDEF123456"

properties := map[string]interface{}{
    // "$time" is a system-reserved property for the event timestamp (int64, milliseconds).
    // If provided, it overrides the SDK's default current time.
    "$time" : time.Now().UnixMilli(),
    // "$ip" is a system-reserved property. If provided with the user's IP address,
    // Sensors Analytics will automatically parse the user's province and city.
    "$ip" : "123.123.123.123",
    // Product ID
    "ProductId" : "123456",
    // Product Category
    "ProductCatalog" : "Laptop Computer",
    // Boolean property indicating if added to favorites
    "IsAddedToFav" : true,
}

// Track the user viewing a product event
err := sa.Track(distinct_id, "ViewProduct", properties, true)
```

### Example 2: Tracking an Order Paid Event

This example demonstrates tracking an order payment event, including a list of product IDs and the order amount.

```go
properties := map[string]interface{}{
    // User IP address
    "$ip" : "123.123.123.123",
    // List of Product IDs (string slice property)
    "ProductIdList" : []string{"123456", "234567", "234567"},
    // Order paid amount
    "OrderPaid" : 12.10,
}

// Track the user order paid event
err = sa.Track(distinct_id, "PaidOrder", properties, true)
```
```

--------------------------------

### Install Golang SDK

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_go_install

Instructions for installing or updating the Sensors Analytics Golang SDK using the go get command.

```APIDOC
## Install Golang SDK

To integrate the Sensors Analytics SDK into your Golang project, you can use the `go get` command.

### Install
```bash
go get github.com/sensorsdata/sa-sdk-go
```

### Update
```bash
go get -u github.com/sensorsdata/sa-sdk-go
```

Alternatively, you can download the source code from GitHub. The SDK requires Golang 1.6 or higher and does not depend on third-party libraries. Note that the Golang SDK does not support Windows.
```

--------------------------------

### Start Logstash with Inline Configuration

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logstash/v0300

Start Logstash with a simple inline output configuration, useful for testing or basic setups.

```bash
bin/logstash -e 'output { sensors_analytics { url => "https://example.sensorsdata.cn/sa" }}'
```

--------------------------------

### Example Usage: Initialization and Cleanup

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_lua_install/v0300

Demonstrates a complete workflow including initializing the logging consumer, initializing the SDK, performing operations, flushing data, and freeing SDK resources.

```APIDOC
## Example Usage

### Description
This example illustrates the typical lifecycle of using the Sensors Analytics Lua SDK, from initialization to cleanup.

### Code Example
```lua
-- Assume SA_FFI_OK is defined elsewhere and represents a successful operation
local SA_FFI_OK = 0

-- Initialize Logging Consumer
local consumer_res, consumer = sensors_analytics.sa_init_logging_consumer("demo.out")
if consumer_res ~= SA_FFI_OK then
    print("Failed to initialize the consumer.")
    return
end

-- Initialize Sensors Analytics SDK
local sa_res, sa = sensors_analytics.sa_init(consumer)
if sa_res ~= SA_FFI_OK then
    print("Failed to initialize the SDK.")
    return
end

-- ... Use the 'sa' instance for various operations (e.g., track events)

-- Flush any buffered data
sensors_analytics.sa_flush(sa)

-- Free the SDK resources
sensors_analytics.sa_free(sa)
```
```

--------------------------------

### Example: Track SubmitOrder Event with Properties

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_lua_api/v0300

Demonstrates how to initialize properties, add various attributes (OS, version, IP, product details), and track a 'SubmitOrder' event.

```lua
do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- Through the UA in the request, you can parse out that the operating system of the user's device is iOS.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$os", "iOS", strlen("iOS"), properties))
    -- The specific version of the operating system.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$os_version", "10.0.0", strlen("10.0.0"), properties))
    -- If the user's IP can be obtained from the request, pass it to SA, and SA will automatically parse the province and city based on this.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("$ip", "123.123.123.123", strlen("123.123.123.123"), properties))
    -- Product name.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("product_name", "XX手机", 8, properties))
    -- Product price.
    assert(SA_FFI_OK == sensors_analytics.sa_add_int("product_price", 5888, properties))
    -- Product discount.
    assert(SA_FFI_OK == sensors_analytics.sa_add_number("product_discount", 0.8, properties))
    -- Record the purchase event.
    assert(SA_FFI_OK == sensors_analytics.sa_track(cookie_id, "SubmitOrder", properties, sa))

    sensors_analytics.sa_free_properties(properties)
end
```

--------------------------------

### Start Logstash with Default Configuration

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logstash/v0300

Start Logstash using the default pipeline and runtime configurations found in the Logstash installation directory.

```bash
bin/logstash
```

--------------------------------

### 配置初始化参数

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_mp_wecode

Configure SDK initialization parameters using the `init()` method.

```APIDOC
## 配置初始化参数

引入 SDK 后，可通过 **init()** 进行 SDK 初始化参数配置：

```javascript
sensors.init({
	server_url: '您的数据接收地址',
	// 是否在控制台打印数据
	show_log: true,
	appid: '建议填写'
});
```

> * 在调用 **init()** 接口之前，采集的数据被缓存在内存中；调用 **init()** 接口后，会将缓存的数据通过网络发送出去。
```

--------------------------------

### Install Golang SDK

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_go_install/v0300

Use 'go get' to install the SensorsData Golang SDK. This command fetches the latest version of the SDK.

```bash
go get github.com/sensorsdata/sa-sdk-go
```

--------------------------------

### Example: Create a Tag

Source: https://manual.sensorsdata.cn/sa/docs/import_tag_segment/v0300

This example demonstrates how to create a tag with specified properties including project, name, display name, directory, matched field, data type, and entity. The --sync_profile flag indicates user synchronization.

```bash
# 标签
horizonadmin tag \
--tool tag_import_meta \
--project default \
--name user_tag_test_str1 \
--display_name str1 \
--dir /batch_import_test \
--matched_field user.$identity_distinct_id \
--sync_profile \
--data_type string \
--entity user
```

--------------------------------

### Get Import Task Example by Task ID

Source: https://manual.sensorsdata.cn/sa/docs/import_tag_segment/v0300

Example command to retrieve an import task's status using its unique task ID.

```bash
horizonadmin tag --tool import --method get_task --task_id 79
```

--------------------------------

### C# SDK Demo for E-commerce Tracking

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_cnet_demo/v0300

This snippet demonstrates basic SDK initialization, setting super properties, tracking user actions like page visits and product searches, associating registered users with anonymous IDs, and updating user profiles with various methods (Set, SetOnce, Append, Increment, Unset). It also includes item dimension management for setting and deleting item information.

```csharp
// LoggingConsumer
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);

// 设置公共属性, 以后上传的每一个事件都附带该属性 
Dictionary<string, Object> properties = new Dictionary<string, object>();
// 服务器应用版本
properties.Add("ServerVersion", "1.2");
// 服务器机房地址
properties.Add("Location", "BeiJing");
// 设置事件公共属性
sa.RegisterSuperPropperties(properties);

// 1. 用户匿名访问网站，cookieId 默认神策生成分配
String cookieId = "ABCDEF123456789";

// 1.1 访问首页
// 前面有 $ 开头的 property 字段，是 SA 提供给用户的预置字段
// 对于预置字段，已经确定好了字段类型和字段的显示名
Dictionary<string, Object> firstRecord = new Dictionary<string, object>();
firstRecord.Add("$time", DateTime.Now);
firstRecord.Add("Channel", "baidu");
firstRecord.Add("$project", "abc");
firstRecord.Add("$token", "123");
sa.Track(cookieId, "track", firstRecord);

// 1.2 搜索商品 
Dictionary<string, Object> searchRecord = new Dictionary<string, object>();
searchRecord.Add("KeyWord", "XX手机");
sa.Track(cookieId, "SearchProduct", searchRecord);

// 1.3 浏览商品
Dictionary<string, Object> lookRecord = new Dictionary<string, object>();
lookRecord.Add("ProductName", "XX手机");
lookRecord.Add("ProductType", "智能手机");
lookRecord.Add("ShopName", "XX官方旗舰店");
sa.Track(cookieId, "ViewProduct", lookRecord);

// 2. 用户注册登录之后，系统分配的注册 ID
// 注册用户的真实 ID
String registerId = "0012345678";
// 用户注册/登录时，将用户注册 ID 与匿名 ID 关联
sa.TrackSignUp(registerId, cookieId);

// 2.2 用户注册时，填充了一些个人信息，可以用 Profile 接口记录下来
Dictionary<string, Object> userRecord = new Dictionary<string, object>();
userRecord.Add("$city", "武汉");
userRecord.Add("$province", "湖北");
userRecord.Add("$name", "昵称123");
userRecord.Add("$signup_time", DateTime.Now);
userRecord.Add("Gender", "male");
userRecord.Add("age", 20);
// $is_login_id 属性判断 distinct_id 是否为登录 ID，如果是则设置为 true，否则为 false，默认为 false userRecord.Add("$is_login_id", true);
sa.ProfileSet(cookieId, userRecord);

// 2.3 设置首次访问时间
Dictionary<string, Object> firstVisitRecord = new Dictionary<string, object>();
firstVisitRecord.Add("$first_visit_time", DateTime.Now);
// $is_login_id 属性判断 distinct_id 是否为登录 ID，如果是则设置为 true，否则为 false，默认为 false
firstVisitRecord.Add("$is_login_id", true);
sa.ProfileSetOnce(cookieId, firstVisitRecord);

// 2.4 追加属性
List<String> newInterest = new List<String>();
newInterest.Add("ball");
Dictionary<string, Object> appendRecord = new Dictionary<string, object>();
appendRecord.Add("interest", newInterest);
sa.ProfileAppend(cookieId, appendRecord);

// 2.5 给属性加值
Dictionary<string, Object> incrementRecord = new Dictionary<string, object>();
incrementRecord.Add("age", 2);
sa.ProfileIncrement(cookieId, incrementRecord);

// 2.6 移除用户属性
sa.ProfileUnset(cookieId, "age");

// 物品纬度表上报
String itemId = "product001", itemType = "mobile";
Dictionary<string, Object> addRecord = new Dictionary<string, object>();
addRecord.Add("color", "white");
addRecord.Add("price", 31.54);
sa.ItemSet(itemType, itemId, addRecord);

// 删除物品纬度信息 
sa.ItemDelete(itemType, itemId);

```

--------------------------------

### Install Sensors Analytics Golang SDK

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_go_install

Use 'go get' to install or update the Sensors Analytics Golang SDK. Ensure you are using Golang 1.6 or later. Windows is not supported.

```bash
go get github.com/sensorsdata/sa-sdk-go
```

```bash
go get -u github.com/sensorsdata/sa-sdk-go
```

--------------------------------

### LTV Analysis Report API Request Example

Source: https://manual.sensorsdata.cn/sa/docs/queries_doc

This is a complete example of a request payload for the LTV Analysis Report API. It specifies the starting event, revenue measures, date range, time unit, dimensions, duration, and filtering conditions.

```json
{
    "start_sign":{
        "start_event":"$MPShow",
        "filters":{
            "conditions":[
                {
                    "field":"event.$Anything.$ip",
                    "function":"isSet",
                    "params":[

                    ]
                }
            ]
        }
    },
    "measures":[
        {
            "event_name":"activityview",
            "aggregator":"average",
            "name":"activityview的LTV_AVG",
            "profit_rate":100
        }
    ],
    "from_date":"2022-10-06",
    "to_date":"2022-10-12",
    "unit":"DAY",
    "by_fields":[
        "event.$Anything.$country"
    ],
    "duration":90,
    "use_cache":true,
    "filter":{
        "conditions":[
            {
                "field":"user.$country",
                "function":"notSet",
                "params":[

                ]
            },
            {
                "field":"user.$province",
                "function":"notSet",
                "params":[

                ]
            }
        ]
    },
    "bucket_params":{

    }
}
```

--------------------------------

### Initialize Sensors Analytics SDK

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_php_install/v0300

Demonstrates the basic initialization of the Sensors Analytics SDK in a PHP script. It includes setting the server URL, initializing a consumer (BatchConsumer in this example), and creating a SensorsAnalytics instance. It also shows how to track a user event and flush the data.

```APIDOC
## Initialize Sensors Analytics SDK

### Description
Demonstrates the basic initialization of the Sensors Analytics SDK in a PHP script. It includes setting the server URL, initializing a consumer (BatchConsumer in this example), and creating a SensorsAnalytics instance. It also shows how to track a user event and flush the data.

### Method
```php
<?php
	require_once("SensorsAnalytics.php");

	# Get the data receiving URL from the Sensors Analytics configuration page
	$SA_SERVER_URL = 'YOUR_SERVER_URL';

	# Initialize a Consumer for data sending
	# BatchConsumer sends data synchronously, so do not use this Consumer in any online services; use FileConsumer for production.
	$consumer = new BatchConsumer($SA_SERVER_URL);

	# Construct the SensorsAnalytics object using the Consumer
	$sa = new SensorsAnalytics($consumer);

	# Optionally, specify the project name when constructing the SensorsAnalytics object.
	# All subsequent data sent through this SensorsAnalytics object will be sent to this project.
	# $sa = new SensorsAnalytics($consumer, "project_name");

	# Example of triggering a user event for data sending test
	$distinct_id = 'ABCDEF123456789';
	$sa->track($distinct_id, true, 'UserLogin');

	# Ensure all buffered data is sent before the program exits
	$sa->flush();
?>
```

### Note
Replace **YOUR_SERVER_URL** with the actual data receiving URL obtained from the Sensors Analytics configuration page. The program should maintain the SDK instance until termination and explicitly close it using `close()` to prevent data loss.
```

--------------------------------

### Update Golang SDK

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_go_install/v0300

Use 'go get -u' to update the locally installed SensorsData Golang SDK to the latest version.

```bash
go get -u github.com/sensorsdata/sa-sdk-go
```

--------------------------------

### Example: Set User Profile Properties

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_c_api

Demonstrates setting user profile properties like registration channel, signup time, and VIP status using sa_profile_set.

```c
properties = sa_init_properties();
if (NULL == properties) {
    fprintf(stderr, "Failed to initialize the properties.");
    return 1;
}

// 用户的注册渠道
assert(SA_OK == sa_add_string("register", "AAA", 5, properties));
// 用户注册日期
assert(SA_OK == sa_add_date("$signup_time", time(NULL), 0, properties));
// 用户是否购买过商品
assert(SA_OK == sa_add_bool("is_vip", SA_FALSE, properties));
//  $is_login_id 属性判断 distinct_id 是否为登录 ID，如果是则设置为 SA_TRUE，否则为 SA_FALSE，默认为 SA_FALSE
assert(SA_OK == sa_add_bool("$is_login_id", SA_TRUE, properties);

// 设置用户属性
assert(SA_OK == sa_profile_set(login_id, properties, sa));

sa_free_properties(properties);
```

--------------------------------

### Example: Create a Segment

Source: https://manual.sensorsdata.cn/sa/docs/import_tag_segment/v0300

This example shows how to create a segment with properties like project, name, display name, matched field, and entity. The --sync_profile flag is used for user synchronization.

```bash
# 分群
horizonadmin segment \
--tool segment_import_meta \
--project default \
--name user_segment_test_str1 \
--display_name str1 \
--matched_field user.$identity_distinct_id \
--sync_profile \
--entity user
```

--------------------------------

### uni-app SDK Initialization

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_mp_wechat

In uni-app, install the SDK via npm and import it in main.js before initializing. This example uses the IDM 3.0 initialization method.

```javascript
import Vue from 'vue';
import sensors from '/dist/wechat/sensorsdata.esm.js'    

// 这里举例使用的是全域用户关联 - IDM 3.0 初始化方式 ,也可以按实际需求换成上面 1.1 中的简易用户关联 - IDM 2.0 初始化方式 
sensors.init({
    name: 'sensors',
    server_url: '您的数据接收地址',
    show_log: true
});  
 
import App from './App';
Vue.config.productionTip = false;
  
App.mpType = 'app';
  
const app = new Vue({
    ...App
});
app.$mount();
```

--------------------------------

### Enable All Auto-Track Events

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_android_super

Configure which auto-track event types to enable. This example enables app start, end, screen view, and click events.

```java
List<SensorsDataAPI.AutoTrackEventType> list = new ArrayList<>();
list.add(SensorsDataAPI.AutoTrackEventType.APP_START);
list.add(SensorsDataAPI.AutoTrackEventType.APP_END);
list.add(SensorsDataAPI.AutoTrackEventType.APP_VIEW_SCREEN);
list.add(SensorsDataAPI.AutoTrackEventType.APP_CLICK);
SensorsDataAPI.sharedInstance().enableAutoTrack(list);
```

--------------------------------

### Windows Path Configuration Example

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logagent

Demonstrates how to configure the 'path' parameter in a LogAgent configuration file for Windows, requiring double backslashes for directory separators.

```properties
path=D:\\data\\logs
```

--------------------------------

### SDK Initialization and Configuration

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_mp_wechat/v0300

Configure the SDK with the server URL and enable logging for debugging.

```APIDOC
## SDK 基本配置
### 配置项目数据接收地址
如下图所示获取数据接收地址：
>   * 获取到数据接收地址之后在 init 接口中设置 server_url，server_url 的域名需要按照微信小程序要求（https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html）配置到微信后台 request 合法域名列表中。
> 

### 设置事件公共属性
对于所有事件都需要添加的属性，可在初始化 SDK 前，调用 **registerApp()** 将属性注册为公共属性：
```javascript
getApp().sensors.registerApp({
	userLever: 'VIP3',
	userSex: '男'
});
```

Copy
> 需要在 App 实例化之前调用 registerApp() 方法完成公共属性的注册，否则会导致部分数据采集不到注册的公共属性。
### 用户关联
用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联，分别用于支撑不同的业务场景。
  * 简易用户关联（IDM 2.0）
  * 全域用户关联（IDM 3.0）


### 代码埋点追踪事件
SDK 初始化后，可通过 **track()** 方法追踪用户行为事件，并为事件添加自定义属性：
```javascript
sensors.track(event_name[properties]);
```

Copy
配置参数：
参数 | 必填 | 描述  
---|---|---  
`event_name` | 是 | 事件名称  
`properties` | 否 | 为用户行为事件添加自定义属性，类型：Object。  
示例：
```javascript
// 为 click 事件添加自定义属性 name 值为点击。
getApp().sensors.track('click',{
	name: '点击'
});
```

Copy
> 事件名和事件属性的格式规范，请参考 数据格式。
## 调试查看事件信息
### 事件的触发日志
**init()** 配置初始化参数时，通过 **show_log: true** 打开 Log 功能且 SDK 完成初始化后（即 **init()** 方法调用后），微信开发者工具 **console** 会打印采集的数据信息：
### 事件的发送情况
事件数据发送成功时，可以在微信开发者工具的 **Network** 模块中，可以看到 **sa** 的请求：
## SDK 可选配置
### 设置用户属性
**setProfile( properties )** 可以设定用户属性，同一个 key 多次设置时，value 值会进行覆盖替换：
```javascript
getApp().sensors.setProfile({
	email:'xxx@xx',
	favoriteFruits: ['苹果', '油桃'],
	subscribers: 7277
});
```

Copy
>   * 关于事件属性和用户属性的区别，请参考 数据模型
>   * 用户属性的命名约束，请参考 数据格式
>   * 用户属性其他设置方法，请参考 用户属性设置
> 

### 渠道追踪
用户通过含有 **utm** 相关参数的路径访问小程序时，预置事件 **$MPLaunch、$MPShow、$MPViewScreen** 会解析启动路径中的 **utm** 相关参数作为自身的属性与属性值，并会设置 **$latest_utm** 相关属性到所有事件中，该特性在小程序的生命周期内有效。

```

--------------------------------

### Initialize SensorsAnalytics with ConcurrentLoggingConsumer (Java)

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logagent_example/v0300

Initialize SensorsAnalytics to output data to files using ConcurrentLoggingConsumer. This example shows how to set the output directory and start tracking user behavior.

```java
final SensorsAnalytics sa = new SensorsAnalytics(
        new SensorsAnalytics.ConcurrentLoggingConsumer("/data/sa/service_log")); 

sa.track(distinctId, true, "UserLogin");
sa.track(distinctId, true, "ViewProduct");

sa.shutdown();
```

--------------------------------

### Example: Setting User Properties (Lua)

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_server_lua_api

Demonstrates initializing properties, adding string, date, and boolean attributes, and then setting them for a user. Ensure properties are freed after use.

```lua
do
    properties = sensors_analytics.sa_init_properties()
    if nil == properties then
        return error("Failed to initialize the properties.")
    end

    -- 用户的注册渠道.
    assert(SA_FFI_OK == sensors_analytics.sa_add_string("register", "AAA", 5, properties))
    -- 用户注册日期.
    assert(SA_FFI_OK == sensors_analytics.sa_add_date("$signup_time", os.time(), 0, properties))
    -- 用户是否购买过商品.
    assert(SA_FFI_OK == sensors_analytics.sa_add_bool("is_vip", false, properties))
    -- 设置用户属性.
    assert(SA_FFI_OK == sensors_analytics.sa_profile_set(login_id, properties, sa))

    sensors_analytics.sa_free_properties(properties)
end
```

--------------------------------

### mpvue SDK Initialization

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_mp_wechat

In mpvue projects, install the SDK via npm and import it in main.js before Vue. Initialize the SDK with your server URL. This example uses the IDM 3.0 initialization.

```javascript
import sensors from '/dist/wechat/sensorsdata.esm.js'
import Vue from 'vue';
import App from './App';  
  
// 这里举例使用的是全域用户关联 - IDM 3.0 初始化方式 ,也可以按实际需求换成上面 1.1 中的简易用户关联 - IDM 2.0 初始化方式   
sensors.init({
    name: 'sensors',
    server_url: '您的数据接收地址',
    show_log: true
});

Vue.config.productionTip = false;

App.mpType = 'app';
 
const app = new Vue(App);
app.$mount();
```

--------------------------------

### 记录激活事件 (Swift)

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_ios_channel/v0300

调用此方法记录应用激活事件。SDK 会在首次调用时触发，后续调用无效。建议使用 `trackAppInstall` 替代旧的 `trackInstallation`。

```Swift
// 首次接入神策 SDK，请使用 trackAppInstall，如果之前使用了 trackInstallation，也建议尽快改成 trackAppInstall，原有的激活事件需要合并看数的话使用 虚拟事件 将原激活事件和 $AppInstall 合并分析数据。如果因为暂时无法修改接口，也可以继续用 trackInstallation
SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])
```

--------------------------------

### Using Macros for Date Range

Source: https://manual.sensorsdata.cn/sa/docs/dynamic_parameter/v0300

Example of using two macro dynamic parameters to define a date range for a SQL query. This enables dynamic selection of start and end dates.

```sql
date between ${start_date} and ${end_date}
```

--------------------------------

### 初始化 SDK (Swift)

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_ios_use/v0300

在 AppDelegate 的 didFinishLaunchingWithOptions 方法中初始化神策分析 SDK。配置数据接收地址，并可选择开启全埋点和日志输出。

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         
    let options = SAConfigOptions.init(serverURL: <#数据接收地址#>, launchOptions: launchOptions)
      
    //开启全埋点
    options.autoTrackEventType = [.eventTypeAppStart, .eventTypeAppEnd, .eventTypeAppClick, .eventTypeAppViewScreen]
#ifdef DEBUG
    //开启log
    options.enableLog = true
#endif
 	/**
	 * 其他配置，如开启可视化全埋点 
	 */
    //初始化SDK
    SensorsAnalyticsSDK.start(configOptions: options)
         
    return true
     
}
```

--------------------------------

### File-list-tool: Get Read Progress

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logagent

Use the file-list-tool to retrieve the current reading progress. Specify the context file path. Add --not start if LogAgent has encountered progress errors.

```bash
bin/file-list-tool --context_file ./logagent.pid.context 
//context_file 为进度文件 logagent.pid.context 的路径，如果 loagegnt 已经出现进度错误，需要再加 --not start 参数
```

--------------------------------

### 记录激活事件

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_ios_channel/v0300

调用 `trackAppInstallWithProperties:` 方法记录激活事件。多次调用此方法只会在第一次调用时触发激活事件。

```APIDOC
## 记录激活事件

### Description
可以调用 `- trackAppInstallWithProperties:` 方法记录激活事件，多次调用此方法只会在第一次调用时触发激活事件。

### Objective-C
```objectivec
// 首次接入神策 SDK，请使用 trackAppInstall，如果之前使用了 trackInstallation，也建议尽快改成 trackAppInstall，原有的激活事件需要合并看数的话使用 虚拟事件 将原激活事件和 $AppInstall 合并分析数据。如果因为暂时无法修改接口，也可以继续用 trackInstallation
[[SensorsAnalyticsSDK sharedInstance] trackAppInstallWithProperties:@{@"DownloadChannel": @"AppStore"}];
```

### Swift
```swift
// 首次接入神策 SDK，请使用 trackAppInstall，如果之前使用了 trackInstallation，也建议尽快改成 trackAppInstall，原有的激活事件需要合并看数的话使用 虚拟事件 将原激活事件和 $AppInstall 合并分析数据。如果因为暂时无法修改接口，也可以继续用 trackInstallation
SensorsAnalyticsSDK.sharedInstance()?.trackAppInstall(withProperties: ["DownloadChannel": "AppStore"])
```

> 注意
> 若用原记录的激活事件名不是 $AppInstall，需要使用 虚拟事件 将原激活事件和 $AppInstall 合并分析数据，具体咨询 **神策技术顾问**
```

--------------------------------

### Consume Data from Kafka Example

Source: https://manual.sensorsdata.cn/sa/docs/subscribe_data_to_kafka

Reference the Kafka subscription sample to implement data consumption. This section guides users on how to process data received in the Kafka cluster after a successful subscription.

```text
参考 Kafka 订阅样例 实现数据消费
```

--------------------------------

### Get Channel Links List Response Example

Source: https://manual.sensorsdata.cn/sa/docs/channel_doc/v0300

This JSON object shows a successful response from the channel links list API. It includes pagination details and a list of channel link results.

```json
{
    "code":"SUCCESS",
    "request_id":"09511615f0f14802af19fada2c95ba37",
    "data":{
        "total_rows":"5",
        "total_page":5,
        "page_num":0,
        "detail_results":[
            {
                "id":1,
                "name":"APP 通用渠道_测试活动_20230203_4996",
                "channel_type":"app_normal",
                "device_type":"通用",
                "short_url":"http://{hostname}:{port}/r/U",
                "app_address":"http://{hostname}:{post}/sa/channel_sa/link_manage?project=default&utm_source=%E6%B5%8B%E8%AF%95%E6%9D%A5%E6%BA%90&utm_campaign=%E6%B5%8B%E8%AF%95%E7%9A%84%E6%B4%BB%E5%8A%A8%25%25&test=%E8%87%AA%E5%AE%9A%E4%B9%89%E5%B1%9E%E6%80%A7&_channel_track_key=U9itljXH",
                "parameters":{
                    "utm_campaign":"测试活动"
                },
                "project_id":1,
                "create_time":"2023-02-03 16:19:57",
                "update_time":"2023-02-03 16:19:57",
                "short_url_id":0,
                "channel_track_key":"U9itljXH",
                "is_show_whole_url":1
            },
            {
                "id":2,
                "name":"App Deeplink 通用渠道_测试应用_20230112_5511",
                "channel_type":"app_deeplink",
                "device_type":"通用",
                "short_url":"https://{hostname}:{port}/sd/xfA/A/W1uy30",
                "app_address":"",
                "parameters":{
                    "utm_campaign":"测试活动"
                },
                "project_id":1,
                "create_time":"2023-01-12 18:11:40",
                "update_time":"2023-01-12 18:11:40",
                "short_url_id":0
            }
        ]
    }
}
```

--------------------------------

### $SignUp Event Data Example

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_web_idm2/v0300

This is an example of the event data structure generated automatically when sensors.login() is called. It includes user identification, library information, and event properties.

```json
{
  "distinct_id": "login_user_xx",              
  "login_id": "login_user_xx",                 
  "anonymous_id": "18e84929a117c0-0147a34acc60ec-1c525637-1296000-18e84929a1276c",
  "original_id": "18e84929a117c0-0147a34acc60ec-1c525637-1296000-18e84929a1276c", 
  "event": "$SignUp",                         
  "lib": {
    "$lib": "js",
    "$lib_method": "code",
    "$lib_version": "1.26.7"
  },
  "identities": {
    "$identity_cookie_id": "18e84929a117c0-0147a34acc60ec-1c525637-1296000-18e84929a1276c",   
    "$identity_anonymous_id": "18e84929a117c0-0147a34acc60ec-1c525637-1296000-18e84929a1276c",
    "$identity_login_id": "login_user_xx"
  },
  "properties": {
    "$timezone_offset": -480,
    "$screen_height": 900,
    "$screen_width": 1440,
    "$viewport_height": 235,
    "$viewport_width": 1440,
    "$lib": "js",
    "$lib_version": "1.26.7",
    "$latest_traffic_source_type": "直接流量",
    "$latest_search_keyword": "未取到值_直接打开",
    "$latest_referrer": "",
    "$url": "http://xx.com/index.html",
    "$title": "bbbb"
  },
  "type": "track_signup",
  "time": 1711621966237,
  "_track_id": 785456237,
  "_flush_time": 1711621966237
}
```

--------------------------------

### Enabling Full Auto-Tracking

Source: https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_flutter_auto_track

To enable full auto-tracking, you need to set the `autoTrackTypes` parameter during the initialization of the SensorsAnalyticsFlutterPlugin. This example shows how to enable tracking for app start, screen views, element clicks, and app end.

```APIDOC
## Enabling Full Auto-Tracking

To enable full auto-tracking, set `autoTrackTypes` during plugin initialization:

```dart
import 'package:sensors_analytics_flutter_plugin/sensors_analytics_flutter_plugin.dart';
 
... 
@override
void initState() {
  // Initialize SDK
  SensorsAnalyticsFlutterPlugin.init(
    serverUrl: "<#Data Receiving Address#>".
    enableLog: true,
    autoTrackTypes: <SAAutoTrackType> {
      SAAutoTrackType.APP_START,  // App Start
      SAAutoTrackType.APP_VIEW_SCREEN,  // Screen View
      SAAutoTrackType.APP_CLICK, // Element Click
      SAAutoTrackType.APP_END   // App End
    }
    ...);
 
  super.initState();
}
```
```

--------------------------------

### LogAgent Configuration Check Output Example

Source: https://manual.sensorsdata.cn/sa/docs/tech_import_logagent

An example of the output from the `bin/logagent --show_conf` command, showing agent version, ID, source configuration, and service URI.

```log
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent version: SensorsAnalytics LogAgent_20170922
17/09/22 15:16:27 INFO logagent.LogAgentMain: Use FQDN as LogAgentID
17/09/22 15:16:27 INFO logagent.LogAgentMain: LogAgent ID: test01.sa
17/09/22 15:16:27 INFO logagent.LogAgentMain: Source config, path: '/home/work/data', pattern: 'service_log.*'
17/09/22 15:16:27 INFO logagent.LogAgentMain: Service Uri: http://10.10.90.131:8106/log_agent
17/09/22 15:16:27 INFO logagent.LogAgentMain: Sender Type: BatchSender
17/09/22 15:16:27 INFO logagent.LogAgentMain: Pid file: /home/work/logagent/logagent.pid
```
Tokens:
Raw