---
code: flutter_sdk_installation
name: "Flutter "
wikiToken: OxdhwoyTDiS4kLknBKBcxZH3n7C
parentWikiToken: EaDPwgIujiz2GKk0rWxct8ZNn4g
updateTime: 1763002927000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=flutter_sdk_installation
---
# Flutter 

本指南将会介绍如何使用 Flutter SDK 接入您的项目。建议在接入开始前，先阅读数据规则一章。

**最新版本: **3.3.1

**更新时间: **2025-11-10

**资源下载:**** **源代码

::: warning 注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 Flutter 接入指南（V2）

::: 

### 一、集成 SDK

在您 Flutter 项目的 `pubspec.yaml` 文件中添加 `thinking_analytics` 依赖：

```
dependencies:
  thinking_analytics: ^3.3.1
```

<!-- unsupported block: 19 -->

在3.3.0之后的版本已经支持鸿蒙平台 Flutter For OpenHarmony，目前支持Flutter 3.7.12和3.22.0版本

鸿蒙平台暂不支持的功能如下：

1. 不支持自定义时区功能
1. 不支持自动采集事件的动态公共属性
1. 不支持JS打通
### 二、初始化

ThinkingData SDK需要在用户同意 《隐私政策》后初始化

<!-- unsupported block: 19 -->

3.3.0及之后的版本不需要加await

```
// 根据隐私协议判断是否开启数据采集
import 'package:thinking_analytics/td_analytics.dart';
if (授权隐私政策)
{
   //SDK初始化
   await TDAnalytics.init(APPID, SERVER_URL);
}
```

参数说明:

- `APPID`: 您的项目的 APPID，可通过在 AE 后台项目管理页面获取
- `SERVER_URL`: 数据上传的 URL
- 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
- 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名
<!-- unsupported block: 34 -->

由于 Android 9.0+ 默认限制 HTTP 请求，因此请务必使用 HTTPS 协议

### 三、常用功能

在使用常用功能之前，建议你先了解用户识别规则.SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地,用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

#### 3.1 设置账号ID

在用户进行登录时，可调用 `login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `logout` 之前一直保留。多次调用 `login` 将覆盖先前的账号 ID 。

```
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.*login*("TA");
```

`login` 可以多次调用，每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致，一致则忽略调用，不一致则会覆盖先前的 ID。

<!-- unsupported block: 34 -->

**该方法不会上传登录事件**

#### 3.2 设置公共事件属性

公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

```
TDAnalytics.setSuperProperties({
  "channel": "ta",//字符串
  "age": 1,//数字
  "isSuccess": true,//布尔
  "birthday": DateTime.now(),//时间
  "object": {"key": "value"},//对象
  "object_arr": [{"key": "value"}],//对象组
  "arr": ["value"]//数组
});
```

公共事件属性将会被保存到缓存中，无需每次启动 App 时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。

- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感，AE 会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

**事件属性、用户属性的要求与公共事件属性保持一致**

#### 3.3 开启自动采集

以下代码示例开启安装、启动、关闭事件，如果您想详细了解SDK的自动采集能力，可以查看自动采集功能详细介绍

```
TDAnalytics.*enableAutoTrack*(TDAutoTrackEventType.*APP_START *|
    TDAutoTrackEventType.*APP_END *|
    TDAutoTrackEventType.*APP_INSTALL *|
    TDAutoTrackEventType.*APP_CRASH*);
```

#### 3.4 发送事件

建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件。事件名称是 `String` 类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感。

```
TDAnalytics.track('product_buy', properties: <String, dynamic>{'product_name': '商品名'});
```

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

#### 3.5 设置用户属性

对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

```
TDAnalytics.userSet(<String, dynamic>{'user_name': 'TA'});  //此时username为TA
TDAnalytics.userSet(<String, dynamic>{'user_name': 'TE'});  //此时userName为TE
```

### 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

```
import 'package:thinking_analytics/td_analytics.dart';
if (授权隐私政策)
{
   //SDK初始化
   await TDAnalytics.*init*('APP_ID', 'https://SERVER_URL');
   //开启自动采集事件
   TDAnalytics.*enableAutoTrack*(TDAutoTrackEventType.*APP_START *|
    TDAutoTrackEventType.*APP_END *|
    TDAutoTrackEventType.*APP_INSTALL *|
    TDAutoTrackEventType.*APP_CRASH*);
   //如果用户已登录，可以设置用户的账号ID作为身份唯一标识
   TDAnalytics.login('TA');
   //设置公共事件属性以后，每个事件都会带有公共事件属性
   TDAnalytics.setSuperProperties({
     "channel": "ta",//字符串
     "age": 1,//数字
     "isSuccess": true,//布尔
     "birthday": DateTime.now(),//时间
     "object": {"key": "value"},//对象
     "object_arr": [{"key": "value"}],//对象组
     "arr": ["value"]//数组
    });
   //发送事件
   TDAnalytics.track('product_buy', properties: <String, dynamic>{'product_name': '商品名'});
   //设置用户属性
   TDAnalytics.userSet(<String, dynamic>{'user_name': 'TE'});
}
```
