Full buried point function

Environment preparation

qt_common_sdk: ^2.1.4

| --- Depends on native iOS 1.7.6

| --- Depends on the native Android version 1.8.5.PX

Initialization section:

1. Use full auto-tracking

Full auto-tracking is disabled by default. You can enable it by using the following method:

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().enable();

Disable full auto-tracking:

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().disable();

Complete Demo

The following is a complete configuration example:

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() {
  // Initialize the collection SDK.
    if (!sdkHasInit) {
      sdkHasInit = true;
      QTCommonSdk.setCustomDomain ('Your receipt domain', 'Your alternate receipt domain');
      QTCommonSdk.setLogEnabled(true);
      QTCommonSdk.initCommon ('AppKey' for iOS, 'AppKey' for Android, 'Configure the release channel');
      
    }
    // Initialize the QTCommonSdk dependency related to all burial points.
    QTAutoTrack()
        .config(QTAutoTrackConfig(
          pageConfigs: [
            QTAutoTrackPageConfig<AutoTrackPage>( // Configure the basic information of the current page.
              pageName: 'Home',
              pagePath: '/Home',
              pageTitle: 'test Home',
            ),
            QTAutoTrackPageConfig<AutoTrackPageA>(
              pageName: 'Page2',
              pagePath: '/Page2',
              pageTitle: 'test Page2',
              skipMe: true // Use the skipMe attribute to disable automatic collection on this page.
            )
            ...
          ],
          eventHandler: (model) => {
            // Pre-callback function
            Log.i("Test page",model)
          },
        ))
        . enable() // Enable tracking.
        . enableLog(); // Enable log.
    
     super.initState();
  }

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

2. Use full page auto-tracking

2.1. Add a page route listener

You must manually enable the full auto-tracking function for Flutter pages. Page PV events are collected by listening to the NavigatorObserver. To enable page PV events, configure QTTrackNavigationObserver in MaterialApp.

import 'package:qt_common_sdk/qt_common_auto_track.dart';

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

You can also wrap an existing navigatorObservers list with QTTrackNavigationObserver.wrap:

import 'package:qt_common_sdk/qt_common_auto_track.dart';

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

2.2. Set automatic tracking

By default, automatic reporting is enabled after full auto-tracking (page and click) is enabled by calling QTAutoTrack().enable(). To configure page tracking separately, use the following APIs:

// Enable page tracking.
QTAutoTrack().enablePageTrack();

/// Disable page tracking.
QTAutoTrack().disablePageTrack();

To disable automatic tracking for a specific page, set the corresponding properties in PageConfig:

QTAutoTrack()
  .config(QTAutoTrackConfig(
    pageConfigs: [
      ...,
      QTAutoTrackPageConfig<AutoTrackPageSkip>(
        pageName: 'Page3', // The page encoding.
        pagePath: '/Home', // The path of the page route.
        pageTitle: 'test Page3', // The title of the page.
        skipMe: true
      )
    ],
    eventHandler: (model) => {
      // Pre-callback function
      QTTrackLogger.i("Test page",model)
      },
  ))
  . enable() // Enable page and click event tracking
  . enableLog(); // Enable the flutter local log 

Parameters:

• pageName: the page encoding.

• pagePath: the path of the page route.

• skipMe: specifies whether to disable automatic page view event collection. A value of true disables collection. A value of false enables collection.

Note: The skipMe setting has a lower priority than the QTAutoTrack().disablePageTrack() switch, which disables automatic page view event collection.

2.3 Using GoRouter

