目录
此内容是否有帮助?

# Flutter SDK User Guide

This guide describes how to access your project using the Flutter SDK. It is recommended to read the Data Rules chapter before accessing. You can get the source code of the Flutter SDK at GitHub (opens new window).

**The latest version is **: 2.0.2

**Update time is **: 2021- 12 - 31

# I. Initialize SDK

# 1.1 Integrated Counting Flutter Plugin

Add thinking_analyticsdependencies to the pubspec.yamlfile of your Flutter project:

dependencies:
  # thinkingdata Flutter plugin
  thinking_analytics: ^2.0.2

# 1.2 Using the Flutter Plugin

First import the Count Flutter package into your code:

import 'package:thinking_analytics/thinking_analytics.dart';

Get ThinkingAnalytics APIinstance:

final ThinkingAnalyticsAPI ta = await ThinkingAnalyticsAPI.getInstance('APP_ID', 'https://SERVER_URL');

Parameter description:

  • APP_ID: The APP_ID of your project will be given when you apply for the project. You can view it on the TA background project management page. Please fill it in here.
  • SERVER URL: The URL of the data receiving end:
    • If you are using Cloud as a Service, enter the following URL:
      • https://receiver.ta.thinkingdata.cn
    • If you are using the version of private deployment, enter the following URL:
      • https://YOU_SERVER_URL

Then you can report the data through the tainstance:

// Report a simple event
ta.track('simple_event');

# 1.3 Other Initialization Parameters

You can configure the SDK by passing in more named parameters during initialization.

# timeZone

By default, the occurrence time of all data is set to local time. If your product is spread across multiple time zones and you want to assign the data time to the specified time zone, you can set the time zone by passing in timeZone. TimeZoneneeds to be a valid time zone string, such as UTC, Asia/Shanghai, etc.

# mode

By default, the SDK runs in ThinkingAnalytics Mode. NORMALmode, where all online applications should run. To facilitate debugging during the integration phase, we also allow the SDK to be set to DEBUG mode:

  • ThinkingAnalyticsMode.DEBUG: Data is reported one by one and detailed error logs are printed

  • ThinkingAnalyticsMode.DEBUG_ONLY: Data is reported one by one, only data is verified, not stored

    Note: Do not turn on DEBUG mode in production environments. Specify that only specified devices can turn on Debug mode. Debug mode can only be enabled on devices that have Debug mode enabled on the client side and the device ID configured in the Debug mode Facility Management project information page in the background of the TA. The device ID can be obtained in three ways:

    • #device_id attribute in event data in TA platform
    • Client side log: The device DeviceId will be printed after the SDK initialization is completed
    • Call through instance interface: get device ID

# II. Set User ID

By default, the SDK will use a random UUID as the guest ID for each user, which will be used as the user's identification ID when the user is not logged in. It should be noted that the default guest ID will change when the user reinstates the game and changes the device.

# 2.1 Set Visitor ID (optional)

If you have your own visitor ID management system for each user, you can call identifyto set the visitor ID:

ta.dentify('your_distinct_id');

If you need to get the current guest ID, you can call getDistinctIdto get:

String distinctId = await ta.getDistinctId();

# 2.2 Set and Clear Account ID

When the user logs in, you can call loginto set the user's account ID. After setting the account ID, the account ID will be used as the user identification ID, and the set account ID will be called logout. Keep it until:

// Set Account ID
ta.login('your_account_id');

// Clear Account ID
ta.logout();

Note: This method does not upload user login, user login and other events.

# III. Upload Events

Events and their attributes can be reported by tracking. In general, you may need to upload a dozen to hundreds of different events. If you are using TA background for the first time, we recommend that you upload a few key events first.

# 3.1 Upload Events

It is recommended that you set the properties of the event and the conditions for sending information according to the previously combed doc. The event type is a Stringtype that can only start with a letter and can contain numbers, letters and an underscore "_". It is up to 50 characters in length and is not sensitive to letter case.

