Track screens

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 screen_view event that identifies the new screen with the screen name provided.

import ContentsquareModule

Contentsquare.send(screenViewWithName: String, cvars: [CustomVar] = [])

@import ContentsquareModule;

[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull)];
// or
[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull) cvars:(NSArray<CustomVar *> * _Nonnull)]; // To add custom variables to screen tracking

The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side.

The SDK triggers a screenview automatically after the app is put in background and foreground, as long as a screenview with a screen name has been triggered previously. It will use the last screen name set.

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

• Right after the SDK has started
• 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)

We advise you to take a look at our reference implementations of screenviews in our sample app. Learning from them is the best way to make sure your implementations are correct. Regardless, here is some general advice.

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.

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 application:didFinishLaunchingWithOptions: of your UIApplicationDelegate if you are using UIKit, or in the init() of your App struct if you are using SwiftUI:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...
    Contentsquare.send(screenViewWithName: "Launch screen")
    // ...
    return true
}

@main
struct MyApp: App {

    init() {
        // ...
        Contentsquare.send(screenViewWithName: "Launch screen")
        // ...
    }

}

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

Contentsquare.start()
Contentsquare.send(screenViewWithName: "Launch screen")

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)

import ContentsquareModule

var body: some View {
    Text("My first screen")
        .foregroundColor(Color.blue)
    .onAppear() {
        Contentsquare.send(screenViewWithName: "First screenView")
    }
}

Be careful when tagging screens with paged ScrollViews: if you want to create a screenview event whenever the user changes the page, do so in UIScrollViewDelegate’s scrollViewDidEndDecelerating(_ scrollView: UIScrollView) function. Make sure that you do not trigger a double tag when the screen appears, or when you come back to the screen after the app being hidden. Also make sure not to send a screenview when the user slightly interacts with a page, but without really changing pages.

When dealing with popups and modals, if you are having issues triggering a screenview event for the underlying view when the modal closes we have the following advice. You could overcome this issue by using a delegate pattern, and setting the underlying screen as the modal’s delegate. The modal would call some delegate method when it is dismissed. The underlying screen would implement that method, where it would make the screenview.

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. Normally, if you send your screenviews in viewWillAppear, this should work fine.

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

When your application returns from the background to the foreground, the SDK automatically logs a screenview with the title of the last logged screenview, so you don’t have to handle this transition yourself.

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.

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 homeLivingHomeFurnishings for a sub-category in a retail app.

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…

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
  Trip planned	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	Product detail
  Template with suggested products	Product detail - Suggestions
  Template with bundled products	Product detail - Bundle