使用Flutter SDK配置頁面瀏覽與點擊事件全埋點-全域採集與增長分析-阿里雲

環境準備

qt_common_sdk: ^2.1.4

｜---依賴原生iOS 1.7.6 版本

｜---依賴原生 Android 1.8.5.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() {
  // 初始化採集sdk
    if (!sdkHasInit) {
      sdkHasInit = true;
      QTCommonSdk.setCustomDomain('您的收數網域名稱', '您的備用收數網域名稱');
      QTCommonSdk.setLogEnabled(true);
      QTCommonSdk.initCommon('iOS的AppKey', 'Android的AppKey', '配置發布渠道');
      
    }
    // 全埋點相關的依賴QTCommonSdk初始化
    QTAutoTrack()
        .config(QTAutoTrackConfig(
          pageConfigs: [
            QTAutoTrackPageConfig<AutoTrackPage>( // 配置當前頁面基礎資訊
              pageName: 'Home',
              pagePath: '/Home',
              pageTitle: 'test Home',
            ),
            QTAutoTrackPageConfig<AutoTrackPageA>(
              pageName: 'Page2',
              pagePath: '/Page2',
              pageTitle: 'test Page2',
              skipMe: true // 使用skipMe屬性關閉該頁面的自動採集功能
            )
            ...
          ],
          eventHandler: (model) => {
            // 前置回呼函數
            Log.i("測試頁面",model)
          },
        ))
        .enable() // 開啟埋點
        .enableLog(); // 開啟log
    
     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. 設定頁面自動埋點

調用QTAutoTrack().enable() 開啟全埋點後（頁面和點擊）自動上報預設是開啟的，如果需要設定頁面採集相關功能，可以調用如下api：

// 啟用頁面埋點
QTAutoTrack().enablePageTrack();

/// 禁用頁面埋點
QTAutoTrack().disablePageTrack();

若只需禁止某頁面的自動採集上報的介面，您可以在PageConfig裡面配置對應的屬性：

QTAutoTrack()
  .config(QTAutoTrackConfig(
    pageConfigs: [
      ...,
      QTAutoTrackPageConfig<AutoTrackPageSkip>(
        pageName: 'Page3', // 頁面編碼
        pagePath: '/Home', // 頁面路由對應的路徑
        pageTitle: 'test Page3', // 頁面標題
        skipMe: true
      )
    ],
    eventHandler: (model) => {
      // 前置回呼函數
      QTTrackLogger.i("測試頁面",model)
      },
  ))
  .enable() // 開啟頁面和點擊事件全埋點
  .enableLog(); // 開啟flutter本地Log

其中

pageName 表示頁面編碼
pagePath 路由對應的路徑
skipMe 為是否關閉該頁面的自動瀏覽事件採集（true表示關閉，false表示開啟）

注意：skipMe設定的優先順序低於關閉頁面瀏覽事件自動採集的總開關QTAutoTrack().disablePageTrack()

重要

pageTitle設定的值目前的版本不會添加至統計事件裡面上報，後續版本考慮開發此功能

2.3 使用goRouter

為適配 Flutter 官方推薦的 GoRouter (v8.0+) 導航方案，QT Flutter SDK 2.1.2+ 版本新增路由相容模式，開發人員需要在PageConifg中設定forGoRouter = true將其開啟。

說明

在開啟goRouter採集後務必確保需要上報的路徑相關的頁面資訊在pageConfigs中配置正確

Demo如下：

import 'package:go_router/go_router.dart';
import 'package:qt_common_sdk/qt_common_sdk.dart';
import 'package:qt_common_sdk/qt_common_auto_track.dart';
import 'package:qt_common_sdk_example/page/auto_track_page.dart';
...

/// The route configuration.
final GoRouter _router = GoRouter(
  routes: <RouteBase>[
    GoRoute(
      path: '/',
      builder: (BuildContext context, GoRouterState state) {
        return const MainPage(title: 'Flutter Demo');
      },
      routes: <RouteBase>[
        GoRoute(
          path: '/auto_track',
          builder: (BuildContext context, GoRouterState state) {
            return AutoTrackPage();
          },
        ),
      ],
    ),
  ],
  observers: QTTrackNavigationObserver.wrap([]),
);


class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      routerConfig: _router,
    );
  }
}