ta.track('TEST_EVENT', properties: <String, dynamic>{
  'PROP_INT': 5678,
  'PROP_DOUBLE': 12.3,
  'PROP_DATE': DateTime.now().toUtc(),
  'PROP_LIST': ['apple', 'ball', 1234],
  'PROP_BOOL': false,
  'PROP_STRING': 'flutter test',
});
  • The event attribute is a Map < String, dynamic >type, where each element represents an attribute;
  • The event attribute Keyis the attribute name, which is of Stringtype. It can only start with letters, including numbers, letters and underscore "_", with a maximum length of 50 characters, and is not sensitive to letter case;
  • Property values support five types: String, numeric, bool, DateTime, and Listtypes.

When you call track (), the SDK takes the current system time as the time when the event occurred. If you need to specify the event time, you can pass in the DateTimeparameter dateTimeto set the event trigger time, and pass in the timeZoneto represent the time zone information of the event. The SDK converts the dateTimetimestamp and timeZoneto a string representing the event time.

DateTime dateTime = DateTime.parse('2020-01-01');
ta.track('test', dateTime: dateTime, timeZone: 'UTC');

/*
Examples of raw data:
{
  "#type": "track",
  "#time": "2019-12-31 16:00:00.000",
  "#event_name": "test",
  "#distinct_id": "1ed3465e-17f6-4205-8f86-2e7a2b18027b",
  "properties": {
      "#network_type": "WIFI",
      "#app_version": "1.0",
      "#zone_offset": 0
  },
  "#uuid": "3d74c56f-8b2c-44c4-8683-2dcb3010c231"
}
*/

Note: Although the trigger time can be set for the event, the receiving end will make the following restrictions: only the data from the first 10 days to the last 3 days of the relative server time will be received, and the data exceeding the time limit will be regarded as abnormal data, and the whole data cannot be stored.

# 3.2 Set Public Event Properties

The public event property refers to the property that each event will carry. You can call setSuperPropertiesto set the public event property. We recommend that you set the public event property before sending the event.

Map<String, dynamic> superProperties = {
  'SUPER_STRING': 'super string value',
  'SUPER_INT': 1234,
  'SUPER_DOUBLE': 66.88,
  'SUPER_DATE': DateTime.now(),
  'SUPER_BOOL': true,
  'SUPER_LIST': [1234, 'hello', DateTime.now().toUtc()]
};

ta.setSuperProperties(superProperties);

The public event properties will be saved to the cache and need not be called every time the app is started. If the call to setSuperPropertiesuploads a previously set public event property, the previous property is overwritten. If the public event property and the Keyof a property uploaded by trackduplicate, the property of the event overrides the public event property.

If you need to remove a public event property, you can call unsetSuperPropertyto clear one of the public event properties; if you want to empty all public event properties, you can call clearSuperProperties.

// Clear property name SUPER_ Common properties of LIST
ta.unsetSuperProperty('SUPER_LIST');

// Empty all public properties
ta.clearSuperProperties();

# 3.3 Set Dynamic Public Properties

If the value of the public property is not constant, you can do so by setting the dynamic public property. The dynamic public property is also added to all events, and the actual reported value is dynamically obtained when the event is reported. The dynamic public property currently does not support automatic collection of events.

To set the dynamic public property, you need to pass in a function that returns the type Map < String, dyanmic >. The example is as follows:

// Set dynamic public attributes, dynamic public attributes do not support automatic event collection
ta.setDynamicSuperProperties((){
  return <String, dynamic> {
    'DYNAMIC_DATE': DateTime.now().toUtc(),
    'PROP_INT': 8888
  };
});

Note: If the event property has a duplicate name, the dynamic public property has a higher priority than the public event property and is less than the event property set in track.

# 3.4 Record the Duration of the Event

