---
title: Track screens - Flutter (classic)
description: Track screens with the Contentsquare Flutter SDK
lastUpdated: 07 April 2026
source_url:
  html: https://docs.contentsquare.com/en/flutter/track-screens/
  md: https://docs.contentsquare.com/en/flutter/track-screens/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/).

Contentsquare aggregate user behavior and engagement at the screen level. To leverage our full range of features, you must implement effective screen tracking.

You can set this up:

* [Manually](https://docs.contentsquare.com/en/flutter/track-screens/#track-screens-manually), by calling a dedicated API.
* [Automatically](https://docs.contentsquare.com/en/flutter/track-screens/#track-screens-automatically), by using our observer to track screens based on changes in the navigation stack.

Warning

Sessions without at least one screenview will be discarded.

## Track screens manually

Call the `.send(String)` API when a screen appears to track screens manually. When you call the API, the SDK logs a screenview event which identifies the new screen with the screen name you provided.

```dart
ContentSquare().send('ScreenName');
```

Warning

If you have implement the manual start of the SDK, you need to start the SDK before sending any screen view.

```dart
await Contentsquare().start();
```

Until this is done, no screen tracking will be collected.

### Back navigation handling

Back navigation is not automatically tracked by the SDK. When back navigation occurs the `send` method should be manually invoked with the screen name of the previous screen.

#### Example with a custom navigation observer

```dart
class CustomNavigationObserver extends NavigatorObserver {


  @override
  void didPop(Route route, Route? previousRoute) {
    ...
    final previousScreenName = // get the previous screen name
    Contentsquare().send(previousScreenName);
    ...
  }


}
```

### Screen name handling

The screen name length is not limited on the SDK side. However, it's important to there is a limit of 2083 characters on the server side. Ensure that screen names do not exceed this limit to prevent any issues with data transmission and processing.

### Handling Screen Views When App Returns from Background

The Contentsquare SDK automatically triggers a screen view when the app is moved to the background and subsequently brought back to the foreground. This occurs provided that a screen view with a screen name has been triggered previously. In such cases, the SDK will use the last screen name that was set.

### Implementation recommendations

From a functional standpoint, we expect a screenview to be sent:

* When the screen becomes visible
* When a modal or pop-up is closed, returning the user to the screen
* When a route is popped, returning the user to the screen

Achieving this can be facilitated through a [NavigatorObserver ↗](https://api.flutter.dev/flutter/widgets/NavigatorObserver-class.html). This observer can be used to listen to route changes and send screenviews accordingly.

### How to name screens

As a general rule, aim to keep distinct screen names under 100 characters. Choose names that provide a comprehensive understanding of the screen's content or purpose. This will help you to identify the screen in the Contentsquare interface.

Tip

We advise against relying on the `runtimeType` of the class, as in the release version, the class name may be obfuscated, rendering the name meaningless.

#### Separate words with space, dash or underscore characters

If you want to create screen names with multiple words, it's best to separate them using spaces, dashes, or underscores. Contentsquare will handle the formatting automatically.

**Example:** For a sub-category list of a retail app, use `Home and Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~.

### Screen name limitations

Casing sensitivity

Screen names are not case sensitive and will appear in lowercase on the Contentsquare platform.

```dart
Contentsquare().send('ScreenName') // screenname
Contentsquare().send('Screen Name') // screen name
Contentsquare().send('screen_name') // screen_name
Contentsquare().send('screenname') // screenname
```

#### Use screen template/layout names

As a general guideline, opt for names that describe the screen template or layout rather than focusing on specific content (data). This approach will minimize the number of unique screen names, making Contentsquare easier to use and reducing the potential for Personal Data transmission.

Examples of screen types falling into this category include Product Detail, Event Detail, Conversation/Chat, and User Profile.

### Screens with multiple states/layouts

Screens can have different layouts or states depending on the user context. In this case, append its value to the screen name.

**Home screen**

| State | Screen name |
| - | - |
| App landing layout | `Home` |
| Women products layout | `Home - Women` |
| Men products layout | `Home - Men` |
| Sales layout | `Home - Sales` |

**Product Detail screen (PDP)**

| State | Screen name |
| - | - |
| Users on a Top for Women PDP | `PDP - Clothing - Women - Tops` |
| Users on a Microwave PDP | `PDP - Kitchenware - Electrics - Microwave` |
| Users on a Hotel details screen | `PDP - Holiday type - Season - Board` |

**User account screen**

| State | Screen name |
| - | - |
| Overview | `My Account - Dashboard` |
| Order history | `My Account - Order history` |
| Returns | `My Account - Returns` |

**Search screen**

| State | Screen name |
| - | - |
| Search | `Search` |
| Search results for "Skincare" products | `Search - Skincare` |
| Search results error screen | `Search - Error` |

**Cart screen**

| State | Screen name |
| - | - |
| Empty cart | `Cart - Empty` |
| Items have been added to the cart | `Cart - Populated` |
| Issues with availability or pricing | `Cart - Error` |

**Checkout screen**

| State | Screen name |
| - | - |
| User provides name, surname, and date of birth | `Checkout - User Details` |
| User provides shipping address | `Checkout - Shipping Details` |
| User inputs their credit card information | `Checkout - Payment` |

## Track screens automatically

Automatic screen view tracking can be done using the `ContentsquareNavigatorObserver`. This will observe the navigation stack of the application and log screen events accordingly.

This observer can be attached to any `WidgetApp` (like `MaterialApp`, `CupertinoApp`) or to a `RouterConfig`

* WidgetApp

  ```dart
  MaterialApp(
    navigatorObservers: [ContentsquareNavigatorObserver()],
  );


  CupertinoApp(
    navigatorObservers: [ContentsquareNavigatorObserver()],
  );


  WidgetsApp(
    navigatorObservers: [ContentsquareNavigatorObserver()],
  );
  ```

* RouterConfig

  ```dart
  MaterialApp.router(
    routerConfig: GoRouter(
      observers: [ContentsquareNavigatorObserver()],
    ),
  );
  ```

Warning

To ensure effective results, make sure that each [Route ↗](https://api.flutter.dev/flutter/widgets/Route-class.html) is properly named

### Configuration

The `ContentsquareNavigatorObserver` can be configured with the following arguments:

#### ShouldTrack

An optional callback function that determines whether a specific route should be tracked. The function takes a `Route` as input and returns a `bool`.

Use this function to selectively exclude certain routes from automatic tracking by returning false for those routes.

By default, all routes are tracked.

```dart
ContentsquareNavigatorObserver(
  shouldTrack: (route) {
    // Exclude /myRoute from tracking
    if (route.settings.name == '/myRoute') return false;
    return true;
  },
)
```

#### ScreenNameProvider

An optional callback function used to customize the screen name for a given route. The function takes a `Route` as input and returns a `String` representing the desired screen name.

Use this function to define custom screen names for specific routes.

By default, the route's name is used if available; otherwise, the route type will be used.

```dart
ContentsquareNavigatorObserver(
  screenNameProvider: (route) {
    final screenName = _formatScreenName(route.settings.name);
    return screenName;
  },
)
```

#### CustomVarsProvider

An optional callback function used to provide a list of custom variables for a specific route. The function takes a `Route` as input and returns a `List<CustomVar>`.

Use this function to attach custom variables to specific routes for tracking purposes.

```dart
ContentsquareNavigatorObserver(
  customVarsProvider: (route) {
    final routeName = route.settings.name;
    final productPageRegex = RegExp(r'/product/(\d)+');


    // In this example, a product ID is extracted from the route name.
    // For a route like "/product/1234", the value "1234" will be set as a customVar.
    if (routeName != null && productPageRegex.hasMatch(routeName)) {
      final productId = productPageRegex.firstMatch(routeName)?.group(1);
      if (productId != null) {
        return [
          CustomVar(index: 1, name: 'productId', value: productId),
        ];
      }
    }
    return [];
  },
)
```

### Troubleshooting

#### Tab bar

TabBar views are commonly tracked as individual screens. However, most TabBar implementations push the route to the navigation stack only during initialization, which can make it challenging to properly track navigation events for each tab change.

To support TabBar tracking correctly, additional configuration may be necessary.

For example, when using AutoTabsRouter from the AutoRoute package, the default behavior does not track tab changes automatically. In this case, combining an AutoRouteObserver with the manual tracking API is required to ensure each tab is tracked as a distinct screen.

```dart
class TabRouteObserver extends AutoRouteObserver {
  @override
  void didInitTabRoute(TabPageRoute route, TabPageRoute? previousRoute) {
    Contentsquare().send(route.name);
  }


  @override
  void didChangeTabRoute(TabPageRoute route, TabPageRoute previousRoute) {
    Contentsquare().send(route.name);
  }


  @override
  void didPop(Route route, Route? previousRoute) {
    final routeName = previousRoute?.settings.name;
    if (routeName == null) return;


    if (_tabRouteNames.contains(routeName)) {
      Contentsquare().send(routeName);
    }
  }
}


[...]


MaterialApp(
  navigatorObservers: [
    ContentsquareNavigatorObserver(),
    TabRouteObserver(),
  ],
);
```

#### PageBuilder

If you use a `pageBuilder` in your routes, make sure to set the page `.name`.

Example using GoRoute:

```dart
GoRoute(
  path: 'checkout',
  name: 'Checkout Screen',
  pageBuilder: (context, state) => MaterialPage(


    name: 'Checkout Screen',
    key: ValueKey(state.pathParameters),
    fullscreenDialog: true,
    child: const CheckoutScreen(),
  ),
),
```