Track screens

A newer version of this documentation is available. Switch to the latest version docs.

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.

import com.contentsquare.android.Contentsquare
// Sends Screenview
Contentsquare.send("screen_name")

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

implementation 'com.contentsquare.android:compose:4.24.1'

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

import com.contentsquare.android.Contentsquare
import com.contentsquare.android.compose.analytics.TriggeredOnResume
@Composable
fun MyComposable(data: Data) {
TriggeredOnResume {
Contentsquare.send("screen_name")
}
// ...
}

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

Section titled Implementation recommendations

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

  • When the screen appears
  • When a modal/pop-up is closed and the user is back on the screen
  • When the app is put in the foreground (after an app hide)

When to send your first screenview

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

If the SDK is started automatically, you should send your first screenview when your app’s life cycle begins. For instance, you can send it in your Application onCreate() method:

import android.app.Application;
import com.contentsquare.android.Contentsquare;
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
// Send screenView
Contentsquare.send("Launch screen");
}
}

If the SDK is started manually, you should send your first screenview right after calling start():

Contentsquare.start();
Contentsquare.send("Launch screen");

To trigger a custom screenview each time the activity becomes visible, place the call in the onResume method (XML layouts only).

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

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.

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

Section titled Back navigation and navigation between screens

Make sure that screenview events will be triggered when a user will go to the previous screen. i.e. 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 to catch the back events.

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

Section titled 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_view events are sent, in order not to track a screen which is not actually shown users.

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

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

Use screen template/layout names

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

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, it would be interesting to 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

How to track sessions & screen metadata

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

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