If you need to record the duration of an event, you can call timeEventto start timing, configure the event type you want to time, and when you upload the event, you will automatically add #durationto your event attribute to indicate the duration of the recording, in seconds.

// Call timeEvent to open for TIME_ Timing of EVENT events
ta.timeEvent('TIME_EVENT');

// do some thing...

// Upload TIME_via trace When an EVENT event occurs, the #duration attribute is added to the attribute
ta.track("TIME_EVENT");

# IV. User Attributes

TA platform currently supports the user feature setting interface for userSet, userSetOnce, userAdd, userUnset, userDelete, userAppend.

# 4.1 UserSet

For general user features, you can call the userSetto set it. Attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the user feature will be created.

ta.userSet(<String, dynamic>{
  'USER_INT': 1,
  'USER_DOUBLE': 50.12,
  'USER_LIST': ['apple', 'ball', 'cat', 1, DateTime.now().toUtc()],
  'USER_BOOL': true,
  'USER_STRING': 'a user value',
  'USER_DATE': DateTime.now(),
});

Similar to event properties:

  • The user feature is a Map < String, dynamic >type, where each element represents an attribute;
  • User feature Keyis the attribute name, which is of Stringtype. It can only start with letters, including numbers, letters and underscore "_". The maximum length is 50 characters and is not sensitive to letter case.
  • User feature values support four types: String, numeric class, bool, DateTime, and List.

# 4.2 UserSetOnce

If the user feature you want to upload only needs to be set once, you can call userSetOnceto set it. When the attribute already has a value before, this information will be ignored:

ta.userSetOnce(<String, dynamic>{
  'USER_INT': 2,
  'USER_DOUBLE': 10.12,
});

Note: The user feature type and restrictions set by userSetOnce are consistent with userSet.

# 4.3 UserAdd

When you want to upload a numeric attribute, you can call userAddto accumulate the attribute. If the attribute has not been set, it will be assigned a value of 0and then evaluated. Negative values can be passed in, which is equivalent to subtraction operations.

ta.userAdd(<String, num>{
  'USER_INT': 2,
  'USER_DOUBLE': 10.1,
});

Note: The restrictions on attribute types and key values in userAdd are consistent with userSet, but Value only allows numeric type attributes to be reported.

# 4.4 UserUnset

If you need to reset a property of a user, you can call userUnsetto remove the value of the user feature specified by the user:

ta.userUnset('USER_INT');

# 4.5 UserDelete

If you want to delete a user, you can call userDeleteto delete the user. You will no longer be able to query the user feature of the user, but the events generated by the user can still be queried:

ta.userDelete();

# 4.6 UserAppend

You can call userAppendto append elements to a user feature of type List:

ta.userAppend(<String, List>{
  'USER_LIST': [DateTime.now()],
});

# V. Automatic Acquisition Events

You can call enableAutoTrackand pass in a Listof type.

ThinkingAnalyticsAutoTrackTypeto turn on automatic collection. Currently four types are supported:

  • ta_app_start: The application enters the foreground, the corresponding type is ThinkingAnalyticsAutoTrackType.APP_START
  • ta_app_end: The application enters the background, the corresponding type is ThinkingAnalyticsAutoTrackType.APP_END
  • ta_app_install: Open the application for the first time after installation, the corresponding type is ThinkingAnalyticsAutoTrackType. APP_INSTALL
  • ta_app_crash: An uncaught exception causes the application to crash, the corresponding type is ThinkingAnalyticsAutoTrackType.APP_CRASH

Regarding automatic collection events, we need to pay attention to:

  1. AutoCollect events are implemented in the native SDK, so dynamic public properties cannot be added to AutoCollect events at this time.
  2. If you need to set a guest ID, or a public property, please complete the setting before turning on the automatic collection event.

Start automatic collection example:

ta.enableAutoTrack([
  ThinkingAnalyticsAutoTrackType.APP_START,
  ThinkingAnalyticsAutoTrackType.APP_END,
  ThinkingAnalyticsAutoTrackType.APP_INSTALL,
  ThinkingAnalyticsAutoTrackType.APP_CRASH,
]);

