- 平台介绍
- 接入指引
- 版本信息
- 使用流程
- 功能手册
- 操作视频
- 技术文档
- 基础知识
- 客户端SDK
- 服务端SDK
- 数据导入
- API功能
- SQL手册
- DML
- SQL函数
- 日期函数
- convert_tz
- curdate,current_date
- current_timestamp
- curtime,current_time
- date_add
- date_format
- date_sub
- datediff
- day
- dayname
- dayofmonth
- dayofweek
- dayofyear
- from_days
- from_unixtime
- hour
- makedate
- minute
- month
- monthname
- now
- second
- str_to_date
- time_round
- timediff
- timestampadd
- timestampdiff
- to_date
- to_days
- unix_timestamp
- utc_timestamp
- week
- weekday
- weekofyear
- year
- yearweek
- localtime,localtimestamp
- quarter
- last_day
- extract
- date_trunc
- minutes_add
- minutes_diff
- minutes_sub
- seconds_add
- seconds_diff
- seconds_sub
- hours_add
- hours_diff
- hours_sub
- days_add
- days_diff
- days_sub
- weeks_add
- weeks_diff
- weeks_sub
- months_add
- months_diff
- months_sub
- years_add
- years_diff
- years_sub
- 字符串函数
- append_trailing_char_if_absent
- to_base64
- from_base64
- ascii
- length
- bit_length
- char_length
- lpad
- rpad
- lower
- lcase
- upper
- ucase
- initcap
- repeat
- reverse
- char
- concat
- concat_ws
- substr
- substring
- sub_replace
- ends_with
- starts_with
- trim
- ltrim
- rtrim
- null_or_empty
- not_null_or_empty
- hex
- unhex
- elt
- instr
- locate
- find_in_set
- replace
- left
- right
- strleft
- strright
- split_part
- split_by_string
- substring_index
- money_format
- parse_url
- convert_to
- extract_url_parameter
- uuid
- space
- sleep
- 日期函数
- 数据类型
- 数据管理
- 常见问题
- 合规说明
- 资源下载
- AB测试
SDK接入
帮助中心 > 技术文档 > 客户端SDK > 跨平台框架 > Flutter 插件 > SDK接入
Flutter插件接入流程主要分为两个步骤(两个文档):
1、SDK配置:将对应的SDK集成到您的产品项目中,然后进行初始化代码处理;
2、SDK接入:将需要埋点的数据,按照SDK包装不同的方法进行数据上送,其中功能主要包含两大类:全埋点(自动采集数据上送)、自定义埋点(手动设置业务数据上送)。
1. 开启全埋点
1.1 移动端
说明:在SDK初始化时,通过 autoTrackTypeList 参数进行配置可开启记录全埋点事件,不配置此参数则默认不开启。
void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
// 放到WidgetsFlutterBinding.ensureInitialized()之后初始化;
if (kIsWeb) {
...
} else {
HinaFlutterPlugin.initForMobile(
...,
autoTrackTypeList: {
// 开启全埋点:App启动
HAAutoTrackType.APP_START,
// 开启全埋点:App退出
HAAutoTrackType.APP_END
},
...
);
}
...
runApp(const MyApp());
}
注意:
- flutter工程仅支持采集APP启动和退出;
- 浏览页面[H_AppViewScreen]、控件点击[H_AppClick]的两个行为事件仅对原生工程支持,所以在非原生工程的情况下,该两个行为事件(浏览页面[H_AppViewScreen]、控件点击[H_AppClick])需要手动设置,设置示例代码如下,可参考进行埋点
1、对于全局的页面浏览事件,可以结合使用 Flutter 的路由机制和事件监听来记录,例如:
class _MyNavigatorObserver extends NavigatorObserver {
@override
void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
super.didPush(route, previousRoute);
// 记录页面浏览事件
// ViewScreen: 页面浏览事件名
// page_title: 页面标题
// page_id: 页面id
HinaFlutterPlugin.track('H_AppViewScreen',
{ 'page_title': 'route.settings.pageName', 'page_id': 'route.settings.pageId' });
}
}
在这个示例中,我们使用了一个自定义的路由观察者 _MyNavigatorObserver,它继承自 NavigatorObserver 类,并重写了 didPush 和 didPop 方法,在页面进入和退出时调用相应的埋点记录方法。你需要根据你实际使用的埋点分析库的要求,在 _MyNavigatorObserver 类的相应方法中调用相应的事件追踪方法。
需要注意的是,这只是一个简单的示例,实际的全埋点实现可能涉及更复杂的逻辑和数据收集方式,具体的实现方式和细节会根据你所使用的埋点分析库和业务需求而有所不同。
2、对于全局的点击事件,可以创建一个全局的按钮点击事件监听器,例如:
void _attachButtonTapListeners(Route<dynamic> route, String page) {
final buttons = findButtonsInRoute(route);
buttons.forEach((button) {
button.onTap = () {
// 记录点击事件
HinaFlutterPlugin.track('H_AppClick',{
// 记录元素内容,如 '注册'
'element_content': 'button.text',
// 记录元素类型,如 'TextButton'
'element_type': 'button.class'
});
button.onTap?.call();
};
});
}
在这个示例中,我们创建了全局按钮点击事件监听器。它继承自 NavigatorObserver 类,并在页面进入后寻找当前页面中的按钮,为每个按钮注册点击事件监听器,并在按钮点击时记录相应的埋点。
这样,当用户在任何页面点击按钮时,都会触发全局按钮点击事件监听器,从而进行埋点记录。请根据你的实际需求和业务逻辑进行相应的调整和扩展。
1.2 web端
详见Web JS SDK初始化参数;
void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
// 放到WidgetsFlutterBinding.ensureInitialized()之后初始化;
if (kIsWeb) {
// web平台有单独的初始化方法,具体查看Web JS SDK集成文档;
HinaFlutterPlugin.callMethodForWeb('init', [{
...,
'autoTrackConfig': {
//是否开启自动点击采集, true表示开启,自动采集 H_WebClick 事件
'clickAutoTrack': true,
//是否开启页面停留采集, true表示开启,自动采集 H_WebStay 事件
'stayAutoTrack': true,
}
}]);
} else {
...
}
...
runApp(const MyApp());
}
2. 用户关联
2.1 用户登录
支持平台:【android、iOS、web】
说明:当用户注册成功或登录成功时,需要调用 SDK 的 setUserUId() 方法。
HinaFlutterPlugin.setUserUId("您平台用户唯一标识");
注意:为了准确记录登录用户的行为信息,建议在以下时机各调用一次用户登录方法:
· 用户在注册成功时
· 用户登录成功时
· 已登录用户每次启动 App 时
2.2 获取设备唯一ID
支持平台:【android、iOS、web】
说明:如需获取设备唯一id,请在初始化SDK后调用getDeviceUId()方法进行获取。
//返回Future<String?>
var deviceUId = await HinaFlutterPlugin.getDeviceUId();
2.3 自定义设备唯一ID
支持平台:【android、iOS、web】
说明:默认情况下,SDK 会生成设备唯一ID 并可以保证该ID的唯一性,如需替换SDK默认分配的,配置如下:
//通过API配置
HinaFlutterPlugin.setDeviceUId(String deviceUId);
注意:
android平台:
SDK 默认使用 AndroidId 作为设备 ID,如果 AndroidId 获取不到则获取随机的 UUID。
iOS平台:
如果 App 引入了 AdSupport 库,SDK 默认使用 IDFA 作为设备唯一 ID,使用 IDFA 能避免用户在重装 App 后设备 ID 发生变化的情况。若没有IDFA,SDK 会使用 IDFV,如果 IDFV 获取失败,则使用随机的 UUID,一般情况下都能够获取到 IDFV。如果使用 IDFV 或 UUID ,当用户卸载重装 App 时设备 ID 会变。
web平台:
默认是 cookie_id。
3. 用户属性
3.1 设置用户属性
支持平台:【android、iOS、web】
说明:同一个 key 多次设置时,会进行覆盖,value 值只会记录最后设定的值。
var properties = <String, dynamic>{};
properties["user_name"] = '张三';
HinaFlutterPlugin.userSet(properties);
3.2 固定初始值的属性
支持平台:【android、iOS、web】
说明:同一个 key 多次设置时,不会进行覆盖,value 值只会记录初次设定的值。
场景示例:适用于为用户设置首次激活时间、首次注册时间等属性。
var properties = <String, dynamic>{};
properties["user_register_time"] = '10101010';
HinaFlutterPlugin.userSetOnce(properties);
3.3 数值类型的属性
支持平台:【android、iOS、web】
说明:同一个 key 多次设置时,value 值(数值类型)进行求和计算;
场景示例:常用于记录用户付费次数、付费额度、积分等属性。
var properties = <String, num>{};
properties['score'] = 8;
HinaFlutterPlugin.userAdd(properties);
3.4 属性取消
支持平台:【android、iOS】
说明:取消已设置的某个用户属性。
var key = 'user_name';
HinaFlutterPlugin.userUnset(key);
3.5 清空用户属性
支持平台:【android、iOS】
说明:清空当前用户的用户属性。
HinaFlutterPlugin.userDelete();
4. 自定义埋点
用于记录埋点事件。
4.1 自定义埋点
支持平台:【android、iOS、web】
说明:使用track()方法进行直接埋点,埋点事件支持添加自定义属性。
//比如:点击“开始阅读”按钮,并添加属性:小说id、小说的章节;
var eventName = 'novel_read_btn_click';
var properties = {'novel_id': '1234567890', 'novel_chapter': '3'};
HinaFlutterPlugin.track(eventName, properties);
4.2 自定义时长埋点
支持平台:【android、iOS、web】
说明:需要成对调用计时器的开始和结束方法,以此来实现对统计时长的事件采集;
*在事件开始时,调用trackTimerStart("event1")
,该方法并不会真正发送事件;
*在事件结束时,调用trackTimerEnd("event1", properties)
,SDK 会触发 “Event” 事件,并自动将事件持续时间记录在事件属性 “H_event_duration” 中。
// 比如:开始观看视频;
HinaFlutterPlugin.trackTimerStart("watch_video");
// 比如:结束观看视频;
var properties = <String, dynamic>{};
properties["video_id"] = "1234567890";//添加自定义属性
properties["video_type"] = "娱乐";//添加自定义属性
// 调用 trackTimerEnd 方法,会触发事件,并在属性 event_duration 中记录时长;
HinaFlutterPlugin.trackTimerEnd("watch_video", properties);
5. 事件属性
在进行埋点事件追踪时,您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性。
5.1 获取预置属性
支持平台:【android、iOS、web】
说明:如需了解和使用预置属性,可以通过此方法获取预置属性。
// 返回Future<Map<String, dynamic>?>
var result = await HinaFlutterPlugin.getPresetProperties();
5.2 设置公共属性
支持平台:【android、iOS、web】
说明:公共属性是指对于所有事件都需要添加的属性,设置之后 SDK 会在每次触发埋点时,自动获取并添加到触发的事件中。
var properties = {'app_name': 'SDKDemo'};
HinaFlutterPlugin.registerCommonProperties(properties);
6. 数据存储与发送
在每次调用 track()、setUserUId()、userSet() 等方法时,SDK 会将埋点事件保存在数据库中,并会检查如下条件,以判断是否向服务器上传数据:
1.是否是 WIFI/2G/3G/4G/5G 网络条件
2.是否满足发送条件之一:
a.与上次发送的时间间隔是否大于 flushInterval
b.本地缓存日志数目是否大于 flushPendSize
c.事件类型为 setUserUid() 方法触发的 H_SignUp 事件
6.1 上报条件
支持平台:【android、iOS】
6.1.1 缓存条数
说明:设置本地缓存日志的最大条目数,默认本地埋点数据缓存为 100 条。
//初始化时配置
HinaFlutterPlugin.init(
...
flushPendSize: 50,//最少50条。
...);
//或者在初始化后,通过API配置
HinaFlutterPlugin.setFlushPendSize(int size);
6.1.2 发送间隔
支持平台:【android、iOS】
说明:设置埋点数据发送的间隔,默认为 15s。
//初始化时配置
HinaFlutterPlugin.init(
...
flushInterval: 5000,//最小 5 秒,单位毫秒。
...);
//或者在初始化后,通过API配置
HinaFlutterPlugin.setFlushInterval(int interval);
6.1.3 设置数据的网络上传策略
支持平台:【android、iOS】
说明:默认情况下,在 WIFI/3G/4G/5G 网络条件下,SDK 都会尝试去同步数据。可以自由组合来指定发送数据的网络策略。
//初始化时配置
HinaFlutterPlugin.init(
...
networkTypeList: {
HANetworkType.TYPE_3G,
HANetworkType.TYPE_4G,
HANetworkType.TYPE_WIFI,
HANetworkType.TYPE_5G
},
...);
//或者在初始化后,通过API配置;
HinaFlutterPlugin.setFlushNetworkPolicy(Set<HANetworkType>? networkTypeList);
6.2 立即上报(强制上报)
支持平台:【android、iOS】
说明:如果追求数据采集的时效性,调用flush(),即可立即执行上报。
HinaFlutterPlugin.flush();
注意:在 App 进入后台状态或监听到网络切换有网络时,SDK 会调用 flush() 方法,将缓存的数据发送。
6.3 本地数据缓存上限值
支持平台:【android、iOS】
说明:Android和iOS设置维度不一样,如有需要,请分开设置;
HinaFlutterPlugin.init(
...
// android配置空间大小,SDK 本地数据库默认缓存数据的上限值为 32MB
maxCacheSizeForAndroid: 16 * 1024 * 1024,//设置最小 16MB(16 * 1024 * 1024),单位 byte;
// iOS配置事件数量,默认最小值10000条事件,低于10000时不生效,防止设置的值太小导致事件丢失
maxCacheSizeForIOS: 20000,
...);
注意:当存储数量达到上限值,会依次丢弃老数据,保留最新的数据。
7. 其他功能
7.1 开启App与H5打通功能
支持平台:【android、iOS】
说明:初始化 SDK 时,进行如下配置。
HinaFlutterPlugin.init(
...
enableJSBridge: true,
...);
7.2 日志开关
支持平台:【android、iOS、web】
说明:初始化 SDK 时,进行如下配置。
void main() async {
...
WidgetsFlutterBinding.ensureInitialized();
// 放到WidgetsFlutterBinding.ensureInitialized()之后初始化;
if (kIsWeb) {
// web平台有单独的初始化方法,具体查看Web JS SDK集成文档;
HinaFlutterPlugin.callMethodForWeb('init', [{
...,
'showLog' : true,
...
}]);
} else {
HinaFlutterPlugin.initForMobile(
...,
enableLog: true //日志打开,默认关闭
);
}
...
runApp(const MyApp());
}
最后编辑:王建华 更新时间:2024-09-05 21:06