Flutter SDK 插件

Flutter SDK 插件时集成后，即可以使用SDK的埋点功能，若是需要无埋点功能，需要在集成插件后再做额外的页面配置才能使其生效。

info

Flutter SDK 插件的更新日志，可参阅 Release Notes
Flutter SDK 无埋点如何生效，请阅读 Flutter 无埋点

Growingio Flutter SDK 插件集成

添加依赖

在 Flutter 项目的pubspec.yaml文件中 dependencies 里面添加 growingio_flutter_plugin 依赖。

dependencies:
  growingio_flutter_plugin: '^4.4.0'

然后执行 flutter pub get 指令安装插件。

info

Flutter SDK 插件已通过 pub / SPM 或 CocoaPods / ohpm 自动集成 Android / iOS / HarmonyOS 原生 SDK，无需在原生工程中重复添加 GrowingIO 原生 SDK 依赖。如需指定原生 SDK 版本，请参考下方版本依赖关系表。

注意：Android 平台若需开启原生无埋点能力，仍需在 Android 工程中配置 GrowingIO Gradle 插件，详见下方《Flutter 插件初始化》小节。

点击查看 GrowingIO Flutter 插件和内置原生 SDK 版本对应关系

Flutter 插件版本	Android SDK 版本	iOS SDK 版本	HarmonyOS SDK 版本
v4.0.0	4.3.0	4.3.0	—
v4.1.0	4.3.0	4.3.2	—
v4.2.0	4.3.0	4.3.2	2.0.x
v4.3.0	4.4.0	4.3.2	2.0.x
v4.3.1	4.4.2	4.6.x	2.0.x
v4.3.2	4.4.3	4.6.x	2.0.x
v4.3.3	4.4.3	4.6.x	2.4.x
v4.3.4	4.5.2	4.10.x	2.4.x
v4.3.5	4.5.3	4.11.x	2.7.x
v4.3.6	4.5.3	4.11.x	2.7.x
v4.4.0	4.5.3	4.12.x	2.7.x

Android SDK 由 Gradle BOM 锁定为单一版本；iOS / HarmonyOS SDK 受 SPM 版本区间、CocoaPods ~> 与 ohpm ~/^ 约束，会在同一 minor 版本内自动取最新补丁版本。

iOS 集成方式说明

从 v4.4.0 起，插件同时支持 Swift Package Manager（SPM）与 CocoaPods 两种 iOS 原生依赖管理方式。

Flutter 3.44 及以上（默认 SPM 模式）

添加依赖后无需任何额外操作，构建时 Flutter 会自动通过 SPM 引入插件及原生 GrowingAnalytics SDK（要求原生 SDK ≥ 4.12.0）。旧工程首次构建时 Flutter 会自动完成 SPM 集成迁移。

caution

如果 Podfile 中曾手动添加过 pod 'GrowingAnalytics/...'，SPM 模式下必须删除这些行，否则 SDK 会被集成两份，链接时报 duplicate symbols。

Flutter 3.44 以下，或手动禁用了 SPM

继续通过 CocoaPods 集成，行为与旧版本完全一致，同样无需额外操作。禁用 SPM 的方式：

# pubspec.yaml
flutter:
  config:
    enable-swift-package-manager: false

原生 + Flutter 混合开发

CocoaPods 模式下原生代码可直接 import GrowingAutotracker；SPM 模式下插件的依赖对 app target 默认不可见，若原生代码需要直接调用 SDK API，请在 Xcode 中 File → Add Package Dependencies… → 输入 https://github.com/growingio/growingio-sdk-ios-autotracker.git（版本 4.12.0 起）→ 勾选 GrowingAutotracker 产品添加到 app target。SPM 会自动与插件已依赖的同一个包去重，不会产生重复代码。

Flutter 插件初始化

GrowingIO Flutter SDK 需要在 Flutter 端初始化 SDK。

原生+Flutter

若您的 Flutter 应用是混编应用，在进入 Flutter 页面之前已经在原生进行了原生 SDK 的初始化，您还应当在 Flutter 端再进行一次 Flutter SDK 的初始化，以使得插件桥接生效。
注意：原生端或 Flutter 端，以先初始化的配置项为主。
如果是 Android 平台且需要无埋点功能支持，还应当在 Android 配置中添加 GrowingIO Gradle 插件才能使原生无埋点生效。

