---
title: Session Replay - Capacitor
description: Session Replay implementation and Personal Data masking
lastUpdated: 11 March 2026
source_url:
  html: https://docs.contentsquare.com/en/capacitor/session-replay/
  md: https://docs.contentsquare.com/en/capacitor/session-replay/index.md
---

Session Replay enables replaying real sessions to observe how users interact with your product, by capturing screen content - including text and images - as users navigate your mobile app. For more details, see [Introduction to Session Replay for Apps ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561-Introduction-to-Session-Replay-for-Apps) in the Help Center.

## Starter guide

### Prerequisites

#### Update 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](https://docs.contentsquare.com/en/capacitor/#install-the-sdk) to its latest version.

#### Implement screen tracking

Ensure screen tracking is implemented, since Session Replay collection starts at the first screenview event. See [Track screens](https://docs.contentsquare.com/en/capacitor/track-screens/).

#### Handle User consent

Ensure user consent is handled, especially if you're implementing the SDK for the first time.\
See [Privacy](https://docs.contentsquare.com/en/capacitor/privacy/) section.

#### Session Replay data collection

Data collection settings - such as sampling rate - should be configured in your project parameters, as explained in this [Help Center article ↗](https://support.contentsquare.com/hc/en-us/articles/37271951720721-Data-collection-for-Session-Replay-Apps)

### Configure Session Replay masking

See [Personal Data Masking](#personal-data-masking)

Warning

Always keep sensitive data masked to ensure compliance with privacy regulations and to protect users' personal data.

### Test your setup

#### 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:

1. [Enable in-app features](https://docs.contentsquare.com/en/capacitor/in-app-features/)
2. Open in-app features settings with a long press on the screenshot button
3. Under "Session Replay", toggle "Enable Session Replay" on
4. Kill the app
5. Start app, a new session is starting with Session Replay enabled

##### Android

![](https://docs.contentsquare.com/_astro/android-enable-sr.Bs1TVfWt_Z1IDHPp.webp)

#### 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](#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

![](https://docs.contentsquare.com/_astro/android-get-replay-link.BQJ27mmY_Z2mfm3D.webp)

##### iOS

![](https://docs.contentsquare.com/_astro/ios-get-replay-link.tN1tVH-m_Z1EodDY.webp)

## 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

Warning

If your application contains native screens, see the [iOS](https://docs.contentsquare.com/en/ios/session-replay/#personal-data-masking) and the [Android](https://docs.contentsquare.com/en/android/session-replay/#personal-data-masking) Masking documentation.

Contentsquare never collects the actual text typed into any `<input>` or `<textarea>` field.

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.

Warning

If Session Replay is turned off, the HTML text/content of the page **is not** collected during the session.

### 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.

Note

Always contact your Implementation Manager to check your approach to masking.

#### 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).

Note

Dropdowns are usually coded with the `<select>` element, which is collected by default by Contentsquare. If you show any Personal Data in these elements, you would have to make sure to apply the `data-cs-mask` data attribute.

#### 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.

```javascript
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.

Note

In case of CSS selectors being changed or removed, the masking will be removed as well.

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**:

```javascript
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:

```javascript
{
  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:

```html
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:

```html
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](https://docs.contentsquare.com/en/web/events-handling/) (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).

Warning

Using comments within the HTML is not supported (`{/* MousetestSensitiveStart */}...{/* MousetestSensitiveEnd */}`).

### 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.

Note

In case of CSS selectors being changed or removed, the element will be masked by default.

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:

```javascript
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:

```html
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:

```html
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:

* [Android - Requests are failing](https://docs.contentsquare.com/en/android/troubleshooting/#requests-are-failing)
* [iOS - Requests are failing](https://docs.contentsquare.com/en/ios/troubleshooting/#requests-are-failing)

### 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](https://docs.contentsquare.com/en/ios/how-the-sdk-works/#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.