Set up the extension

This page will guide you to set up Mobile Experience Analytics Extension for Contentsquare Product Analytics.

This will supercharge the Product Analytics platform with:

• Powerful Session Replay
• Heatmaps
• Analysis capabilities of Mobile API Errors and Crashes

This guide assumes that you have already implemented the CSQ SDK for Product Analytics.

1. In Product Analytics, navigate to Account > Manage > Replays & Heatmaps.

1. If this is your first time setting up Session Replay, select the checkbox to accept the terms and conditions.
2. Click Add web or mobile app to launch the setup wizard. There is one configuration per app.
3. Select Mobile as platform.
4. Give your app a name and choose a storage location (US or EU).

1. Set a sampling rate for how many sessions to record.
2. Configure replay settings:
   • App ID: enter the bundle ID of your app (for example, com.companyname.appname).
   • Quality Settings: choose the recording fidelity for Wi-Fi and Cellular connections. The default for both is Medium; keep Cellular equal to or lower than Wi-Fi.
   • User Consent: enable this if your app requires explicit opt-in before recording. See Privacy docs for the opt-in API.

1. Click Save and Continue to finish the wizard.

Add the Contentsquare Network Gradle plugin to the plugins block in both your root-level and app-level Gradle files:

plugins {
   id("com.contentsquare.error.analysis.network") version "1.7.0" apply false
}

plugins {
   id("com.contentsquare.error.analysis.network")
}

plugins {
   id "com.contentsquare.error.analysis.network" version "1.7.0" apply false
}

plugins {
   id "com.contentsquare.error.analysis.network"
}

Once this is done, the SDK running on your app will immediately start collecting the required data to provide Session Replay and Errors / Crashes (if enabled) into the Product Analytics platform.

Error and crash collection is managed separately from the setup wizard. Navigate to Account > Manage > Replays & Heatmaps, click Edit next to your app configuration, then scroll to the relevant section under General Settings:

• Error Capture: toggles for API Errors and Custom Errors.
• Crashes Capture: toggle for Crashes.

Click Save when finished.

The Session Replay feature replays every interaction of your users with your app. To respect the user's right to privacy, the Contentsquare SDK:

• Masks everything by default
• Allows you to control which part of the user interface is collected via our Masking rules

Every single UI element is converted into a highly pixelated image to reach a very low resolution. Text and images will appear very blurry so that the content cannot be identified.

Masking rules can be applied in two ways:

1. Through remote masking configuration in the CSQ Console (for admin users): These configurations are managed directly in the Console and take effect for all sessions as soon as the app is restarted or brought to the foreground See How to customize masking rules from the Data Masking tab ↗ in the Help Center.
2. Using public masking APIs in the SDK (for mobile application developers): These configurations require developer implementation and will be applied only after the mobile app has gone through its release cycle.

Masking rules set via the CSQ Console or the public APIs are applied according to different priorities, as described below. The SDK determines whether a view is masked by evaluating the rules in the order specified below. Once a rule is triggered, the state is set, and subsequent rules are not applied:

Special consideration is needed for text inputs, as the risk of leaking personal data is higher with these elements. As a result, the SDK applies slightly different rules to EditText and Jetpack Compose TextField:

Specifically, default masking and parent masking won't change the masking state of text inputs.

All Android View elements, their subclasses, and Jetpack Compose components are fully masked by default.

Change the default masking state with:

/**
* Sets the default masking state for the Contentsquare's Session Replay features.
*
* @param masked A boolean value indicating whether masking should be enabled (true) or disabled (false).
*/
@JvmStatic
fun setDefaultMasking(masked: Boolean)

/**
* Masks the contents of a specific view.
*
* @param view an instance of [View] to mask.
*/
@JvmStatic
fun mask(view: View)

/**
* Unmasks the contents of a specific view.
*
* @param view an instance of [View] to unmask.
*/
@JvmStatic
fun unmask(view: View)

/**
 * [View] extension function to mask the contents of a view.
 * This extension function can be used as alternative to [CSQ.mask] and [CSQ.unmask].
 *
 * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false) for this view.
 */