# VI. Other interfaces

# 6.1 Get the Device ID

After the SDK is initialized, the device ID will be automatically generated and recorded in the local cache. For the same application/game, the device ID of a device is unchanged. You can call getDeviceIdto obtain the device ID:

String deviceId = await ta.getDeviceId();

// Use Device ID as Visitor ID
// ta.identify(deviceId);

# 6.2 Pause/stop data reporting

There are two types of interfaces that stop SDK reporting:

# 6.2.1 Pause SDK Reporting (enableTracking)

You may want to temporarily stop SDK data collection and reporting in some scenarios, such as the user is in a test environment, or the user logged in to a test account. At this time, you can call the following interfaces to temporarily stop SDK reporting.

You can call enableTrackingthrough an instance (including the main instance and the light instance), pass in falseto suspend the reporting of the SDK. The #distinct_id, #account_id, public attributes that have been set by the instance will be retained; the data that has been collected but has not been successfully reported by the instance will continue to try to report; the subsequent instance cannot collect and report any new data, cannot set visitor ID, account ID, and public attributes, etc., but can read that the instance has been set The public attributes and device ID, guest ID, account ID and other information.

The stop state of the instance will be saved in the local cache until enableTrackingis called and trueis passed in. The SDK instance will resume data collection and reporting. It should be noted that the light instance is not cached, so every time you open the APP, The paused state of the light instance will not be retained, and the reporting will be reopened.

// Pause instance reporting, cached data and set information are not cleared
ta.enableTracking(false);

// Report of recovery instances
ta.enableTracking(true);

# 6.2.2 Stop SDK Reporting (optOutTracking)

In some special situations, you may need to completely stop the functions of the SDK. For example, in areas where GDPR is applicable, users choose not to provide data collection permissions, you can call the following interface to completely turn off the functions of the SDK.

OptOutTrackingcan only be called through the main instance, and the biggest difference with enableTrackingis that it will empty the local cache of this instance, including the guest ID, account ID, public attributes, and unreported data queues of this instance. Then turn off the collection and reporting functions of this instance.

// Stop reporting instances and clear local caches
ta.optOutTracking();

If you want to delete the user's user data in the TA cluster while turning off the SDK function, you can pass in the deleteUserparameter, which will report a userDeletedata to delete the user's user data before stopping the function of the SDK instance.

// Stop reporting instances and send user_ Del
ta.optOutTracking(deleteUser: true);

The stopped state of the instance will also be saved in the local cache until the optInTrackingis called, and subsequent reports can continue, but this is equivalent to a completely new instance

//Re-start reporting
ta.optInTracking();

# 6.3 Creating Light Instances

You can create multiple instances under the same APP ID by light instances

// Create a light example
ThinkingAnalyticsAPI light = await ta.createLightInstance();

// Setting Visitor ID for Light Instance
light.identify('light_d_id');

// Report Events via Light Example
light.track('TEST_EVENT_FROM_LIGHT');

Note: The APP ID, reporting address and some settings of the child lightweight instance are consistent with the parent instance, but other information is not shared

# 6.4 Time Calibration

The SDK will use the native time as the event occurrence time by default. If the user manually modifies the device time, it will affect your business analysis. Since version v1.1.0, you can use the current timestamp obtained from the server level to calibrate the SDK time. After that, all calls that do not specify a time, including event data and user feature setting operations, will use the calibrated time as the time of occurrence.

// 1585633785954 is the current UNIX time stamp in milliseconds corresponding to Beijing Time 2020-03-31 13:49:45
ThinkingAnalyticsAPI.calibrateTime(1585633785954);

We also provide the ability to get time to SDK calibration from NTP. You need to pass in the NTP server address that your users can access. The SDK then attempts to obtain the current time from the incoming NTP service address and calibrate the SDK time. If the correct return result is not obtained within the default timeout time (3 seconds), the data will be reported using the local time later.

