全埋点功能_全域采集与增长分析(Quick Tracking)-阿里云帮助中心

环境准备

qt_common_sdk: ^2.1.0

｜---依赖原生iOS 1.5.8.PX 版本

｜---依赖原生 Android 1.6.3.PX 版本

初始化部分：

重要

要使用SDK 的全埋点功能首先得完整集成FlutterSDK 详情参照

flutter SDK的集成教程

1. 使用全埋点

全埋点默认关闭，可通过以下方法打开：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().enable();

关闭全埋点：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().disable();

完整 Demo

import 'package:qt_common_sdk/qt_common_sdk.dart';
import 'package:qt_common_sdk/qt_common_auto_track.dart';
...

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    if (!sdkHasInit) {
      sdkHasInit = true;
      QTCommonSdk.setCustomDomain(DOMAIN, DOMAIN);
      QTCommonSdk.setLogEnabled(true);
      QTCommonSdk.initCommon(APP_KEY, APP_KEY, '配置发布渠道');
      
    }
    // 全埋点相关的依赖QTCommonSdk初始化
    QTAutoTrack()
        .config(QTAutoTrackConfig(
          pageConfigs: [
            QTAutoTrackPageConfig<AutoTrackPage>(
              pageName: 'Home',
              pagePath: '/Home',
              pageTitle: 'test Home',
            ),
            QTAutoTrackPageConfig<AutoTrackPageA>(
              pageName: 'Page2',
              pagePath: '/Page2',
              pageTitle: 'test Page2',
            ),
            QTAutoTrackPageConfig<AutoTrackPageSkip>(
              pageName: 'Page3',
              pagePath: '/Home',
              pageTitle: 'test Page3',
              skipMe: true
            )
          ],
          eventHandler: (model) => {
            // 前置回调函数
            QTTrackLogger.i("测试页面",model)
          },
        ))
        .enable() // 开启埋点
        .enableLog();
    
     super.initState();
  }

  ...
    @override
    Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: QTTrackNavigationObserver.wrap([]),
      initialRoute: '/',
      routes: {
        '/': ((context) => Home()),
        '/page2': ((context) => Page2()),
        '/page3': ((context) => Page3()),
      },
    );
  }
}

2. 使用页面全埋点

2.1. 添加页面路由监听

使用Flutter页面全埋点需要手动开启。全埋点中页面PV事件是通过监听NavigatorObserver 采集的，因此想要页面全埋点生效我们需要直接在 MaterialApp 中配置 QTTrackNavigationObserver 如下所示：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: [QTTrackNavigationObserver()],
    ...
  );
}
...

也可以在已有的 navigatorObservers 列表中，通过 QTTrackNavigationObserver.wrap 包裹：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
  @override
  Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: QTTrackNavigationObserver.wrap([]),
    ...
  );
}
...

2.2. 设置页面自动埋点

开启全埋点后页面自动上报默认是开启的，如果需要设置页面采集相关功能，可以调用如下api：

// 启用页面埋点
QTAutoTrack().enablePageTrack();

/// 禁用页面埋点
QTAutoTrack().disablePageTrack();

若只需禁止某页面的自动采集上报的接口，您可以在pageConfigs里面配置对应的属性：

QTAutoTrack()
  .config(QTAutoTrackConfig(
    pageConfigs: [
      ...,
      QTAutoTrackPageConfig<AutoTrackPageSkip>(
        pageName: 'Page3', // 页面编码
        pagePath: '/Home', // 页面路由对应的路径
        pageTitle: 'test Page3', // 页面标题
        skipMe: true
      )
    ],
    eventHandler: (model) => {
      // 前置回调函数
      QTTrackLogger.i("测试页面",model)
      },
  ))
  .enable() // 开启埋点
  .enableLog();

其中

pageName 表示页面编码
pagePath 路由对应的路径
skipMe 为是否关闭该页面的自动浏览事件采集（true表示关闭，false表示开启）

注意：skipMe设置的优先级低于关闭页面浏览事件自动采集的总开关QTAutoTrack().disablePageTrack()

3. 使用自动点击全埋点

重要： Android端需要开启全埋点上报功能后事件才能正确上报集成代码如下：

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        QtConfigure.setCustomDomain("您的收数服务域名", null);
        // 打开调试log
        QtConfigure.setLogEnabled(true);
        // 采样率拉取依赖全埋点开关设置，如需要事件采样率控制功能，请按需调用此API
        QtTrackAgent.setAutoEventEnabled(true);        
        //...
    }
    //... 
}