fun View.csqMaskContents(enable: Boolean)

/**
 * A composable function that applies masking to Compose UI content.
 *
 * @param enable A boolean value indicating whether masking should be enabled (true) or disabled (false).
 * @param block A composable lambda function representing the content to apply masking condition.
 */
@Composable
fun CsqMask(enable: Boolean, block: @Composable () -> Unit)

CsqMask(true) {
   Text(
      text = "Text"
   )
}

Although the SDK allows masking elements by type for convenience but it isn't the recommended masking mechanism because it impacts all screens of your application.

Use this when you have a specific class for presenting user information or for displaying the user profile picture to make sure it always stays masked, for instance.

/**
* Masks the contents of the view for all instances of a specific [Class] and subclass of a [View].
* This will be applied only for Session Replay feature.
*
* @param type a [Class] object representing the type to be masked.
*/
@JvmStatic
fun mask(type: Class<*>)

/**
* Unmasks the contents of the view for all instances of a specific [Class] and subclass of a [View] for
* Session Replay feature.
*
* @param type a [Class] object representing the type to be unmasked.
*/
@JvmStatic
fun unmask(type: Class<*>)

CsqMask(true) {
   Column {
      Row {
         CsqMask(false) {
            // unmask this `Text` composable
            Text(
               text = "Text",
            )
         }
      }
      Row {
         Text(
            // this `Text` composable will be masked, as it inherits the masking state from the parent
            text = "Text 2",
         )
      }
   }
}

Bottom Sheets

Bottom sheets can be masked or unmasked using the same APIs available for any other view, whether you're working with Android Views or Jetpack Compose. To apply the masking behavior, ensure that you call the appropriate API after the bottom sheet has been created.

AlertDialogs

/**
 * Masks the entire [AlertDialog].
 */
fun AlertDialog.csqMask()

/**
 * Masks the title of the [AlertDialog].
 */
fun AlertDialog.csqMaskTitle()

/**
 * Masks the message of the [AlertDialog].
 */
fun AlertDialog.csqMaskMessage()

/**
 * Masks the positive button of the [AlertDialog].
 */
fun AlertDialog.csqMaskPositiveButton()

/**
 * Masks the negative button of the [AlertDialog].
 */
fun AlertDialog.csqMaskNegativeButton()

/**
 * Unmasks the entire [AlertDialog].
 */
fun AlertDialog.csqUnMask()

/**
 * Unmasks the title of the [AlertDialog].
 */
fun AlertDialog.csqUnMaskTitle()

/**
 * Unmasks the message of the [AlertDialog].
 */
fun AlertDialog.csqUnMaskMessage()

/**
 * Unmasks the positive button of the [AlertDialog].
 */
fun AlertDialog.csqUnMaskPositiveButton()

/**
 * Unmasks the negative button of the [AlertDialog].
 */
fun AlertDialog.csqUnMaskNegativeButton()

AlertDialog(
   icon = {
      Icon(icon, contentDescription = "Example Icon")
   },
   title = {
      Text(text = dialogTitle)
   },
   text = {
      // Mask the dialog text
      CsqMask(true) {
         Text(
            text = dialogText
         )
      }
   },
   onDismissRequest = {
      onDismissRequest()
   },
   confirmButton = {
      TextButton(
         onClick = {
            onConfirmation()
         }
      ) {
         // Unmask the dialog confirm button
         CsqMask(false) {
            Text(
               "Confirm"
            )
         }
      }
   }
)

TimePickerDialog and DatePickerDialog

/**
 * Masks the entire [DatePickerDialog].
 */
fun DatePickerDialog.csqMask()

/**
 * Masks the header of the DatePicker, which typically displays the selected date.
 * This affects the [DatePickerDialog].
 */
fun DatePickerDialog.csqMaskHeader()

/**
 * Masks the calendar view (day picker) of the [DatePickerDialog].
 */
fun DatePickerDialog.csqMaskCalendar()

/**
 * Masks the button panel of the [DatePickerDialog], typically containing "OK" and "Cancel" buttons.
 */