Flutter 初始化

在 Flutter 端进行初始化，推荐将 SDK 的初始化代码放入 main.dart 的 main 中，代码示例如下：

void main() async {
  /// 代码中的 <ProjectId>、<DataSourceId>、<UrlScheme>请自行替换为自己项目的对应值。
  var option = AutotrackerConfiguration("<ProjectId>", "<DataSourceId>", "<UrlScheme>");
  option.dataCollectServerHost = "https://napi.growingio.com";
  option.debugEnabled = false;
  option.dataCollectionEnable = true;
  option.androidConfig = AndroidConfiguration(
      channel: "应用宝", androidIdEnabled: true, imeiEnabled: false, requireAppProcessesEnabled: false);
  
  /// 添加相应的模块
  option.addGioComponent(EncoderLibraryGioModule());

  /// 设置完配置后，调用该接口进行初始化
  GrowingAutotracker.startWithConfiguration(option);


  runApp(MyApp());
}

Flutter On HarmonyOS 配置上下文

如果您的 Flutter 应用需要在 HarmonyOS 平台运行，您还需要在项目中 FlutterAbility 子类的 configureFlutterEngine(flutterEngine: FlutterEngine) 方法中配置 HarmonyOS 插件上下文：

首先，定义一个包含上下文的插件类型 AsGrowingAnalytics：

interface AsGrowingAnalytics extends FlutterPlugin {
  context: Context
}

其次，配置 HarmonyOS 插件上下文，注意配置代码需要在 GeneratedPluginRegistrant.registerWith(flutterEngine) 之后：

configureFlutterEngine(flutterEngine: FlutterEngine) {
  super.configureFlutterEngine(flutterEngine)
  GeneratedPluginRegistrant.registerWith(flutterEngine)

  // 配置 HarmonyOS 插件上下文
  let plugins = flutterEngine.getPlugins()
  if (plugins && plugins.has('FlutterGrowingAutotrackerPlugin')) {
    let analytics = plugins.get('FlutterGrowingAutotrackerPlugin') as AsGrowingAnalytics
    analytics.context = this.context
  }
}

初始化配置说明

在 Flutter 初始化中会传入各式的参数，AutotrackerConfiguration 参数配置如下表所示：

配置项	参数类型	是否必填	默认值	说明	版本
projectId	String	是	null	项目ID，每个应用对应唯一值	-
dataSourceId	String	是	null	应用的DataSourceId，唯一值	-
urlScheme	String	是	null	应用特有的URLScheme，用于外部应用拉起应用，如圈选	-
dataCollectionServerHost	String	否	null	服务端部署后的 ServerHost	-
debugEnabled	bool	否	false	调试模式，会打印SDK log，抛出错误异常，在线上环境请关闭	-
cellularDataLimit	int	否	10	每天发送数据的流量限制，单位MB	-
dataUploadInterval	int	否	15	数据发送的间隔，单位秒	-
sessionInterval	int	否	30	会话后台留存时长，单位秒	-
dataCollectionEnabled	bool	否	true	是否采集数据	-
requestTimeout	int	否	30	设置数据上报请求的超时时间，单位秒	-
dataValidityPeriod	int	否	7	设置为上报数据在数据库的缓存时间，单位天	-
idMappingEnabled	bool	否	false	是否开启多用户身份上报	-
autotrackAllRoutePage	bool	否	true	设置是否发送 Route 页面上的Page事件	-
autotrackEnabled	bool	否	true	设置原生端是否打开无埋点功能	-
autotrackAllNativePage	bool	否	false	设置原生端是否自动发送Page事件	-
modules	`Set<LibraryGioModule>`	否	empty	模块集成，具体请阅读下方的模块说明	-
androidConfig	`AndroidConfiguration`	否	null	用于配置Android设备上特有的一些属性	-
iosConfig	`IosConfiguration`	否	null	用于配置iOS设备上特有的一些属性	-

AndroidConfiguration 参数特有配置如下表所示