class MainPage extends StatefulWidget {
  final String title;

  const MainPage({Key? key, required this.title}) : super(key: key);

  @override
  _MainPageState createState() => _MainPageState();
}

class _MainPageState extends State<MainPage> {
 ....
  @override
  void initState() {
    super.initState();
    ...
    if (!sdkHasInit) {
      sdkHasInit = true;
      QTCommonSdk.setCustomDomain(DOMAIN, DOMAIN);
      QTCommonSdk.setLogEnabled(true);
      QTCommonSdk.initCommon(APP_KEY, APP_KEY, '配置發布渠道');
    }
    QTAutoTrack()
        .config(QTAutoTrackConfig(
          forGoRouter: true, // 當前採用goRouter模式
          pageConfigs: [
            QTAutoTrackPageConfig<AutoTrackPage>(
              pageName: 'auto_track',
              pagePath: '/auto_track',
              pageTitle: 'test auto_track',
            ),
            ...
          ],
          eventHandler: (model) => {
            // 前置回呼函數
            QTTrackLogger.i("測試頁面",model)
          },
        ))
        .enable()
        .enableLog();
  }
 }
 ...

重要

pageTitle設定的值目前的版本不會添加至統計事件裡面上報，後續版本考慮開發此功能

3. 使用自動點擊全埋點

重要

重要： Android & iOS端需要開啟全埋點上報功能後事件才能正確上報整合代碼如下：

Android：

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        QtConfigure.setCustomDomain("您的收數服務網域名稱", null);
        QtConfigure.setLogEnabled(true);
        
        // flutter全埋點依賴原生開啟全埋點功能，需要手動設定
        QtTrackAgent.setAutoEventEnabled(true);        
        //...
    }
    //... 
}

iOS：

 [QTMobClick setAutoEventEnabled:YES];
 //設定網域名稱
 [QTConfigure setCustomDomain:@"您的收數網域名稱" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您應用的appKey" channel:@"App Store"];

調用QTAutoTrack().enable() 開啟全埋點後（頁面和點擊）自動上報預設是開啟的，如果需要設定點擊採集相關功能，可以調用如下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: () {},
)
...

4. 開啟日誌

日誌預設關閉，可通過以下方式開啟：

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().enableLog();

5. 配置相關（可選）

pageConfigs：用於配置頁面的參數，影響 page_start，page_end埋點。需要指定頁面的類型，配置只對指定頁面生效。

pageName：頁面的自訂 ID，對應埋點方案中的事件編碼。
pageTitle：頁面的標題，如果不配置，則使用 AppBar 中指定的 title，配置後優先使用配置的值。在
pagePath：頁面的路徑，如果不配置，則使用 MaterialApp 中通過 routes 配置的路徑，配置後優先使用配置的值。在頁面PV的埋點中會放在 page_path 欄位上報。
skipMe：預設為 false，設定為 true 後會忽略當前頁面PV的埋點。

ignoreElementKeys：忽略入參中通過 Key 指定元素的 click 埋點。
ignoreElementStringKeys：忽略入參中通過字串指定元素的 click 埋點，匹配方式是字串內容必須與元素 key 的 toString() 傳回值相同。
enablePageTrack：預設為 true，設定為 false 後會關閉所有的自動頁面PV的埋點。
enableClick：預設為 true，設定為 false 後會關閉所有的 click 埋點。
forGoRouter: 預設為false，設定為true後會預設按照pageConfigs裡面的配置去比對路由路徑和配置，QT Flutter SDK 2.1.2版本新增

您可以參考以下代碼進行配置：

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,
))；