In-app features

Alongside its tracking capabilities, the SDK embeds some features aimed at Contentsquare users such as Snapshot Capture and SDK Logs.

To enable in-app features within your app, you have to first make sure your app is launched in the background. To do so, start it and press the Android home button. Then, follow the appropriate method described as follows.

If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.

If you are using an emulator, you can use the ADB command to enable in-app features.

If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select “Copy this ADB command”.

It will look like this:

adb shell am start -W -a android.intent.action.VIEW -d "cs-{{packageName}}://contentsquare.com?activationKey={{uniqueActivationKey}}\&userId={{userId}}"

If you don’t have access to the Contentsquare platform, you can ask the Contentsquare team to share the link with you.

Contentsquare provides Logging capabilities that allow you to see the raw event data logged by your app in Android Studio or in the Contentsquare platform. Use this for validation purposes during the instrumentation phase of development and can help you discover errors and mistakes in your analytics implementation and confirm that all events are being logged correctly.

By default, almost all logs are disabled. There is only one log that is always visible to notify that the SDK has started:

I/CSLIB: Contentsquare SDK 4.34.1 starting in app: your.application.package

In order to enable all logs, activate in-app features. Logging is directly linked to in-app features state: it starts when in-app features is enabled and stops when you disable in-app features.

To view logs:

1. Plug your Android phone into your computer (or use an emulator)
2. Start the Android Studio app
3. Open the Logcat view and select your phone or emulator
4. Filter logs on CSLIB

To view logs directly on the platform, you can use Log visualizer. Log visualizer is a helper tool to see SDK logs without logging tools. It requires having platform access for your project and enabling in-app features. See the SDK Log Visualizer Help Center Article ↗ for more information.

In order to unlock the full data-visualization capabilities of Contentsquare, the SDK provides a way to capture snapshots of your app screens. These snapshots can only be taken by Contentsquare’s users on their device. They are not captured from your end-users device. It means your Personal Data is safe, as long as you use a test user account.

Snapshots are used in the Zoning Analysis module to look at zone-level metrics (Tap rate, Swipe rate…):

To enable Jetpack Compose support for Zoning, it is necessary to add a new Gradle dependency to your Gradle build file. Make sure to follow the Track screens section.

Invisible overlays are transparent information overlays that do not display any information most of the time. These overlays may lead to issues in the Zoning editor. The screen elements covered by the overlay will display 0 taps. On the Contentsquare SDK side, the gesture recognition assigns the taps to the overlay, that is the target view path (TVP) of the tap differs from the TVP of the covered element in the Zoning editor.

To avoid this issue, you may change the layout of the screen so that the overlay is no longer present. Another option is to mark the overlay using the extension function Modifier.excludeFromGestureRecognition().

/**
 * [Modifier] extension function that provides the facility to exclude a Composable from the gesture recognition.
 */
fun Modifier.excludeFromGestureRecognition(): Modifier

The marked Composable and all of its children will be excluded from the gesture recognition. Thus no gestures will be assigned to this part of the Composable hierarchy anymore.

For example:

@Composable
private fun InfoOverlay() {
    Box(
        modifier = Modifier
            .fillMaxSize()
            .excludeFromGestureRecognition()
    ) {
        // some content that is displayed occasionally
    }
}

When creating a Long Snapshot of a RecyclerView or a lazy Compose list, the contents of the list are scrolled automatically. If individual elements of the list are missing in the resulting snapshot, that is they are invisible, this may be because the elements take too long to render. In such a case, automatic scrolling can be delayed. You must have enabled in-app features:

1. Long press on the snapshot button to open the Contentsquare settings.
2. Move the slider to set the delay for scrolling. The value is displayed in milliseconds.
3. Tap on the arrow back to close the Contentsquare settings.

You can now repeat the snapshot and then check it in the zoning editor.

• The snapshot capture is only supported from Android API 26 (Android Oreo).
• The combination of CoordinatorLayout, AppBarLayout, and RecyclerView is currently not supported.
• ConcatAdapter is currently not supported.
• Lists with different item layouts are not supported.
• Two or more scrollable containers are not supported. Furthermore, horizontal scrollable containers are not supported.
• Snapshots of screens in edge-to-edge / fullscreen mode may contain visual artifacts in Zoning Analysis module, for example from the status and navigation button bar. Although some zoning elements will be visually altered by system bars, creating zones and displaying statistics will still work correctly.
• Some lifecycle events are currently not handled. For example: app in background, device rotation, or fragment change.
• The dark mode is currently not supported.

• The snapshot for Jetpack Compose is not fully supported yet. This also applies to the combination of Compose and WebViews.
• The visual information may not be consistent for snapshots of Jetpack Compose screens. This applies in particular to transparency and visibility.
• Scrollable elements with spacings and paddings may not yet be fully supported. While all elements can be selected as zones in the Zoning editor and statistics will be accurate, visual presentation might be affected by artifacts.
• Android views embedded within scrollable Compose containers are not fully supported. These views can be selected as zones in the Zoning editor, and the statistics will be accurate. However, they will not scroll properly with the rest of the content.
• Sometimes, LazyColumn items may contain more than one direct composable, or no composables at all. This can result in an error during snapshot creation or an invalid snapshot in the Zoning editor. To avoid this, wrap the LazyColumn items with an additional Column wrapper, like this:

  LazyColumn(modifier = Modifier.fillMaxSize()) {
      items(20) { itemIndex ->
          // Wrapping every item with additional Column avoids issues if some
          // items have multiple direct composables, or no composables at all.
          Column {
              when (itemIndex % 3) {
                  0 -> {
                      // Item with 1 direct composable (Row).
                      Row {
                          Text(text = "Sample")
                      }
                  }
                  1 -> {
                      // Item with multiple direct composables (Text, Row).
                      Text(text = "Sample")
                      Row {
                          Text(text = "Sample")
                      }
                  }
                  // No else statement: some items will have no composables at all.
              }
          }
      }
  }