Flutter SDK 插件
Flutter SDK 插件提供了无埋点 SDK 和埋点 SDK 两个版本,在使用 Flutter 无埋点 SDK 前,需要按照 Flutter Aspect 集成 才能使无埋点功能生效。
环境配置
- Flutter SDK 插件的更新日志,可参阅 Release Notes
- Flutter SDK 无埋点如何生效,请阅读 Flutter Aspect 集成
Growingio Flutter SDK 插件集成
添加依赖
以工程flutter_app为例,在pubspec.yaml文件中添加依赖。
- 无埋点
- 埋点
dependencies:
growingio_autotracker_flutter_plugin: '2.2.0'
dependencies:
growingio_tracker_flutter_plugin: '2.2.0'
然后执行 flutter pub get 指令安装插件。
点击查看Growingio Flutter 插件和 SDK 版本的依赖关系
| Flutter 插件版本 | Android SDK 版本范围 | iOS SDK 版本范围 | HarmonyOS SDK 版本范围 |
|---|---|---|---|
| = v1.0.0 | >= v3.4.7 | >= v3.4.8 | — |
| = v1.1.0 | >= v3.5.0 | >= v3.5.0 | — |
| = v1.1.3 | >= v3.5.0 | >= v3.5.0 | — |
| = v2.1.0 | >= v3.5.0 | >= v3.5.0 | — |
| = v2.1.2 | >= v3.5.0 | >= v3.8.3 | — |
| = v2.1.3 | >= v3.5.0 | >= v3.8.3 | — |
| = v2.2.0 | >= v3.5.0 | 3.9.x(>= v3.9.2) | 2.9.x |
添加 Android 依赖
添加 maven 仓库
在 project 级别的 build.gradle 文件中添加 Maven 仓库
buildscript {
repositories {
// 添加maven仓库
mavenCentral()
//如果使用 SNAPSHOT 版本,则需要使用如下该仓库。
maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots/" }
}
}
allprojects {
repositories {
// 添加maven仓库
mavenCentral()
//如果使用 SNAPSHOT 版本,则需要使用如下该仓库。
maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots/" }
}
}
添加依赖
在 app 级别的 build.gradle 文件中添加代码依赖
- 依赖
- BoM
apply plugin: 'com.android.application'
dependencies {
implementation 'com.growingio.android:autotracker-cdp:3.5.1'
implementation 'com.growingio.android:flutter:3.5.1'
}
apply plugin: 'com.android.application'
dependencies {
// Import the BoM for the GrowingIO platform
implementation platform('com.growingio.android:autotracker-bom:3.5.1')
//GrowingIO 无埋点 SDK
implementation 'com.growingio.android:autotracker-cdp'
implementation 'com.growingio.android:flutter'
}
添加插件(集成无埋点需要)
在 project 级别的 build.gradle 文件中添加插件路径
buildscript {
...
dependencies {
//GrowingIO 无埋点 SDK plugin
classpath 'com.growingio.android:autotracker-gradle-plugin:3.5.0'
}
}
在 app 级别的 build.gradle 文件中添加 com.growingio.android.autotracker 插件
apply plugin: 'com.android.application'
//添加 GrowingIO 插件
apply plugin: 'com.growingio.android.autotracker'
...
插件最新发布版本为 Github Releases
关于如何在 Android Gradle Plugin 7 及其更高版本使用插件请参考 SDK 插件说明
iOS 集成方式说明
从 v2.2.0 起,插件同时支持 Swift Package Manager(SPM)与 CocoaPods 两种 iOS 原生依赖管理方式,均无需在 iOS 工程中手动添加 GrowingIO 原生 SDK 依赖。
Flutter 3.44 及以上(默认 SPM 模式)
添加依赖后无需任何额外操作,构建时 Flutter 会自动通过 SPM 引入插件及原生 GrowingAnalytics SDK(要求原生 SDK ≥ 3.9.2)。旧工程首次构建时 Flutter 会自动完成 SPM 集成迁移。
如果 Podfile 中曾手动添加过 pod 'GrowingAnalytics-cdp/...' 或 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(版本 3.9.2 起)→ 勾选 GrowingAutotracker_cdp(无埋点)或 GrowingTracker_cdp(埋点)产品添加到 app target。SPM 会自动与插件已依赖的同一个包去重,不会产生重复代码。
HarmonyOS 集成说明
从 v2.2.0 起,插件支持 HarmonyOS 平台,桥接 HarmonyOS 原生 SDK @growingio/analytics(CDP 模式)。
HarmonyOS 平台 CDP 模式目前仅支持埋点采集,暂不支持无埋点采集(PAGE / VIEW_CLICK / VIEW_CHANGE)与圈选(服务端限制),因此无需替换 AOP snapshot;扫码数据校验(MobileDebugger)不受影响。
此外,HarmonyOS 平台暂不支持 doDeepLinkByUrl(广告归因)与初始化后动态注册组件(registerComponent)。加解密(EncoderLibraryGioModule)、Protobuf(ProtobufLibraryModule)等组件请在 startWithConfiguration 的 modules 参数中配置。
- 需使用支持 HarmonyOS 的 Flutter SDK(如 3.7.12-ohos / 3.22.x-ohos),在 Flutter 工程的
ohos目录下构建。 - 原生 SDK 依赖由插件自动引入,初始化时
dataCollectionServerHost为必传参数。 - 插件在注册时会自动通过
FlutterPluginBinding获取 applicationContext 用于初始化原生 SDK,无需额外配置。 - 如需使用扫码数据校验(MobileDebugger),URL Scheme 配置分两部分。首先在
module.json5中 EntryAbility 对应的 skills 添加 URL Scheme:
{
"actions": [
"ohos.want.action.viewData"
],
"uris": [
{
"scheme": "Your URL Scheme",
"host": "growingio/webservice"
}
]
}
然后在 FlutterAbility 的 onCreate/onNewWant 中将 uri 传递给 SDK:
import { FlutterAbility } from '@ohos/flutter_ohos'
import Want from '@ohos.app.ability.Want'
import AbilityConstant from '@ohos.app.ability.AbilityConstant'
import { GrowingAnalytics } from 'growingio_autotracker_flutter_plugin'
export default class EntryAbility extends FlutterAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onCreate(want, launchParam)
let uri = want?.uri
if (uri) {
GrowingAnalytics.handleOpenURL(uri)
}
}
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onNewWant(want, launchParam)
let uri = want?.uri
if (uri) {
GrowingAnalytics.handleOpenURL(uri)
}
}
}
埋点 SDK 请将上方 import 中的
growingio_autotracker_flutter_plugin替换为growingio_tracker_flutter_plugin。
Flutter 插件初始化
GrowingIO Flutter SDK 支持在 Flutter 中初始化SDK,也同时支持在原生代码中初始化。如果需要更多的功能设置,我们更推荐您在原生端实现初始化。
原生端初始化
原生端初始化请参考各端的初始化文档:
- Android: 无埋点初始化配置、埋点初始化配置,另外,在 Android 原生初始化需要额外添加 Flutter 模块
- iOS: 无埋点初始化配置、埋点初始化配置
Flutter 初始化
在 Flutter 端进行初始化,请将 SDK 的初始化代码放入 main.dart 的 main 中,代码示例如下:
- 无埋点
- 埋点
void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
GrowingAutotracker.startWithConfiguration(
projectId: "Your ProjectId",
dataCollectionServerHost: "Your collection server host",
dataSourceId: "Your datasourceid",
urlScheme: "Yoour Url Scheme",
debugEnabled: true,
modules: {
AdvertLibraryGioModule(config: AdvertConfig()),
ProtobufLibraryModule()
},
dataCollectionEnabled: true,
idMappingEnabled: true,
cellularDataLimit: 10,
dataUploadInterval: 15,
sessionInterval: 20,
);
...
runApp(MyApp());
}
void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
GrowingTracker.startWithConfiguration(
projectId: "Your ProjectId",
dataCollectionServerHost: "Your collection server host",
dataSourceId: "Your datasourceid",
urlScheme: "Yoour Url Scheme",
debugEnabled: true,
modules: {
AdvertLibraryGioModule(config: AdvertConfig()),
ProtobufLibraryModule()
},
dataCollectionEnabled: true,
idMappingEnabled: true,
cellularDataLimit: 10,
dataUploadInterval: 15,
sessionInterval: 20,
);
...
runApp(MyApp());
}
初始化配置说明
在 Flutter 初始化中会传入各式的参数,参数配置如下表所示:
| 配置项 | 参数类型 | 是否必填 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|---|
| projectId | String | 是 | null | 项目ID,每个应用对应唯一值 | - |
| urlScheme | String | 是 | null | Android 应用特有的URLScheme,用于外部应用拉起应用,如圈选 | - |
| dataSourceId | String | 是 | null | 应用的DataSourceId,唯一值 | - |
| dataCollectionServerHost | String | 是 | null | 服务端部署后的 ServerHost | - |
| channel | String | 否 | null | 应用的分发渠道 | - |
| debugEnabled | bool | 否 | false | 调试模式,会打印SDK log,抛出错误异常,在线上环境请关闭 | - |
| cellularDataLimit | int | 否 | 10 | 每天发送数据的流量限制,单位MB | - |
| dataUploadInterval | int | 否 | 15 | 数据发送的间隔,单位秒 | - |
| sessionInterval | int | 否 | 30 | 会话后台留存时长,单位秒 | - |
| dataCollectionEnabled | bool | 否 | true | 是否采集数据 | - |
| modules | Set<LibraryGioModule> | 否 | empty | 模块集成,具体请阅读下方的模块说明 | - |
urlScheme 说明
在使用 GrowingIO SDK 的Mobile Debugger 和圈选功能时,需要外部浏览器通过扫描二维码来拉起应用。
模块配置
GrowingIO SDK 利用模块来实现SDK核心功能以外的额外功能,在 Flutter SDK 插件中,可以通过在 modules 传入模块声明来开启相应的功能。
目前 Flutter SDK 可启用的模块功能包括:
广告功能
GrowingTracker.startWithConfiguration(
//....
modules: {
AdvertLibraryGioModule(
config: AdvertConfig(readClipBoardEnable: true, /// 是否打开剪切板
deepLinkHost: "https://n.datayi.cn", /// 深度链接配置地址
asaEnabled: true, /// 仅iOS端使用
deepLinkCallback:(Map<String,String> params,int error,int time){
///监听深度链接中的地址参数
},
)),
},
//....
);
广告模块包括激活事件和深度链接,能帮助客户提供广告,活动的引导跳转和下载。
iOS 端从 v2.2.0 起,引入原生广告库的方式按集成模式二选一:
- SPM 模式:Xcode 打开 iOS 工程 → File → Add Package Dependencies… → 输入
https://github.com/growingio/growingio-sdk-ios-autotracker.git(版本 3.9.2 起)→ 产品列表中勾选GrowingModule_Advert添加到 app target(SPM 会自动与插件已依赖的同一个包去重) - CocoaPods 模式:Podfile 中添加
pod 'GrowingAnalytics/Advert'
未引入广告库时调用 doDeepLinkByUrl 会静默降级并在控制台提示“广告模块未集成”,不会崩溃。HarmonyOS 平台暂不支持广告模块。
在 Flutter SDK 启动广告模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:
加密模块
GrowingTracker.startWithConfiguration(
//....
modules: {
EncoderLibraryGioModule(),
},
//....
);
加密模块用于数据网络上传数据的加密。
在 Flutter SDK 启动加密模块同时,Android端需要引入相应的模块代码,请参考:
- Android 端 引入加密模块
- iOS端会打开相关配置,无须引入模块。
Protobuf 模块
GrowingTracker.startWithConfiguration(
//....
modules: {
ProtobufLibraryModule(),
},
//....
);
Protobuf 数据模块将会使用 Google Protobuf 格式保存和上传事件数据。
在 Flutter SDK 启动 Protobuf 模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:
H5混合模块
GrowingTracker.startWithConfiguration(
//....
modules: {
HybridLibraryGioModule(),
},
//....
);
若使用了原生的WebView,且内嵌 H5 页面如果也需要进行数据采集(H5 页面已经集成 Web JS SDK),则可以开启该 H5混合模块。
在 Flutter SDK 启动H5混合模块同时,原生端(包括Android和iOS端)都需要引入相应的模块代码,请参考:
API说明
- 无埋点
- 埋点
GrowingAutotracker.get().setDataCollectionEnabled(true)
GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name")
GrowingAutotracker.get().cleanLoginUserId()
GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});
GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11)
GrowingAutotracker.get().cleanLocation()
GrowingAutotracker.get().getDeviceId()
GrowingAutotracker.get().trackCustomEvent(eventName: "eventName", attributes: {"age":"18"})
String? timerId =await GrowingAutotracker.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();
GrowingAutotracker.get().registerComponent(module);
GrowingTracker.get().setDataCollectionEnabled(true)
GrowingTracker.get().setLoginUserId(userId: "cpacm",userKey: "name")
GrowingTracker.get().cleanLoginUserId()
GrowingTracker.get().setLocation(latitude: 20.11,longitude: 20.11)
GrowingTracker.get().cleanLocation()
GrowingTracker.get().setLoginUserAttributes(attributes: {"sex":"female"})
GrowingTracker.get().getDeviceId()
GrowingTracker.get().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});
String? timerId =await GrowingTracker.get().trackTimerStart(eventName: "custom");
GrowingTracker.get().trackTimerPause(timerId: timerId!);
GrowingTracker.get().trackTimerResume(timerId: timerId);
GrowingTracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingTracker.get().removeTimer(timerId: timerId);
GrowingTracker.get().clearTrackTimer();
GrowingTracker.get().registerComponent(module);
1. 数据采集开关
setDataCollectionEnabled
打开或关闭数据采集
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
enabled | boolean | true打开数据采集,false关闭数据采集,默认 true |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().setDataCollectionEnabled(true);
GrowingTracker.get().setDataCollectionEnabled(true);
2. 设置登录用户ID
setLoginUserId
当用户登录之后调用,设置登录用户ID
支持 ID-MAPPING 需在初始化 SDK 时设置 idMappingEnabled 为 true
如果您的App每次用户升级版本时无需重新登录的话,为防止用户本地缓存被清除导致的无法被识别为登录用户,建议在用户每次升级App版本后初次访问时重新调用setLoginUserId方法
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
userId | String | 长度限制大于0且小于等于1000,如果大于长度1000将只截取前1000长度 |
userKey | String | 适用于ID-MAPPING,可设置 userId 的类型,可选填 |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().setLoginUserId(userId: "cpacm",userKey: "name");
GrowingTracker.get().setLoginUserId(userId: "cpacm",userKey: "name");
3. 清除登录用户ID
cleanLoginUserId
当用户登出之后调用,清除已经设置的登录用户ID。
示例
- 无埋点
- 埋点
GrowingAutotracker.get().cleanLoginUserId();
GrowingTracker.get().cleanLoginUserId();
4. 设置用户的地理位置
setLocation
设置用户当前的地理位置,基于WGS-84坐标
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
latitude | double | 地理坐标点纬度 |
longitude | double | 地理坐标点经度 |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().setLocation(latitude: 20.11,longitude: 20.11);
GrowingTracker.get().setLocation(latitude: 20.11,longitude: 20.11);
5. 清除用户的地理位置
cleanLocation
清除用户当前的地理位置
示例
- 无埋点
- 埋点
GrowingAutotracker.get().cleanLocation();
GrowingTracker.get().cleanLocation();
6. 设置登录用户属性
setLoginUserAttributes
发送登录用户属性事件,用于用户信息相关分析;
在添加发送用户属性事件代码之前,需在CDP平台用户管理界面创建用户属性。
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
attributes | Map<String, String> | 用户属性信息 |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().setLoginUserAttributes(attributes: {"sex":"female"});
GrowingTracker.get().setLoginUserAttributes(attributes: {"sex":"female"});
7. 设置埋点事件
trackCustomEvent
发送一个埋点事件;注意:在添加发送的埋点事件代码之前,需在CDP平台事件管理界面创建埋点事件以及关联事件属性;
如果事件属性需关联维度表,请在事件属性下关联维度表( CDP平台版本>= 2.1 )
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
eventName | String | 事件名,事件标识符 |
attributes | Map<String, String> | 事件发生时所伴随的属性信息;当事件属性关联有维度表时,属性值为对应的维度表模型ID(记录ID)(可选) |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});
GrowingTracker.get().trackCustomEvent(eventName: "custom",attributes: {"item":"exp"});
8. 获取设备ID
getDeviceId
获取设备ID,又称为匿名用户ID,SDK 自动生成用来定义唯一设备。
如果没有初始化SDK 或者关闭采集开关可能返回值为null,且可能有IO操作。
示例
- 无埋点
- 埋点
GrowingAutotracker.get().getDeviceId();
GrowingTracker.get().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.get().trackTimerStart(eventName: "custom");
GrowingAutotracker.get().trackTimerPause(timerId: timerId!);
GrowingAutotracker.get().trackTimerResume(timerId: timerId);
GrowingAutotracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingAutotracker.get().removeTimer(timerId: timerId);
GrowingAutotracker.get().clearTrackTimer();
String? timerId =await GrowingTracker.get().trackTimerStart(eventName: "custom");
GrowingTracker.get().trackTimerPause(timerId: timerId!);
GrowingTracker.get().trackTimerResume(timerId: timerId);
GrowingTracker.get().trackTimerEnd(timerId: timerId,attributes: {});
GrowingTracker.get().removeTimer(timerId: timerId);
GrowingTracker.get().clearTrackTimer();
10. 注册模块组件
registerComponent
可通过该方法手动注册SDK需要的可配置模块组件(推荐在初始化通过 Configuration 初始化时注册)。
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
module | LibraryGioModule | 模块 |
config | Configuration | 模块的配置类(可选参数) |
示例
- 无埋点
- 埋点
GrowingAutotracker.get().registerComponent(ProtobufLibraryModule());
GrowingTracker.get().registerComponent(ProtobufLibraryModule());
11. 发送无埋点页面事件
trackCustomPage
可以手动将一个 Widget 作为 Page 页面,发送一个 Page 事件。
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
title | String | 页面标题 |
widget | Widget | 控件 |
示例
class SplashScreen extends StatefulWidget{
SplashScreen({Key? key}) : super(key: key){
GrowingAutotracker.get().trackCustomPage("Splash页面", this);
}
}
12. 自定义无埋点页面事件属性
IGrowingPage
使用 IGrowingPage 接口,可以自定义页面事件的标题,路径和事件属性。页面事件会优先使用该接口里面赋予的值。
参数说明
| 参数 | 参数类型 | 说明 |
|---|---|---|
pageTitle | String | 页面标题 |
pageUri | String | 页面Uri |
pagePath | String | 页面路径 |
attributes | Map | 页面属性 |
示例
class SplashScreen extends StatefulWidget with IGrowingPage{
/// 页面标题
String? get pageTitle => "Splash页面";
///格式为:package::aaa/bbb.dart/PageWidget
///其中前缀为 为 dart 的 importUri,后缀为页面的 Widget。
String? get pageUri => "package::ui/splash.dart/SplashScreen";
///如 /books/100
String? get pagePath => "/splash";
///页面属性
Map<String, String>? get attributes => {"action":"欢迎"};
}