配置项	参数类型	是否必填	默认值	说明	版本
channel	String	否	null	Android 应用的分发渠道	-
androidIdEnabled	bool	否	false	是否允许在 Android 设备上采集 AndroidId	-
imeiEnabled	bool	否	false	是否允许在 Android 设备上采集 imei	-
requireAppProcessesEnabled	bool	否	false	是否允许在 Android 设备上获取应用进程名称	-

IosConfiguration 目前暂无特有配置。

urlScheme 配置说明

在使用 GrowingIO SDK 的 Mobile Debugger 和圈选功能时，用于外部浏览器通过扫描二维码来拉起应用。

模块配置

GrowingIO SDK 利用模块来实现SDK核心功能以外的额外功能，在 Flutter SDK 插件中，可以通过在 modules 传入模块声明来开启相应的功能。

目前 Flutter SDK 可启用的模块功能包括：

广告功能

  option.addGioComponent(AdsLibraryGioModule(
      config: AdsConfig(
          readClipBoardEnable: true,
          asaEnabled: true,
          deepLinkHost: "https://ads-uat.growingio.cn",
          deepLinkCallback: (Map params, int error, int time) {
            print("deeplink params: $params");
          })));

广告模块包括激活事件和深度链接，能帮助客户提供广告，活动的引导跳转和下载。

iOS 端需额外引入原生广告库，按集成模式二选一：

SPM 模式：Xcode 打开 iOS 工程 → File → Add Package Dependencies… → 输入 https://github.com/growingio/growingio-sdk-ios-autotracker.git（版本 4.12.0 起）→ 产品列表中勾选 GrowingModule_Ads 添加到 app target（SPM 会自动与插件已依赖的同一个包去重）
CocoaPods 模式：Podfile 中添加 pod 'GrowingAnalytics/Ads'

未引入广告库时调用 doDeepLinkByUrl 会静默降级并在控制台提示“广告模块未集成”，不会崩溃。

info

什么是广告模块，请参考原生端说明：

加密模块

option.addGioComponent(EncoderLibraryGioModule());

加密模块用于数据网络上传数据的加密。

Json 模块

option.addGioComponent(JsonLibraryModule());

Json 数据模块将会使用 Json 格式保存和上传事件数据。

API说明

GrowingAutotracker.getContext().setDataCollectionEnabled(true)
GrowingAutotracker.getContext().setLoginUserId(userId: "cpacm",userKey: "name")
GrowingAutotracker.getContext().cleanLoginUserId()
GrowingAutotracker.getContext().setLoginUserAttributes(attributes: {"sex":"female"});
GrowingAutotracker.getContext().setLocation(latitude: 20.11,longitude: 20.11)
GrowingAutotracker.getContext().cleanLocation()
GrowingAutotracker.getContext().getDeviceId()
GrowingAutotracker.getContext().trackCustomEvent(eventName: "eventName", attributes: {"age":"18"})
String? timerId =await GrowingAutotracker.getContext().trackTimerStart(eventName: "custom");
GrowingAutotracker.getContext().trackTimerPause(timerId: timerId!);
GrowingAutotracker.getContext().trackTimerResume(timerId: timerId);
GrowingAutotracker.getContext().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.getContext().removeTimer(timerId: timerId);
GrowingAutotracker.getContext().clearTrackTimer();
GrowingAutotracker.getContext().setGeneralProps(props:{});
GrowingAutotracker.getContext().removeGeneralProps(keys:["col1 row1", "key1"]);
GrowingAutotracker.getContext().clearGeneralProps();
GrowingAutotracker.getContext().flushEvents();

GrowingAutotracker.getContext().registerComponent(module);

1. 数据采集开关

setDataCollectionEnabled
打开或关闭数据采集

参数说明

参数	参数类型	说明
`enabled`	`boolean`	`true`打开数据采集，`false`关闭数据采集，默认 `true`

示例

GrowingAutotracker.getContext().setDataCollectionEnabled(true);

2. 设置登录用户ID

setLoginUserId
当用户登录之后调用，设置登录用户ID

info

如果您的App每次用户升级版本时无需重新登录的话，为防止用户本地缓存被清除导致的无法被识别为登录用户，建议在用户每次升级App版本后初次访问时重新调用setLoginUserId方法
当需要标记用户ID类型时，请先进行规划，并在平台的数据中心，添加新的用户身份类型，再设置userkey，误设会影响数据质量。 同时在初始化 SDK 时设置idMappingEnabled为true

