Contentsquare aggregates user behavior and engagement at the screen level. To do so, it is required to track screen transitions by calling a dedicated API. When the API is called, the SDK logs a screenview event that identifies the new screen with the screen name provided.
If Jetpack Compose is used, 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.
If no recompositions occur, no additional code is needed.
Screen name handlingSection titled Screen name handling
The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side.
Implementation recommendationsSection titled Implementation recommendations
General rulesSection titled General rules
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 screenviewSection titled When to send your first screenview
Most of the events collected by the SDK require you to send a screenview event first so they can be associated to that screen, otherwise they will be discarded. If you need to collect events right from app launch, you should trigger a screenview event right after the SDK has started.
Automatic startSection titled Automatic start
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 :
Manual startSection titled Manual start
If the SDK is started manually, you should send your first screenview right after calling
ActivitiesSection titled Activities
To trigger a custom screenview each time the activity becomes visible, place the call in the
onResume method (XML layouts only).
ViewPagersSection titled ViewPagers
To avoid double tagging on Fragments, make sure to include the call in each ViewPager’s
PopupsSection titled 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
Bottom sheetsSection titled 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 screensSection 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 appSection 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.
How to name screensSection titled How to name screens
As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive.
Separate words with space, dash or underscore charactersSection titled Separate words with space, dash or underscore characters
To generate screen names with more than one word, separate them using spaces, dashes or underscores.
For instance, use
Home & Living - Home Furnishings instead of
for a sub-category in a retail app.
Use screen template/layout namesSection 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 screenSection 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:
State Screen name No trip planned
Home - no trip
Home - trip planned
Trip about to start
Home - upcoming trip
Trip in progress
Home - trip in progress
- Product detail screen of an e-commerce app with different layouts depending on the type of product:
State Screen name Default template
Template with suggested products
Product detail - Suggestions
Template with bundled products
Product detail - Bundle
How to track sessions & screen metadataSection titled How to track sessions & screen metadata
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.
- Product name: “Acme Widget”
- Product color: “red”
- Product price: “$19.99”
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.
- Campaign name: “Summer Sale 2023”
- Variation version: “Version A”