fun DatePickerDialog.csqMaskButtonPanel()

/**
 * Unmasks the entire [DatePickerDialog].
 */
fun DatePickerDialog.csqUnMask()

/**
 * Unmasks the header of the DatePicker.
 * This affects the [DatePickerDialog].
 */
fun DatePickerDialog.csqUnMaskHeader()

/**
 * Unmasks the calendar view (day picker) of the DatePicker.
 * This affects the [DatePickerDialog].
 */
fun DatePickerDialog.csqUnMaskCalendar()

/**
 * Unmasks the button panel of the [DatePickerDialog].
 */
fun DatePickerDialog.csqUnMaskButtonPanel()

/**
 * Masks the entire TimePicker view within the [TimePickerDialog].
 */
fun TimePickerDialog.csqMask()

/**
 * Masks the header of the TimePicker, including the time display and input mode header.
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqMaskHeader()

/**
 * Masks the radial picker (clock face) of the TimePicker.
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqMaskRadialPicker()

/**
 * Masks the input mode view of the TimePicker (keyboard input for time).
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqMaskInputMode()

/**
 * Masks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons.
 */
fun TimePickerDialog.csqMaskButtonPanel()

/**
 * Unmasks the entire TimePicker view within the [TimePickerDialog].
 */
fun TimePickerDialog.csqUnMask()

/**
 * Unmasks the header of the TimePicker, including the time display and input mode header.
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqUnMaskHeader()

/**
 * Unmasks the radial picker (clock face) of the TimePicker.
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqUnMaskRadialPicker()

/**
 * Unmasks the input mode view of the TimePicker (keyboard input for time).
 * This affects the [TimePickerDialog].
 */
fun TimePickerDialog.csqUnMaskInputMode()

/**
 * Unmasks the button panel of the [TimePickerDialog], including positive, negative, and toggle mode buttons.
 */
fun TimePickerDialog.csqUnMaskButtonPanel()

Custom Dialogs

Menu Items

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
        android:id="@+id/action_settings"
        android:orderInCategory="10"
        android:title="@string/action_settings"
        app:showAsAction="never" />
    <item
        android:id="@+id/profile_settings"
        android:orderInCategory="100"
        android:title="Name Placeholder"
        app:showAsAction="never" />
</menu>

The SDK processes masked views first, ensuring that if a view has transparency and is not masked, it will not expose any personal data since masked views have already been processed.

This approach ensures the protection of sensitive information, even in UIs with transparent views.

Masking operation should be performed before the first draw of the view and it should always be called on the UI thread.

At the Activity level, call the masking API methods on the onCreate lifecycle method.

At the Fragment level, call the masking API methods on the onViewCreated lifecycle method.

The SDK doesn't provide a list of what is currently masked, if you need to keep track, you probably will have to write your specific wrapper.

You can call unmask(View view) multiple times without impacting the SDK performance or your app.

You can mask or unmask a Map, that will then be captured as an image in the replay. However, you won't be able to mask or unmask specific elements within the Map.

Masking rules don't apply on Fragments using animations. So to mask this type of Fragment, mask the container view where the Fragment is inserted, rather than masking its content. This ensures that the Fragment content remains masked during transitions.

Additionally, you can unmask some specific views within the Fragment content, by using CSQ.unmask(view: View).

The masking solution relies on the bounding box reported by a view to determine the area that should be masked. In most cases, this approach is sufficient, as the bounding box accurately reflects the view's position and dimensions on the screen.

However, when a view is rotated or scaled, the bounding box no longer represents the view's actual position or size after the transformation.

To prevent any personal data from being leaked, we advise adopting one of the following approaches:

• Mask the Parent View: Apply masking to the parent container of the transformed view. This ensures that the entire area encompassing the rotated or scaled view is covered, regardless of transformations.

• Mask the Entire Window: In case of complex layouts, transformations, or critical scenarios where absolute certainty is required, mask the entire window to guarantee that no personal data is exposed.

These approaches provide the highest level of confidence in preventing personal data leakage while working within the constraints of the current implementation.