Session Replay

Prerequisites

Screen tracking implemented

As session data collection will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the Capacitor Track screens sections.

Updating to latest SDK version

In order to enable Session Replay in your app and get the most stable version, it is required to upgrade the SDK to its latest version.

If you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the Capacitor Privacy sections.

Testing and Debugging

Enable Session Replay on your device

Since not all sessions are collected (depending on the percentage set in the Contentsquare back office), we have implemented an option to force replay collection on your device for testing and debugging purposes. This option can be enabled from the in-app features settings:

Enable in-app features
Open in-app features settings with a long press on the snapshot button
Under “Session Replay”, toggle “Enable Session Replay” on
Kill the app
Start app, a new session is starting with Session Replay enabled

Android

How do I know if Session Replay is enabled?

There are 2 places where you can check if Session Replay is enabled:

In the logs: The log Session Replay is starting (Android) or Enable Session Replay for Capacitor succeeded (iOS) will confirm that Session Replay is enabled.

In in-app features settings: Below the “Enable “will start at next app start” (see below Access the replay), you will either see:

No replay link available which means Session Replay is not running for the current session
Get Replay link which means Session Replay is running for the current session

Access the replay

The replay can be accessed by tapping on Get replay link button from the in-app features settings: The replay will be available within 5 minutes. Only the “ended screen views” are processed (we know a screenview is ended when we start receiving data for the next screenview). This means that you will be able to replay your session up to the previous screenview if the session is still running.

Android

iOS

Personal Data Masking

The Session Replay feature collects every user interaction within your app. In order 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 and un-masking component.

Masking mechanisms

Sessions will be collected for Session Replay if:

The Session Replay feature has been enabled for your account
The threshold set by the Session Replay Collection Rate is not exceeded.

For the HTML content to be sent, all these conditions must be true:

The user hasn’t opted out.
The session is being tracked.

Session Replay data collection options

If Session Replay is turned on and data collection is active for the session, the HTML content of the page is sent after every pageview (both natural and artificial) and every DOM change (only the updated elements are sent).

Depending on the Session Replay option chosen, the resulting replay will differ and additional masking tasks will have to be carried out.

Clear content with masked Personal Data

With this option enabled, the Tracking Tag performs the following tasks:

The content of <input> elements with type text, email, password, search, tel, url or <input> elements without a type attribute are replaced with bullets before the HTML is sent,
Every figure of <input> elements with type number are replaced by 0,
The content <textarea> elements is replaced with bullets before the HTML is sent,
The content of <script> elements is emptied,
Except for the above, all the HTML content is sent, including <head>,
The content of every element marked with the data attribute data-cs-mask is removed (see below).

Auto-masked content with AAA masking

With this option enabled, the Tracking Tag performs the following tasks:

The content of <input> elements with type text, email, password, search, tel, url or <input> elements without a type are replaced with bullets before the HTML is sent,
Every figure of <input> elements with type number are replaced by 0,
The content <textarea> elements is replaced with bullets before the HTML is sent,
The content of <script> elements is emptied,
The content of every element marked with the data attribute data-cs-mask is removed (see below).
The content of every element marked with the data attribute data-cs-capture is collected and shown unless it falls under the excluded elements listed above (<input>, <textarea>)
Every character of the text content included in the elements sent is replaced by “A”.
Attributes unrelated to layout are Only id, class, style, src, srcset, href, rel, and type are kept.

Selectively mask pages by URL

In case your site displays Personal Data only on a specific set of pages, you can decide to run the Auto-Masking process only on a pre-defined set of pages, so that you won’t have to apply the masking across the whole site.

We currently have two available options:

Mask all pages except: All pages will be masked except the ones defined by a Regex Pattern agreed with your dedicated Implementation Manager.
Unmask all pages except: All pages will be collected with clear content except from the ones defined by a Regex pattern agreed with your dedicated Implementation Manager.

These can only be configured by your dedicated Implementation Manager.

Block data collection for specific pages (Session Replay)

Use the excludeURLforReplay command to block data collection on pages based on their URL.
You might want to use this command for the following reasons:

Some page replays for Session Replay cause performance issues (when the page contains many images or videos, for instance) — you can block these pages until the problem is fixed,
Personal data has been exposed,
You want to exclude whole parts of your website from being collected for Session Replay.

import { ContentsquarePlugin } from '@contentsquare/capacitor-plugin';

ContentsquarePlugin.excludeURLForReplay(URL_REGEX);

Using this command does not block page views for the given page(s) — it only blocks data collection for Session Replay.

Remove content/Personal Data from the collected HTML

There are two methods to remove content from the collected HTML:

Using the Contentsquare Personal Data Selector
Tagging DOM Elements

Personal Data Selector

Each DOM element to be masked is identified thanks to its CSS selector and those selectors are pushed to the API via a JavaScript object. The content of the identified element will be thus removed from the replay.

