Screen Tracking

For screen navigation in Flutter, refer to the Flutter developer documentation below.

• Flutter Navigation & Routing

• Navigator

• RouteObserver

Because Flutter fundamentally uses a single Activity/ViewController architecture, it is difficult to automatically collect screen information.

To properly collect $page_view and $engagement events, you must explicitly call the setCurrentScreen method each time the screen changes.

setCurrentScreen

This feature is supported in Flutter SDK 2.28.0 and above.

Use the setCurrentScreen(screen) method to track screens.

• The minimum time unit for Screen Tracking is 1 second.

• $engagement for pages changed within 1 second is not measured.

Parameter	Type	Required	Description
name	string	Required	The name of the current screen.
className	string	Required	If you do not need a separate class name, enter the same value as name.

Screen Tracking cannot be performed for the same screen.

If setCurrentScreen is called with a Screen that has the same name and className as the previous screen, it is recognized as no screen transition occurred and no action is taken.

• $page_view and $engagement are not triggered.

Example

It is recommended to call setCurrentScreen inside route change detection methods such as didPush and didPop of NavigatorObserver.

import "package:hackle/hackle.dart";

class HackleRouteObserver extends NavigatorObserver {
  final NavigationService _navigationService = NavigationService();

  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPush(route, previousRoute);
    _setCurrentScreen(route);
  }

  @override
  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPop(route, previousRoute);
    if (previousRoute != null) {
      _setCurrentScreen(previousRoute);
    }
  }

  @override
  void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) {
    super.didReplace(newRoute: newRoute, oldRoute: oldRoute);
    if (newRoute != null) {
      _setCurrentScreen(newRoute);
    }
  }

  void _setCurrentScreen(Route route) {
    var name = route.settings.name;
    if (name == null || name.isEmpty) {
      return;
    }
		var screen = Screen.builder(name: name, className: name).build();
    HackleApp.setCurrentScreen(screen);
  }
}

Property

The Hackle SDK supports adding properties to an Event object.

• You can add a maximum of 64 properties per event object.

Category	Type	Constraints
Property Key (key)	string	Maximum 128 characters. Case-insensitive. For example, amount and AMOUNT are treated as the same key.
Property Value (value)	boolean, string, number, array	For string type, maximum 1024 characters. For number type, up to 15 integer digits and up to 6 decimal places are supported.

Example

var screen = Screen.builder(name: name, className: name)
    .property("key", "value")
    .build();
HackleApp.setCurrentScreen(screen);

Disabling automaticScreenTracking

The SDK has automaticScreenTracking enabled by default. If you do not want to track MainActivity and ViewController, you must disable automaticScreenTracking.

You can configure automaticScreenTracking when initializing the SDK.

If automaticScreenTracking is enabled while you are manually collecting screen data via setCurrentScreen, $page_view and $engagement may be over-collected or collected with unintended properties.

If you are manually collecting screen information, it is recommended to disable automaticScreenTracking.

Example

await HackleApp.initialize("YOUR_API_KEY",
    hackleConfig: HackleConfigBuilder()
      .automaticScreenTracking(false)
      .build());