growingio_flutter_plugin 4.0.0

Flutter SDK Plugin for GrowingIO Flutter Plugin.

Growingio Flutter SDK 插件集成

添加依赖

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

dependencies:
  growingio_flutter_plugin: '^4.0.0'

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

Flutter SDK 无埋点如何生效，请阅读 Flutter 无埋点 原生+Flutter 若是纯 Flutter 应用，上述集成就可以使用了,Flutter和原生共用一套SDK逻辑，不会重复初始化两次。
若是在 Android 项目中同时包含了原生界面，且需要无埋点功能支持，那么就需要额外在 Android 配置中添加 GrowingIO Gradle 插件才能使原生无埋点生效。 在 iOS 项目中则无需其他操作。

Flutter 插件初始化

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

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: true);
      
  option.addGioComponent(EncoderLibraryGioModule());

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


  runApp(MyApp());
}

初始化配置说明

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

配置项	参数类型	是否必填	默认值	说明	版本
projectId	String	是	null	项目ID，每个应用对应唯一值	-
dataSourceId	String	是	null	应用的DataSourceId，唯一值	-
urlScheme	String	是	null	应用特有的URLScheme，用于外部应用拉起应用，如圈选	-
dataCollectionServerHost	String	否	null	服务端部署后的 ServerHost	-
autoTrackAllRoutePage	bool	否	true	是否自动开启页面采集	-
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 和圈选功能时，用于外部浏览器通过扫描二维码来拉起应用。

• Android 端 URLScheme 配置说明
• iOS 端 URLScheme 配置说明

模块配置

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");
          })));

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

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

• Android 已默认引入广告模块
• iOS 端 需引入广告模块

加密模块

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().registerComponent(module);

1. 数据采集开关

setDataCollectionEnabled
打开或关闭数据采集

参数说明

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

示例

GrowingAutotracker.getContext().setDataCollectionEnabled(true);

2. 设置登录用户ID

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

• 如果您的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. 注册模块组件

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

参数说明

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

示例

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

12. 无埋点页面事件

Flutter的 Page事件可以通过 mixin 类 GrowingPageStateMixin 或者 GrowingPageStatelessMixin 来手动实现。

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

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

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

2. 在 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.