The following object that contains CSS selectors for text and for attributes should be pushed to the API as follows, before firing the main tag:

import { ContentsquarePlugin } from '@contentsquare/capacitor-plugin';

ContentsquarePlugin.setPIISelectors({PII Object});

The structure of the PII Object is as follows:

PIISelectors: CSS selectors defined here will allow the matching DOM element to be masked by the tag.
Attributes: Using this key, one can remove the defined attributes of the DOM elements from the elements matching the CSS selectors. Note that it is possible to use an array of attribute names as shown in the example above.

Keep in mind that using both PII Selectors and Attributes is optional, meaning you can use either full element selectors, specific attribute selectors or both in the same object:

{
  PIISelectors: [".css-selector, ss-selector"], // DOM elements to be sked
  Attributes: [
      {
          selector: "select#month option, select#year option", // CSS selectors
          attrName: 'id' // Attribute name you want to mask
      },
      {
          selector: ".link-page-7", // CSS selectors
          attrName: ['href','name'] // Array attribute names you want to mask
      }
  ]
};

Tagging DOM elements

To exclude content from being collected, use the data-cs-mask attribute on selected elements:

Content before
<p data-cs-mask>
  emailaddress@sentitivedata.com
</p>
Content after

Their content is removed in the browser before it is sent to Contentsquare:

Content before
<p data-cs-mask>
  emailaddress@sentitivedata.com
</p>
Content after

You can also add the data-cs-mask attribute with JavaScript provided you do it before any pageview is sent.

Events on removed HTML — Events (click, hover, etc.) will still be collected and sent to our servers even if they are targeting removed HTML elements. They will be visible in the application using Live Resources (as named in the platform).

Display content in a fully masked HTML page

There are two methods to display content in a masked HTML page:

Using the Contentsquare Personal Data Selector
Tagging DOM Elements

Personal Data Selector

Each DOM element to be displayed is identified thanks to its CSS selector and those selectors are pushed to the API via a JavaScript object. The content of the identified element will be thus displayed in Session Replay.

The string which contains comma-separated CSS selectors for text and for attributes must be pushed to the Contentsquare API, before firing the main tag, as follows:

import { ContentsquarePlugin } from '@contentsquare/capacitor-plugin';

ContentsquarePlugin.setCapturedElementsSelector('#capture-me, .show-me');

Tagging DOM elements

To display an HTML element in a masked page, add the data-cs-capture attribute to the HTML element:

Sensitive Content before
<p data-cs-capture>
  some piece of text that is not sensitive
</p>
Sensitive Content after

Content that is part of the tagged element is displayed as is:

AAAA AAAA AA
<p data-cs-capture>
  some piece of text that is not sensitive
</p>
AAA AAA AA

It can also be added with JavaScript but, be careful, as attributes must be added before any pageview is sent.

Known limitations

Some fonts are not loaded
SVG assets are not supported
Zoom is not properly handled

Android specific

Some screen titles don’t correspond to the screen currently shown in the player
Ratio of the screen is not correct while the gesture positions are correct on the player
“Loading webviews” and “Webview not tracked” messages sometimes appear in the player
The CSS is sometimes not immediately loaded on a new page

Troubleshooting

Requests are not sent from an Android emulator / iOS simulator

If you struggle to watch a replay collected on an emulator/simulator, it may be due to some network constraints applied on your computer (VPN, company network restrictions, etc.). Check your configuration or use a real device.

See following sections for more information about our endpoints and requests:

Very long session on an Android emulator / iOS simulator

It is important to remember that an app kill does not end a session. See Session definition for more information. If you leave the simulator/emulator running with the app in foreground, the session will not end, even if you are inactive. To better reflect actual end user behavior and avoid unusually long sessions (last hours), put the app in background or kill it.

SR has weird timestamps when using Android / iOS simulator

Some bugs with the timestamps only appear when testing with a simulator/emulator. Test out the Session Replay feature when implementing it with a device in order not to trigger it.

Prerequisites

Screen tracking implemented

Updating to latest SDK version

Reminder about User consent

Testing and Debugging

Enable Session Replay on your device

Android

How do I know if Session Replay is enabled?

Access the replay

Android

iOS

Personal Data Masking

Masking mechanisms

Session Replay data collection options

Clear content with masked Personal Data

Auto-masked content with AAA masking

Selectively mask pages by URL

Block data collection for specific pages (Session Replay)

Remove content/Personal Data from the collected HTML

Personal Data Selector

Tagging DOM elements

Display content in a fully masked HTML page

Personal Data Selector

Tagging DOM elements

Known limitations

Android specific

Troubleshooting

Requests are not sent from an Android emulator / iOS simulator

Very long session on an Android emulator / iOS simulator

SR has weird timestamps when using Android / iOS simulator