参数说明

参数	参数类型	说明
`userId`	`String`	长度限制大于0且小于等于1000，如果大于长度1000将只截取前1000长度
`userKey`	`String`	适用于ID-MAPPING,可设置 `userId` 的类型,可选填

示例

GrowingAutotracker.getContext().setLoginUserId(userId: "cpacm",userKey: "name");

3. 清除登录用户ID

cleanLoginUserId
当用户登出之后调用，清除已经设置的登录用户ID。

示例

GrowingAutotracker.getContext().cleanLoginUserId();

4. 设置用户的地理位置

setLocation
设置用户当前的地理位置，基于WGS-84坐标

参数说明

参数	参数类型	说明
`latitude`	`double`	地理坐标点纬度
`longitude`	`double`	地理坐标点经度

示例

GrowingAutotracker.getContext().setLocation(latitude: 20.11,longitude: 20.11);

5. 清除用户的地理位置

cleanLocation
清除用户当前的地理位置

示例

GrowingAutotracker.getContext().cleanLocation();

6. 设置登录用户属性

setLoginUserAttributes
发送登录用户属性事件，用于用户信息相关分析；在添加发送用户属性事件代码之前，需在CDP平台用户管理界面创建用户属性。

参数说明

参数	参数类型	说明
`attributes`	`Map<String, String>`	用户属性信息

示例

GrowingAutotracker.getContext().setLoginUserAttributes(attributes: {"sex":"female"});

7. 设置埋点事件

trackCustomEvent
发送一个埋点事件；注意：在添加发送的埋点事件代码之前，需在CDP平台事件管理界面创建埋点事件以及关联事件属性；
如果事件属性需关联维度表，请在事件属性下关联维度表（ CDP平台版本>= 2.1 ）

参数说明

参数	参数类型	说明
`eventName`	`String`	事件名，事件标识符
`attributes`	`Map<String, String>`	事件发生时所伴随的属性信息；当事件属性关联有维度表时，属性值为对应的维度表模型ID(记录ID)（可选）

示例

GrowingAutotracker.getContext().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});

8. 获取设备ID

getDeviceId
获取设备ID，又称为匿名用户ID，SDK 自动生成用来定义唯一设备。如果没有初始化SDK 或者关闭采集开关可能返回值为null，且可能有IO操作。

示例

GrowingAutotracker.getContext().getDeviceId();

9. 事件化计时器

trackTimerStart
初始化一个事件计时器，参数为计时事件的事件名称，返回值为该事件计时器唯一标识

trackTimerPause
暂停事件计时器，参数为trackTimerStart返回的唯一标识

trackTimerResume
恢复事件计时器，参数为trackTimerStart返回的唯一标识

trackTimerEnd
停止事件计时器，参数为trackTimerStart返回的唯一标识。调用该接口会自动触发删除定时器。

removeTimer
删除事件计时器，参数为 trackTimerStart 返回的唯一标识。
该接口会将标识为 timerId 的计时器置为空。调用停止计时器接口，会自动触发该接口。注意移除时不论计时器处于什么状态，都不会发送事件。

clearTrackTimer
清除所有已经注册的事件计时器。
存在所有计时器需要清除时调用。注意移除时不论计时器处于什么状态，都不会发送事件。

参数说明

参数	参数类型	说明
`eventName`	`String`	事件名称，事件标识符
`attributes`	`Map<String, String>`	事件发生时所伴随的属性信息

返回值说明

参数	参数类型	说明
`timerId`	`String`	计时器唯一标识

示例

String? timerId =await GrowingAutotracker.getContext().trackTimerStart(eventName: "custom");
GrowingAutotracker.getContext().trackTimerPause(timerId: timerId!);
GrowingAutotracker.getContext().trackTimerResume(timerId: timerId);
GrowingAutotracker.getContext().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.getContext().removeTimer(timerId: timerId);
GrowingAutotracker.getContext().clearTrackTimer();

10. 通用属性

setGeneralProps({required Map<String, dynamic> props})
为所有的自定义事件（CustomEvent）添加通用属性。

removeGeneralProps({required List<String> keys})
根据Key值移除已经设置的属性，如不存在则不影响。

clearGeneralProps()
清除所有已经设置的通用属性。