// Time Calibration Using Apple NTP Service
ThinkingAnalyticsAPI.calibrateTimeWithNtp("time.apple.com");

Note:

  • You need to choose your NTP server address carefully to ensure that the user equipment can get the server time quickly when the network is in good condition.
  • There is some uncertainty in using the NTP service for time calibration. It is recommended that you give priority to using timestamp calibration.

# VII. Relevant Preset Attributes

# 7.1 Get Preset Attributes

V2.0.1 and later can call the getPresetProperties ()method to obtain preset properties.

When server level event tracking requires some preset properties of the App side, you can obtain the preset properties of the App side through this method and then pass them to the server level.

//Get Attribute Object
TDPresetProperties presetProperties = await _ta.getPresetProperties();

//Generate event preset properties
Map<String, dynamic>? eventPresetProperties = presetProperties.toEventPresetProperties();
/*
   {
  "#carrier": "China Telecom",
  "#os": "iOS",
  "#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
  "#screen_height": 2264,
  "#bundle_id": "com.sw.thinkingdatademo",
  "#manufacturer": "Apple",
  "#device_model": "iPhone7",
  "#screen_width": 1080,
  "#system_language": "zh",
  "#os_version": "10",
  "#network_type": "WIFI",
  "#zone_offset": 8
    }
*/

//
Get a preset property
String bundleId = presetProperties.bundleId;//name
String os = presetProperties.os;//os tyle ,as Android、iOS
String systemLanguage = presetProperties.systemLanguage;//Cell phone system language type
int screenWidth = presetProperties.screenWidth;//Screen width
int screenHeight = presetProperties.screenHeight;//Screen height
String deviceModel = presetProperties.deviceModel;//Divice Model
String deviceId = presetProperties.deviceId;//Unique Identification of device
String carrier = presetProperties.carrier;//Mobile SIM Card Operator Information, Dual Card Dual Standby, Master Card Operator Information
String manufacture = presetProperties.manufacturer;//Mobile phone manufacturers such as Huawei and Apple
String networkType = presetProperties.networkType;//Network Type
String osVersion = presetProperties.osVersion;//System Version Number
double zoneOffset = presetProperties.zoneOffset;//Time zone offset value

IP, country and city information is generated by server level resolution, and the client side does not provide an interface to obtain these attributes

# Advanced Functions

Starting with v1.3.0, the Flutter SDK supports the reporting of three special types of events: first-time events, updatable events, and rewritable events. These three events need to be used in conjunction with TA system 2.8 and later versions. Since special events are only applicable in certain specific scenarios, please use special events to report data with the help of Count Technology's customer success and analysts.

# 8.1 First Incident

First-time events are events that are recorded only once for a device or another dimension ID. For example, in some scenarios, you may want to record the first event on a device, you can use first-time events to report data.

// Instance: Report device first event, assuming event name is DEVICE_ FIRST
var properties = {
  'PROP_INT': 5678,
  'PROP_DOUBLE': 12.3,
  'PROP_DATE': DateTime.now().toUtc(),
  'PROP_LIST': ['apple', 'ball', 1234],
  'PROP_BOOL': false,
  'PROP_STRING': 'flutter test',
};
var firstModel = TrackFirstEventModel('DEVICE_FIRST', '', properties);
_ta.trackEventModel(firstModel);

If you want to determine whether it is the first time in a dimension other than the device, you can set FIRST_CHECK_ID for the first event. For example, if you need to record the first event of an account, you can set the account ID to the FIRST_CHECK_ID of the first event:

