基础 API 介绍（Flutter）

    SensorsAnalyticsFlutterPlugin.init(
        serverUrl: "<神策数据接收地址>",
        // 可选，全埋点配置，按需开启
        autoTrackTypes: <SAAutoTrackType>{
          SAAutoTrackType.APP_START,
          SAAutoTrackType.APP_VIEW_SCREEN,
          SAAutoTrackType.APP_CLICK,
          SAAutoTrackType.APP_END
        },
        // 默认关闭，是否开启调试日志，上线请关闭
        enableLog: true
      );

       harmony: HarmonyConfig(
            publicKey:  <RSA 公钥 key>,
            pkv: <RSA 秘钥版本号> )

SensorsAnalyticsFlutterPlugin.profileSetOnce({'AdSource':'XXX Store'});

// 再次设定用户渠道，设定无效，"developer@sensorsdata.cn" 的 "AdSource" 属性值仍然是 "XXX Store"
SensorsAnalyticsFlutterPlugin.profileSetOnce({'AdSource':'developer@sensorsdata.cn'});

// 将用户游戏次数属性增加一次 
SensorsAnalyticsFlutterPlugin.profileIncrement("GamePlayed", 1);

SensorsAnalyticsFlutterPlugin.profileAppend('address',['Beijing','Shanghai']);

SensorsAnalyticsFlutterPlugin.profileUnset("age");

埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

代码埋点追踪事件

SDK 初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。

SensorsAnalyticsFlutterPlugin.track('eventname',{'ProductID':'123456','ProductCatalog':'Laptop Computer'});

事件名和事件属性的格式规范，请参考数据格式。

埋点事件采集时长属性

可以通过计时器统计事件的持续时间。首先，在事件开始时调用 trackTimerStart("Event")，该方法并不会真正发送事件；在事件结束时，调用 trackTimerEnd("Event", properties)，SDK 会触发 "Event" 事件，并自动将事件持续时间记录在事件属性 "$event_duration" 中。例如记录用户浏览商品页面的时间：

// 进入商品页面
// 调用 trackTimerStart("ViewProduct") 标记事件启动时间 
SensorsAnalyticsFlutterPlugin.trackTimerStart("ViewProduct");

// ... 用户浏览商品

// 离开商品页
SensorsAnalyticsFlutterPlugin.trackTimerEnd('ViewProduct',{"product_id":PRODUCT_ID});

多次调用 trackTimerStart("Event") 时，事件 "Event" 的开始时间以最后一次调用时为准。注意务必确保 trackTimerStart 和 trackTimerEnd 接口配对使用，多次调用 trackTimerEnd 会触发无时长的埋点事件。

统计事件时长支持暂停和恢复，通过调用 trackTimerPause(String eventName) 和 trackTimerResume(String eventName) 来分别实现暂停和恢复。如果需要清空已记录的时长事件则调用 clearTrackTimer() 接口。

物品元数据上报

设置物品属性

直接设置一个物品，如果已存在则覆盖。除物品 ID 与物品所属类型外，其他物品属性需在 properties 中定义。物品属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 数据格式。

// 为物品类型为 itemType 且物品 ID 为 itemId 的物品，设置物品属性 properties
SensorsAnalyticsFlutterPlugin.itemSet(String itemType, String itemId, [Map<String, dynamic>? properties]);

删除物品属性

如果物品不可被推荐需要下线，删除该物品即可，如不存在则忽略。除物品 ID 与物品所属类型外，不解析其他物品属性。

// 删除物品，类型为 itemType，ID 为 itemId
SensorsAnalyticsFlutterPlugin.itemDelete(String itemType, String itemId);

事件属性

在进行埋点事件追踪时，您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性。当同一事件中出现相同 Key 的属性时，SDK 覆盖优先级：预置属性 < 静态公共属性 < 动态公共属性 < 自定义属性。

获取预置属性

可以调用 getPresetProperties() 方法获取预置属性。服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

//获取预置属性 
SensorsAnalyticsFlutterPlugin.getPresetProperties();

静态公共属性

静态公共属性是指对于所有事件都需要添加的属性，初始化 SDK 后，可以通过 registerSuperProperties() 将属性注册为公共属性。设置方法如下：

// 将应用名称作为事件公共属性，后续所有 track 类型的事件都会自动带上 "AppName" 属性 
SensorsAnalyticsFlutterPlugin.registerSuperProperties({"AppName":"FlutterDemo"});

注册的静态公共属性可以通过 unregisterSuperProperty(String key) 方法删除指定 key 的静态公共属性，也可以通过 clearSuperProperties() 删除所有注册的公共属性。

数据存储与发送

需要更精细地控制神策分析可以通过以下选项设置数据采集功能。

数据采集

在每次调用 track()、login()、profileSet() 等方法时，神策分析 SDK 会将埋点事件保存在数据库中，并会检查如下条件，以判断是否向服务器上传数据：

1. 是否是 WIFI/2G/3G/4G/5G 网络条件
2. 是否满足发送条件之一：
   1. 与上次发送的时间间隔是否大于 flushInterval
   2. 本地缓存日志数目是否大于 flushBulkSize
   3. 事件类型为 login() 方法触发的 $SignUp 事件

默认的 flushBulkSize 为 100 条，默认的 flushInterval 为 15 秒。满足条件后，神策分析 SDK 会将数据 gzip 压缩后，批量发送到神策分析。

如果追求数据采集的时效性，可以调用 flush() 方法，强制将数据发送到神策分析，例如：

// 记录用户登录事件 
SensorsAnalyticsFlutterPlugin.track("UserLogin");

// 强制发送数据 
SensorsAnalyticsFlutterPlugin.flush();

在 App 进入后台状态时，SDK 会调用 flush() 方法，将缓存的数据发送到神策分析。

设置发送数据的网络策略（HarmonyOS 不支持）

默认情况下，在 2G/3G/4G/5G/WIFI 网络条件下，SDK 都会尝试去同步数据。v1.7.2 及以后的版本支持可以自定义同步数据的网络策略。通过设置 SANetworkType 在初始化时来指定发送数据的网络策略。例如：

//SANetworkType  为支持的网络类型枚举
    SensorsAnalyticsFlutterPlugin.init(
        serverUrl: "xxx",
        networkTypes: <SANetworkType>{
          SANetworkType.TYPE_2G,
          SANetworkType.TYPE_3G,
          SANetworkType.TYPE_4G,
          SANetworkType.TYPE_WIFI,
          SANetworkType.TYPE_5G
        },
...

设置本地缓存上限值

SDK 本地数据库默认缓存数据的上限值根据不同的平台具体值不一样，具体需要在 SensorsAnalyticsFlutterPlugin.init() 方法中配置，如下：