Flutter

Last updated 10/03/2026

This guide describes how to integrate the Flutter SDK into your project. Before you start, we recommend that you read the Data rules chapter.

Latest version: 3.3.3

Update time: 2026-08-05

Downloads: Source code

Note

This document applies to v3.0.0 and later. For earlier versions, see Flutter Integration Guide (V2)

1. Integrate the SDK

Add the thinking_analytics dependency to the pubspec.yaml file of your Flutter project:

dependencies:
  thinking_analytics: ^3.3.3

note

Versions after 3.3.0 support the HarmonyOS platform through Flutter For OpenHarmony. Flutter 3.7.12 and 3.22.0 are currently supported

The following features aren't supported on the HarmonyOS platform yet:

1. Custom time zones
2. Dynamic super properties for auto-tracked events
3. Connecting with the JS SDK (H5 integration)

2. Initialization

The ThinkingData SDK must be initialized after the user agrees to the Privacy Policy

note

For 3.3.0 and later, you don't need to add await

// Determine whether to enable data collection based on the privacy policy
import 'package:thinking_analytics/td_analytics.dart';
if (privacy policy authorized)
{
   //Initialize the SDK
   await TDAnalytics.init(APPID, SERVER_URL);
}

Parameters:

• APPID: The APPID of your project, which you can find on the Project Settings page in the AE backend

• SERVER_URL: The URL that data is uploaded to

  • If you use the cloud service, enter: https://global-receiver-ta.thinkingdata.cn
  • If you use an on-premises deployment, bind a domain name to the data collection URL and configure an HTTPS certificate: https://your-domain-for-data-collection

Android 9.0 and later restrict HTTP requests by default, so make sure you use HTTPS.

3. Common features

Before you use the common features, we recommend that you read the user identification rules. By default, the SDK generates a random number as the distinct ID and persists it locally. Before a user logs in, the distinct ID is used as the user's identifier. Note: The distinct ID changes when the user reinstalls the app or switches devices.

3.1 Set the account ID

When a user logs in, you can call login to set the user's account ID. The AE platform uses the account ID as the identifier, and the account ID you set is kept until logout is called. Calling login multiple times overwrites the previous account ID.

// The unique login identifier of the user, which corresponds to #account_id in the reported data. In this case, the value of #account_id is TA
TDAnalytics.login("TA");

login can be called multiple times. Each call checks whether the passed account ID is the same as the previously saved ID. If it is the same, the call is ignored; otherwise, the previous ID is overwritten.

This method does not upload a login event

3.2 Set super properties

Super properties are properties that every event carries. You can call setSuperProperties to set super properties. We recommend setting super properties before you send events. Some important properties, such as a user's membership level and source channel, need to be set in every event; in this case, you can set them as super properties.

TDAnalytics.setSuperProperties({
  "channel": "ta",//String
  "age": 1,//Number
  "isSuccess": true,//Boolean
  "birthday": DateTime.now(),//Time
  "object": {"key": "value"},//Object
  "object_arr": [{"key": "value"}],//Object group
  "arr": ["value"]//Array
});

Super properties are saved in the cache, so you don't need to call this every time the app starts. If you call setSuperProperties to upload a super property that was set before, the new value overwrites the previous one.

• Key is the name of the property and is of the string type. It must start with a letter, can contain only digits, letters, and underscores "_", and can be up to 50 characters long. Keys are not case-sensitive; AE converts all letters to lowercase
• Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

Event properties and user properties have the same requirements as super properties

3.3 Enable auto-tracking

The following code example enables the install, start, end, and crash events. To learn more about the auto-tracking capabilities of the SDK, see Auto-tracked events

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

3.4 Send events

We recommend that you set event properties and the conditions for sending events based on the document you prepared earlier. The event name is of the String type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive.

TDAnalytics.track('product_buy', properties: <String, dynamic>{'product_name': 'Product Name'});

The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.

3.5 Set user properties

For general user properties, you can call userSet to set them. Properties uploaded through this API overwrite the existing property values. If the user property did not exist before, it is created with the same type as the value passed in. The following example sets the user name:

TDAnalytics.userSet(<String, dynamic>{'user_name': 'TA'});  //username is now TA
TDAnalytics.userSet(<String, dynamic>{'user_name': 'TE'});  //userName is now AE

4. Best practices

The following sample code includes all of the operations above. We recommend using them in the following order:

import 'package:thinking_analytics/td_analytics.dart';
if (privacy policy authorized)
{
   //Initialize the SDK
   await TDAnalytics.init('APP_ID', 'https://SERVER_URL');
   //Enable auto-tracked events
   TDAnalytics.enableAutoTrack(TDAutoTrackEventType.APP_START |
    TDAutoTrackEventType.APP_END |
    TDAutoTrackEventType.APP_INSTALL |
    TDAutoTrackEventType.APP_CRASH);
   //If the user has logged in, you can set the user's account ID as the unique identifier
   TDAnalytics.login('TA');
   //After you set super properties, every event carries them
   TDAnalytics.setSuperProperties({
     "channel": "ta",//String
     "age": 1,//Number
     "isSuccess": true,//Boolean
     "birthday": DateTime.now(),//Time
     "object": {"key": "value"},//Object
     "object_arr": [{"key": "value"}],//Object group
     "arr": ["value"]//Array
    });
   //Send an event
   TDAnalytics.track('product_buy', properties: <String, dynamic>{'product_name': 'Product Name'});
   //Set user properties
   TDAnalytics.userSet(<String, dynamic>{'user_name': 'TE'});
}