> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/development-guide/flutter/event-tracking/flutter-track-screen.md).

# Screen Tracking

{% hint style="info" %}
For screen navigation in Flutter, refer to the Flutter developer documentation below.

* [Flutter Navigation & Routing](https://docs.flutter.dev/ui/navigation)
* [Navigator](https://api.flutter.dev/flutter/widgets/Navigator-class.html)
* [RouteObserver](https://api.flutter.dev/flutter/widgets/RouteObserver-class.html)
  {% endhint %}

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

{% hint style="info" %}
This feature is supported in Flutter SDK 2.28.0 and above.
{% endhint %}

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.

<table><thead><tr><th width="150">Parameter</th><th width="120">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td><code>string</code></td><td>Required</td><td>The name of the current screen.</td></tr><tr><td>className</td><td><code>string</code></td><td>Required</td><td>If you do not need a separate class name, enter the same value as name.</td></tr></tbody></table>

{% hint style="warning" %}
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.
  {% endhint %}

#### Example

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

```dart
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.

<table><thead><tr><th width="150">Category</th><th width="120">Type</th><th>Constraints</th></tr></thead><tbody><tr><td>Property Key (key)</td><td><code>string</code></td><td><p>Maximum 128 characters.</p><p>Case-insensitive. For example, amount and AMOUNT are treated as the same key.</p></td></tr><tr><td>Property Value (value)</td><td><code>boolean</code>, <code>string</code>, <code>number</code>, <code>array</code></td><td><p>For string type, maximum 1024 characters.</p><p>For number type, up to 15 integer digits and up to 6 decimal places are supported.</p></td></tr></tbody></table>

#### Example

```dart
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.

{% hint style="danger" %}
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`.**
{% endhint %}

#### Example

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/en/development-guide/flutter/event-tracking/flutter-track-screen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.