开启全埋点后页面自动上报默认是开启的，如果需要设置页面采集相关功能，可以调用如下api：

// 启用点击全埋点
QTAutoTrack().enableClick();

/// 禁用页面埋点
QTAutoTrack().disableClick();

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
  @override
void initState() {
  QTAutoTrack().enable().disableClick();  // 开启全埋点，禁用自动点击埋点
  super.initState();
}
...

3.1. 设置 click 元素的自定义ID

我们通过 Key 来设置元素的自定义 ID，自定义 ID 在 click 埋点中会作为事件id进行上报，值是 Key 的 toString() 方法返回值，可以直接使用 QTElementKey

触发 click 埋点的元素目前支持以下组件：

GestureDetector
InkWell
ElevatedButton
ListTile

对于支持列表以外的组件，则无法通过 Key 设置自定义 ID，click 埋点会触发在组件内部的 GestureDetector 上。

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
ListTile(
  key: QTElementKey('custom-key'),
  title: Text("Click Me"),
  onTap: () {}
)
...

3.2. 忽略 click 元素

如果不希望统计某些元素的 click 埋点，可以通过以下办法忽略 click 元素：通过 QTElementKey 设置 skipMe：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
ListTile(
  key: QTElementKey('custom-key', skipMe: true),
  title: Text("Click Me"),
  onTap: () {},
)
...

通过 ignoreElementKeys() 方法指定元素的 key：

import 'package:qt_common_sdk/qt_common_auto_track.dart'

...
final customKey = QTElementKey('custom-key');

...
QTAutoTrack().ignoreElementKeys([customKey]);

...
ListTile(
  key: Key("custom-key"),
  title: Text("Click Me"),
  onTap: () {},
)
...

通过 ignoreElementStringKeys() 方法指定元素 key 的 string 值，只要与 key 的 toString() 返回值匹配即可生效，这里建议使用 QTElementKey：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
QTAutoTrack().ignoreElementStringKeys(['custom-key']);

...
ListTile(
  key: QTElementKey('custom-key'),
  title: Text("Click Me"),
  onTap: () {},
)
...

2.8 开启日志

日志默认关闭，可通过以下方式开启：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().enableLog();

3.1 配置相关（可选）

3.1 示例

pageConfigs：用于配置页面的参数，影响 pageview，pageleave 埋点。需要指定页面的类型，配置只对指定页面生效。

pageName：页面的自定义 ID，对应埋点方案中的事件编码。
pageTitle：页面的标题，如果不配置，则使用 AppBar 中指定的 title，配置后优先使用配置的值。在
pagePath：页面的路径，如果不配置，则使用 MaterialApp 中通过 routes 配置的路径，配置后优先使用配置的值。在 page_end，pageleave 埋点中会放在 page_path 字段上报。z
skipMe：默认为 false，设置为 true 后会忽略当前页面的 pageview，pageleave 埋点。

ignoreElementKeys：忽略入参中通过 Key 指定元素的 click 埋点。
ignoreElementStringKeys：忽略入参中通过字符串指定元素的 click 埋点，匹配方式是字符串内容必须与元素 key 的 toString() 返回值相同。
enablePageTrack：默认为 true，设置为 false 后会关闭所有的 pageview 埋点。
enableClick：默认为 true，设置为 false 后会关闭所有的 click 埋点。

import 'package:qt_common_sdk/qt_common_auto_track.dart';


QTAutoTrack().config(QTAutoTrackConfig(
  pageConfigs: [
    QTAutoTrackPageConfig<AutoTrackPage>(
      pageName: 'Home',
      pagePath: '/Home',
      pageTitle: 'test Home',
    ),
    QTAutoTrackPageConfig<AutoTrackPageA>(
      pageName: 'Page2',
      pagePath: '/Page2',
      pageTitle: 'test Page2',
    ),
    QTAutoTrackPageConfig<AutoTrackPageSkip>(
      pageName: 'Page3',
      pagePath: '/Home',
      pageTitle: 'test Page3',
      skipMe: true
    )
  ],
  eventHandler: (model) => {
    // 前置回调函数
    QTTrackLogger.i("测试页面",model)
  },
  ignoreElementKeys: [],
  ignoreElementStringKeys: [],
  enablePageTrack: true,
  enableClick: true,
))；