---
title: Track screens - Android
description: Learn how to implement screen tracking in your Android app with CSQ SDK to capture user navigation patterns and screen interactions
lastUpdated: 11 March 2026
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/
  md: https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/track-screens/index.md
---

Contentsquare aggregates user behavior and engagement at the screen level. To achieve this, it is necessary to provide a name for each screen by calling a dedicated screenview API.

Warning

Sessions without at least one screenview will be discarded.

* Kotlin

  ```kotlin
  import com.contentsquare.CSQ


  // Sends Screenview
  CSQ.trackScreenview("screen_name")
  ```

* Java

  ```java
  import com.contentsquare.CSQ;


  // Sends Screenview
  CSQ.trackScreenview("screen_name");
  ```

## Jetpack Compose support

To enable Jetpack Compose support, it is necessary to add a new dependency to your Gradle build file.

* Kotlin

  **build.gradle**

  ```kotlin
  implementation("com.contentsquare.android:sdk-compose:1.5.1")
  ```

* Groovy

  **build.gradle**

  ```groovy
  implementation 'com.contentsquare.android:sdk-compose:1.5.1'
  ```

Attention must be paid to recompositions. The call should be wrapped using `TriggeredOnResume` composable to ensure only one screenview is triggered when a given screen is presented to the user.

* Kotlin

  ```kotlin
  import com.contentsquare.CSQ
  import com.contentsquare.api.compose.screen.TriggeredOnResume


  @Composable
  fun MyScreen() {
    TriggeredOnResume {
      CSQ.trackScreenview("screen_name")
    }
    // ...
  }
  ```

* Java

  ```java
  // Jetpack Compose is primarily designed for Kotlin
  // While it's possible to use Compose with Java, Kotlin is recommended
  import androidx.compose.runtime.Composable;
  import com.contentsquare.CSQ;
  import com.contentsquare.api.compose.screen.TriggeredOnResume;


  public class MyComposeExample {
      @Composable
      public void MyComposable(Data data) {
          TriggeredOnResume.INSTANCE.invoke(() -> {
              CSQ.trackScreenview("screen_name");
              return null; // Required for Java lambda returning Unit in Kotlin
          });
          // ...
      }
  }
  ```

## Screen name handling

The screen name is limited to 2083 characters. However, this limit is not enforced by the SDK, but rather by the Contentsquare servers.

## Implementation recommendations

### General rules

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

* The screen appears on the device
* A modal or pop-up is displayed
* A modal or pop-up is closed, returning the user to the screen
* The app is brought back to the foreground (after being minimized)

### When to send your first screenview

Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started:

* Kotlin

  ```kotlin
  CSQ.start(this)
  CSQ.trackScreenview("Launch screen")
  ```

* Java

  ```java
  CSQ.start(this);
  CSQ.trackScreenview("Launch screen");
  ```

### Activities

To trigger a screenview each time the activity becomes visible, place the call in the `onResume` method (Android view system only).

### ViewPagers

To avoid double tagging on Fragments, make sure to include the call in each ViewPager's `onPageChangeListener` callback.

### Popups

When tracking a popup as an isolated screen, use the API to send a screenview event in `onShow`. To re-trigger a screenview of the current activity when the popup is dismissed, make sure to trigger a screenview event with the original activity screenName on the popup `DismissListener`.

### Bottom sheets

When tracking a bottom sheet as an isolated screen, use the API to send a screenview event on view displayed. On its dismiss, make sure to trigger a screenview event with the original screen name on `BottomSheetBehaviorCallback` state change (Usually when STATE\_HIDDEN) to track the complete cycle.

### Back navigation and navigation between screens

Make sure that screenview events will be triggered when a user will go to the previous screen (example: Home → Profile → Home), it is expected to have a screenview event for the Home screen that might be reached with the back navigation button. Trigger screenview event in a [**custom callback** ↗](https://developer.android.com/guide/navigation/navigation-custom-back) to catch the back events.

### Redirecting the user to another screen (authentication, home) when closing the app/re-opening the app

For some apps, you might want to redirect users whenever they hide your app, for example for security purposes (bank apps, password managers, etc...). If that is the case, pay specific attention to the way Screen name events are sent, in order not to track a screen which is not actually shown users.

## How to name screens

As a general rule, keep the number of distinct screen names under 100. Since these names are used to map your app in Contentsquare, choose names that are clear and comprehensive.

### Separate words with spaces, dashes or underscores

When generating screen names with multiple words, separate them using spaces, dashes, or underscores.

For instance, use `Home & Living - Home Furnishings` instead of ~~`homeLivingHomeFurnishings`~~ for a sub-category in a retail app.

### Screen name limitations

Casing sensitivity

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

```kotlin
CSQ.trackScreenview("ScreenName") // screenname
CSQ.trackScreenview("Screen Name") // screen name
CSQ.trackScreenview("screen_name") // screen_name
CSQ.trackScreenview("screenname") // screenname
```

### Use screen template/layout names

As a general recommendation, use names referring to the screen template/layout rather than referring to the specific content (data). This will help:

* To keep the number of distinct screen names low and therefore make Contentsquare easier to use
* Remove the risk of sending Personal Data to Contentsquare

List of screen types falling into that category: Product detail, Event detail, Conversation/Chat, User profile, and so on.

### 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` |

## How to track sessions & screen metadata

**Custom Variables**

Custom variables are designed to provide additional details about the screenview or user information during end-user engagement. These variables can encompass various aspects, including screen-specific attributes or user-related information, and serve as a means to enhance data collection and analysis.

Example:

* Product name: "Acme Widget"
* Product color: "red"
* Product price: "$19.99"

[Learn how to setup Custom Variables](../track-custom-variables/)

**Dynamic Variables**

Dynamic variables are used to provide additional information on the session, such as the name of a campaign or the version of a variation for an A/B test integration. They can be sent at any time during a session and do not require sending a screenview. Note that dynamic variables should be used only in segments.

Example:

* Campaign name: "Summer Sale 2023"
* Variation version: "Version A"

[Learn how to setup Dynamic Variables](../track-dynamic-variables/)