GrowingAutotracker.getContext().setGeneralProps(props:{"key1":"name"});
GrowingAutotracker.getContext().removeGeneralProps(keys:["xxx", "key1"]);
GrowingAutotracker.getContext().clearGeneralProps();

11. 事件 flush 上报

flushEvents
在每次调用 trackCustomEvent()、setLoginUserId() 等方法时，SDK 都会先将埋点事件保存在数据库中，并默认在15秒时间内判断是否向服务器上传数据：

如果追求数据采集的时效性，可以调用 flushEvents() 方法，强制将数据发送到服务端.

示例

GrowingAutotracker.getContext().flushEvents();

12. 注册模块组件

registerComponent
可通过该方法手动注册SDK需要的可配置模块组件（推荐在初始化通过 Configuration 初始化时注册）。

参数说明

参数	参数类型	说明
`module`	`LibraryGioModule`	模块
`config`	`Configuration`	模块的配置类(可选参数)

示例

GrowingAutotracker.getContext().registerComponent(JsonLibraryModule());

13. 无埋点页面事件

在配置了 Flutter 无埋点既可以通过路由监听器和替换Route类自动实现，也可以通过 mixin 类 GrowingPageStateMixin 或者 GrowingPageStatelessMixin 来使用代码实现。

在 StatefulWidget 中，可以将其 State 声明为 Page页面，如下：

class _HomeScreenState extends State<HomeScreen> with GrowingPageStateMixin {
  @override
  String get alias => "HomeScreen";

  @override
  Map<String, dynamic>? get attributes => {};
}

在 StatelessWidget 中，直接将自己声明为 Page 页面，如下：

class SplashScreen extends StatelessWidget with GrowingPageStatelessMixin {
  @override
  String get alias => "SplashScreen";

  @override
  Map<String, dynamic>? get attributes => {};
}

alias 对应页面的名称，attributes为页面属性。

另外，可以直接在 Page 下调用 trackCustomEvent 方法，发送的自定义事件就会携带事件属性，如不需要则可以调用GrowingAutotracker.getContext().trackCustomEvent.

14. 无埋点点击事件

如是想要自动获取无埋点点击事件，需要为整个 App 添加事件监听器，如下所示：

import 'package:growingio_flutter_plugin/growingio_flutter_plugin.dart';

void main() async {
  runApp(const GrowingWidget(child:const MyApp()));
}

Growingio Flutter SDK 插件集成​

添加依赖​

iOS 集成方式说明​

Flutter 插件初始化​

Flutter 初始化​

Flutter On HarmonyOS 配置上下文​

初始化配置说明​

urlScheme 配置说明​

模块配置​

广告功能​

加密模块​

Json 模块​

API说明​

1. 数据采集开关​

参数说明​

示例​

2. 设置登录用户ID​

参数说明​

示例​

3. 清除登录用户ID​

示例​

4. 设置用户的地理位置​

参数说明​

示例​

5. 清除用户的地理位置​

示例​

6. 设置登录用户属性​

参数说明​

示例​

7. 设置埋点事件​

参数说明​

示例​

8. 获取设备ID​

示例​

9. 事件化计时器​

参数说明​

返回值说明​

示例​

10. 通用属性​

11. 事件 flush 上报​

示例​

12. 注册模块组件​

参数说明​

示例​

13. 无埋点页面事件​

14. 无埋点点击事件​

Growingio Flutter SDK 插件集成

添加依赖

iOS 集成方式说明

Flutter 插件初始化

Flutter 初始化

Flutter On HarmonyOS 配置上下文

初始化配置说明

urlScheme 配置说明

模块配置

广告功能

加密模块

Json 模块

API说明

1. 数据采集开关

参数说明

示例

2. 设置登录用户ID

参数说明

示例

3. 清除登录用户ID

示例

4. 设置用户的地理位置

参数说明

示例

5. 清除用户的地理位置

示例

6. 设置登录用户属性

参数说明

示例

7. 设置埋点事件

参数说明

示例

8. 获取设备ID

示例

9. 事件化计时器

参数说明

返回值说明

示例

10. 通用属性

11. 事件 flush 上报

示例

12. 注册模块组件

参数说明

示例

13. 无埋点页面事件

14. 无埋点点击事件