// Instance: First event to report a user account, assuming the event name is USER_ FIRST
var properties = {
  'PROP_INT': 5678,
  'PROP_DOUBLE': 12.3,
  'PROP_DATE': DateTime.now().toUtc(),
  'PROP_LIST': ['apple', 'ball', 1234],
  'PROP_BOOL': false,
  'PROP_STRING': 'flutter test',
};
var firstModel = TrackFirstEventModel('USER_FIRST', 'YOU_ACCOUNT_ID', properties);
_ta.trackEventModel(firstModel);

Note: Due to the completion of the verification of whether it is the first time at the server level, the first event will be delayed by 1 hour by default.

# 8.2 Updatable Events

You can implement the requirement to modify event data in a specific scenario through updatable events. Updatable events need to specify an ID that identifies the event and pass it in when the updatable event object is created. The TA background will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be updated, assuming the event name is UPDATABLE_ EVENT
var properties = {
  'status': 3,
  'price': 100
};
var updateModel = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties);

// Event attributes after reporting are status 3 and price 100
_ta.trackEventModel(updateModel);


var properties_new = {
  'status': 5
};
var updateModel_new = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', properties_new);

// Event attributes status is updated to 5 after reporting, price remains unchanged
_ta.trackEventModel(updateModel_new);

Updatable events will update the event time of historical data by default using the current time of the device. If you want to specify the event time, you can specify the event time when reporting the updatable event:

var updateModel = TrackUpdateEventModel('UPDATABLE_EVENT', 'test_event_id', {});
// Specify event time for updatable events
updateModel.dateTime = DateTime.now().toUtc();
updateModel.timeZone = 'UTC';
_ta.trackEventModel(updateModel);

# 8.3 Rewritable Events

Rewritable events are similar to updatable events, except that rewritable events will completely cover historical data with the latest data, which is equivalent to deleting the previous data and storing the latest data in effect. The TA background will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be overridden, assuming the event name is OVERWRITABLE_ EVENT

var properties = {
    'status': 3,
    'price': 100
};
var overwriteModel = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties);
// Event attributes after reporting are status 3 and price 100
_ta.trackEventModel(overwriteModel);


var properties_new = {
    'status': 5
};
var overwriteModel_new = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', properties_new);
// Event attribute status is 5 after reporting and price attribute is deleted
_ta.trackEventModel(overwriteModel_new);

Rewritable events will overwrite the event time of historical data by default using the current time of the device. If you want to specify the event time, you can specify the event time when reporting the rewritable event:

var overwriteModel = TrackOverwriteEventModel('OVERWRITABLE_EVENT', 'test_event_id', {});
// Specifies the event time for a rewritable event
overwriteModel.dateTime = DateTime.now().toUtc();
overwriteModel.timeZone = 'UTC';
_ta.trackEventModel(overwriteModel);

# Release Note

# v2.0.1 2021/06/28

  • Support preset attribute acquisition

# v2.0.0 2021/05/17

  • Adapted to Flutter2.0

# v1.3.3 2020/10/29

  • Adapt iOS 5G network
  • Optimize install, start event reporting logic
  • Optimized data transfer format
  • Default network reporting policy adjusted to 2G/3G/4G/5G/WIFI

# v1.3.2 2020/08/25

  • Fix the problem that the special event does not set timeZone, which causes the wrong #zone_offset to be reported.

# v1.3.0 2020/08/24

  • Supports first-time events, allowing custom ID checks to be passed in to verify whether it is reported for the first time
  • Supports updatable, rewritable events

# v1.2.1 2020/06/28

  • Optimized code: avoid null pointer exceptions in extreme cases

# v1.2.0 2020/06/23

  • Optimize Debug mode and cooperate with background event tracking management
  • Support #system_language attribute

# v1.1.1 2020/04/14

  • Fix the bug of event upload in DEBUG mode on Android platform

# v1.1.0 2020/04/03

  • Support calibration of SDK time using server time

# v1.0.0 2020/03/10

  • Support event and user feature data reporting
  • Support for multiple and light instances
  • Support public event properties and dynamic public properties
  • Support automatic event collection
  • Support Debug mode
  • Support setting default time zone