Track screens

Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it’s necessary to track screen transitions by calling a dedicated API. When this API is called, the SDK logs a screenview event which identifies the new screen with the provided screen name.


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

Section titled Example with a custom navigation observer
class CustomNavigationObserver extends NavigatorObserver {
void didPop(Route route, Route? previousRoute) {
final previousScreenName = // get the previous screen name

The screen name length is not limited on the SDK side. However, it’s important to note that 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

Section titled 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

Section titled 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. This observer can be used to listen to route changes and send screenviews accordingly.

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 easily identify the screen in the Contentsquare interface.

Separate words with space, dash or underscore characters

Section titled 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 & Living - Home Furnishings instead of homeLivingHomeFurnishings.

Use screen template/layout names

Section titled 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.

Multiple layouts/states for one screen

Section titled Multiple layouts/states for one screen

In some cases, there will be screen that can have different layouts/states depending on the user context. In this situation, you could append the layout/state value to the screen name. Examples:

  • Home screen of a travel app adapting its layout on the user context:
StateScreen name
No trip plannedHome - no trip
Trip plannedHome - trip planned
Trip about to startHome - upcoming trip
Trip in progressHome - trip in progress
  • Product detail screen of an e-commerce app with different layouts depending on the type of product:
StateScreen name
Default templateProduct detail
Template with suggested productsProduct detail - Suggestions
Template with bundled productsProduct detail - Bundle