To support the GoRouter (v8.0+) navigation solution recommended by Flutter, route compatibility mode was added in QT Flutter SDK 2.1.2+. Set forGoRouter= true in PageConfig to enable this mode.

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, 'Configure the release channel');
    }
    QTAutoTrack()
        .config(QTAutoTrackConfig(
          forGoRouter: true, // The current goRouter mode is used.
          pageConfigs: [
            QTAutoTrackPageConfig<AutoTrackPage>(
              pageName: 'auto_track',
              pagePath: '/auto_track',
              pageTitle: 'test auto_track',
            ),
            ...
          ],
          eventHandler: (model) => {
            // Pre-callback function
            QTTrackLogger.i("Test page",model)
          },
        ))
        .enable()
        .enableLog();
  }
 }
 ...

3. Use automatic click tracking

Android:

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        QtConfigure.setCustomDomain("Your collection service domain name", null);
        QtConfigure.setLogEnabled(true);
        
        // Flutter full tracking depends on the native feature. You need to manually set the full tracking feature.
        QtTrackAgent.setAutoEventEnabled(true);        
        //...
    }
    //... 
}

iOS:

 [QTMobClick setAutoEventEnabled:YES];
 // Set the domain name.
 [QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil]; 
 // Initialize the appkey.
 [QTConfigure initWithAppkey:@"AppKey of your application" channel:@"App Store"]; 

By default, automatic reporting is enabled after full auto-tracking (page and click) is enabled by calling QTAutoTrack().enable(). To configure click tracking separately, use the following APIs:

// Enable all click tracking.
QTAutoTrack().enableClick();

/// Disable click tracking.
QTAutoTrack().disableClick();

import 'package:qt_common_sdk/qt_common_auto_track.dart';

...
@override
void initState() {
  QTAutoTrack().enable().disableClick(); // Enable full tracking and disable automatic click tracking.
  super.initState();
}
...

3.1. Set the custom ID of the click element.

Use Key to set a custom ID for an element. The custom ID is reported as the event ID in click tracking events. The value is the return value of the toString() method of Key. You can use QTElementKey directly.

Click tracking supports the following components:

• GestureDetector

• InkWell

• ElevatedButton

• ListTile

For unsupported components, you cannot use Key to set a custom ID. Click tracking is triggered on the GestureDetector component instead.

import 'package:qt_common_sdk/qt_common_auto_track.dart';

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

3.2. Ignore the click element

To exclude specific elements from click tracking, use one of the following methods: Set skipMe with QTElementKey:

import 'package:qt_common_sdk/qt_common_auto_track.dart';

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

Use the ignoreElementKeys() method to specify an element by its 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: () {},
)
...

Use the ignoreElementStringKeys() method to specify the string value of an element key. The match takes effect when the string value matches the toString() value of the key. We recommend that you use 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. Enable logging

Logging is disabled by default. Enable it by using the following method:

import 'package:qt_common_sdk/qt_common_auto_track.dart';

QTAutoTrack().enableLog();

5. Configuration options

• pageConfigs: configures page parameters that affect the page_start and page_end events. You must specify the page type. The configuration takes effect only on the specified page.

• pageName: the custom page ID, which corresponds to the event code in the tracking scheme.

• pageTitle: the title of the page. If not specified, the title from AppBar is used.

• pagePath: the path of the page. If not specified, the path configured in MaterialApp routes is used. The specified value takes priority. The page_path is included in the page PV event report.

• skipMe: defaults to false. If set to true, page PV tracking is disabled for the current page.

• ignoreElementKeys: ignores click tracking for elements specified by Key.

• ignoreElementStringKeys: ignores click tracking for elements whose key toString() return value matches the specified string.

• enablePageTrack: defaults to true. If set to false, all automatic page PV tracking is disabled.

• enableClick: defaults to true. If set to false, click tracking is disabled.

• forGoRouter: defaults to false. If set to true, the routing path is matched against the configuration in pageConfigs. Available in QT Flutter SDK 2.1.2+.

Example configuration:

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) => {
    // Pre-callback function
    QTTrackLogger.i("Test page",model)
  },
  ignoreElementKeys: [],
  ignoreElementStringKeys: [],
  enablePageTrack: true,
  enableClick: true,
));