---
title: Tag API reference - Web
description: Tag commands reference including signature, parameter descriptions, and examples
lastUpdated: 07 April 2026
source_url:
  html: https://docs.contentsquare.com/en/web/command-reference/
  md: https://docs.contentsquare.com/en/web/command-reference/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

Tag commands reference including signature, parameter descriptions, and examples.

Which commands are available in my project?

Contentsquare use [tree shaking ↗](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) techniques to optimize the Tag bundle size for every project. Specific commands can be unavailable when:

* You haven't subscribed to the specified paying option or module
* You are [self-hosted](https://docs.contentsquare.com/en/web/#self-hosting) and do not use a recent version of the Tag

## About this page

### iFrames

When iframe tracking is enabled (`CS_CONF.iframesTracking = 1`), commands used in iframes or nested iframes that load a tag are sent to the top window tag which processes them like any other command.

For example, using `window._uxa.push(["trackPageview", IFRAME_PATH]);` will trigger an artificial pageview in the top window.

Commands supported in iframes while iframe tracking is enabled are specified with iframe.

### Webview

Some commands can be run in webviews when webview tracking is enabled. This requires both `CS_CONF.webviewsTrackingEnabled = true` and `_uxa.push(["setOption", "isWebView", "true"])`.

Commands that support webviews are marked with webview.

## Pageview

The Tag can send 3 types of pageview:

* **Natural** pageview: sent when the tracking tag initializes during the initial browser load. This is the standard trigger for traditional multi-page websites.
* **Artificial** pageview: triggered via a manual command. This is essential for Single-Page Applications (SPAs), where the browser does not perform a full refresh as the user navigates between different states or views.
* **Renewal** pageview: occurs when a visitor re-engages with a page after their previous session has expired. Since every session starts with a pageview, the system generates a renewal pageview to maintain session integrity without requiring a URL change.

### `trackPageview`

iframe | webview | **Added in:** `1.1.0`

Send an artificial pageview.

```javascript
window._uxa.push(["trackPageview", path, options]);
```

If run before the loading of the tag, the command will behave as [`setPath`](#setpath).

[Tag Configurator Template: Artificial Pageview ](https://support.contentsquare.com/hc/en-us/articles/37271878716433-CSTC-Template-Artificial-Pageview)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### path   string (optional, <= 255 chars)  

  The URL pathname to send. If not set, the current document `href` attribute is used instead.

* #### options   object (optional)  

  Path options

  * #### options.decodeURI   boolean  

    Single attempt to decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.decodeURIDeep   boolean  

    Up to 10 attempts to fully decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.lifespan   integer or string  

    Specify the lifespan of the overridden path. If not set, the overridden path will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after this pageview). Possible integer values: `2`.

### `setPath`

iframe | **Added in:** `2.0.0`

Override the path to send within a pageview.

```javascript
window._uxa.push(["setPath", path, options]);
```

#### Parameters

* #### path   string  

  The path to send in place of the current URL pathname.

* #### options   object (optional)  

  Path options

  * #### options.decodeURI   boolean  

    Single attempt to decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.decodeURIDeep   boolean  

    Up to 10 attempts to fully decode the provided `path` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.lifespan   integer or string  

    Specify the lifespan of the overridden path. If not set, the overridden path will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after upcoming pageview). Possible integer values: `2`.

#### Examples

##### Collect URL with custom decoded path

URL is `https://www.company.es/specials/campañas-y-ofertas`.

```javascript
window._uxa.push(["setPath", window.location.href, { decodeURI: true }]);
```

Using `decodeURI`, the URL in the next pageview request is collected without encoding:

```text
https://www.company.es/specials/campañas-y-ofertas
```

instead of:

```text
https://www.company.es/specials/campa%C3%B1as-y-ofertas
```

### `setQuery`

iframe | **Added in:** `7.16.0`

Replace a URL query string containing personal data with a masked one.

```javascript
window._uxa.push(["setQuery", queryString, options]);
```

#### Parameters

* #### queryString   string  

  Masked query string.

* #### options   object (optional)  

  Query string options

  * #### options.decodeURI   boolean  

    Single attempt to decode the provided `queryString` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.decodeURIDeep   boolean  

    Up to 10 attempts to fully decode the provided `queryString` using the [`decodeURI` ↗](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) native API. Since 13.97.0.

  * #### options.lifespan   integer or string  

    Specify the lifespan of the overridden query. If not set, the overridden query will persist all along the user session. Possible string values: `onNextPageviewOnly` (reset after upcoming pageview). Possible integer values: `2`.

#### Examples

##### Collect URL with custom decoded query string

URL is `https://www.company.es/specials/ofertas?code=mañanas2024`.

```javascript
window._uxa.push(["setQuery", window.location.search + "&cookies-popin=true", { decodeURI: true }]);
```

Using `decodeURI`, the query string URL in the next pageview request is collected without encoding:

```text
https://www.company.es/specials/ofertas?code=mañanas2024&cookies-popin=true
```

instead of:

```text
https://www.company.es/specials/ofertas?code=ma%C3%B1anas2024&cookies-popin=true
```

### `referrer:maskUrl`

iframe | **Added in:** `11.53.0`

Allows to change the referrer URL (`dr` query parameter) that is sent in the next pageview request. The command can be called multiple times to mask different URL patterns.

```javascript
window._uxa.push(["referrer:maskUrl", url]);
```

#### Parameters

* #### url   string  

  URL containing parameters prefixed with a colon for masking purposes.

#### Examples

The referrer URL to be sent is:

```text
https://web.com/users/123456/products/ABCDEF
```

By calling `referrer:maskUrl` with this URL:

```javascript
window._uxa.push(["referrer:maskUrl", "https://web.com/users/:USER_ID/products/:PRODUCT_ID"]);
```

The referrer URL that is sent becomes:

```text
https://web.com/users/CS_ANONYMIZED_USER_ID/products/CS_ANONYMIZED_PRODUCT_ID
```

### `referrer:keepQueryString`

iframe | **Added in:** `11.53.0`

Reverts the action of [`referrer:removeQueryString`](#referrerremovequerystring) for the next pageview.

```javascript
window._uxa.push(["referrer:removeQueryString"]);
```

#### Examples

The referrer URL to be sent is:

```text
https://hello?withQueryString=true
```

`referrer:keepQueryString` will keep the query string if `referrer:removeQueryString` was used:

```javascript
window._uxa.push(["referrer:removeQueryString"]);
// Referrer URL will be https://hello?


window._uxa.push(["referrer:keepQueryString"]);
// Referrer URL will be https://hello?withQueryString=true
```

#### Parameters

* No parameters.

### `referrer:removeQueryString`

iframe | **Added in:** `11.53.0`

Remove all characters in the query string.

```javascript
window._uxa.push(["referrer:removeQueryString"]);
```

#### Parameters

* No parameters.

#### Examples

The referrer URL to be sent is:

```text
https://hello?withQueryString=true
```

By calling `referrer:removeQueryString`:

```javascript
window._uxa.push(["referrer:removeQueryString"]);
```

The referrer URL becomes:

```text
https://hello?
```

### `setCustomVariable`

iframe | **Added in:** `1.1.0`

Define a custom variable to add meta information to pageviews about the page, user, or the session.

```javascript
window._uxa.push(["setCustomVariable", index, name, value, scope]);
```

A custom var can be deleted by calling the command with an empty string value. The index parameter must match the custom var to delete. If a custom var already exists with a given index, the new name and value will override the old one.

[Tag Configurator Template: Custom Variable ](https://support.contentsquare.com/hc/en-us/articles/37271895488401-CSTC-Template-Custom-Variable)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### index   positive integer  

  Variable index (between 1 and 20).

* #### name   string (<= 512 chars)  

  Variable name.

* #### value   string (<= 255 chars)  

  Variable value.

* #### scope   string or integer (optional)  

  Variable scope. If not set, defaults to visit and page.

  Possible string values: `visit`, `page`, or `nextPageOnly`. Possible integer values: `2`, `3`, or `4`.

#### Examples

##### Setting a custom variable with the scope `visit` at index 5

```javascript
window._uxa.push(["setCustomVariable", 5, "cname", "cvalue", "visit"]);
```

##### Setting and deleting custom variables with specific scopes

Setting a custom var in both scopes (visit + page) at index 6 and named `cname` value `cvalue`:

```javascript
window._uxa.push(["setCustomVariable", 6, "cname", "cvalue"]);
```

To delete the custom variable:

```javascript
window._uxa.push(["setCustomVariable", 6, "cname", "", 2]); // from scope visit
window._uxa.push(["setCustomVariable", 6, "cname", "", 3]); // from scope page
window._uxa.push(["setCustomVariable", 6, "cname", ""]); // from both scopes by passing no value
```

##### Setting a custom variable with the scope `nextPageOnly`

```javascript
window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", "nextPageOnly"]);
// or
window._uxa.push(["setCustomVariable", 6, "cname", "cvalue", "4"]);
```

Attach and send the custom variable to an specific artificial pageview:

```javascript
window._uxa.push(["trackPageview", "/a-path"]);
```

After sending another artificial pageview:

```javascript
window._uxa.push(["trackPageview", "/another-path"]);
```

The custom variable is automatically deleted.

### `hidePageTitle`

iframe | Product Analytics | **Added in:** `15.10.0`

Replace the page title by `****` in the next pageview or in all the next pageviews.

```javascript
window._uxa.push(["hidePageTitle", scope]);
```

#### Parameters

* #### scope   string  

  When `scope` equals to `onNextPageviewOnly`, the command only affects the next pageview. Otherwise, it affects all subsequent pageviews.

#### Examples

Consider the following HTML page:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Order #12345 for Jane Smith - Retail Store</title>
  </head>
  <body>
    ...
  </body>
</html>
```

Calling `window._uxa.push(["hidePageTitle"]);` replaces "Order #12345 for Jane Smith - Retail Store" by `****` on all the next pageviews, until the tag is reloaded or if the `resetHidePageTitle` command is run.

### `resetHidePageTitle`

iframe | Product Analytics | **Added in:** `15.10.0`

Reverts the action of [`hidePageTitle`](#hidepagetitle) for the next pageviews.

```javascript
window._uxa.push(["resetHidePageTitle"]);
```

#### Parameters

* No parameters.

## eCommerce

A transaction should be sent by implementation to track information about visitors transactions on the website.

To send a transaction, use these commands in the following order:

1. [`ec:transaction:create`](#ectransactioncreate) to create a transaction which can contain items
2. [`ec:transaction:items:add`](#ectransactionitemsadd) to add an item to the previously created transaction (multiple items can be added by calling this command multiple times)
3. [`ec:transaction:send`](#ectransactionsend) to send the previously created transaction containing all the items

### `ec:transaction:create`

iframe | webview | **Added in:** `11.5.0`

Create transactions before adding items and sending them to Contentsquare.

```javascript
window._uxa.push([
  "ec:transaction:create",
  {
    id: TRANSACTION_ID,
    revenue: REVENUE_AMOUNT,
    currency: CODE
  },
]);
```

#### Parameters

* #### id   string  

  Transaction ID.

* #### revenue   integer or string  

  Total cost of the transaction.

* #### currency   string (optional, <= 10 characters)  

  Currency value. When no currency is supplied, the currency used in the one from the Contentsquare project settings.

#### Examples

##### Creating a transaction in euros

```javascript
window._uxa = window._uxa || [];


window._uxa.push([
  "ec:transaction:create",
  {
    id: "037333583343",
    revenue: 280,
    currency: "EUR"
  },
]);


window._uxa.push([
  "ec:transaction:items:add",
  {
    id: "037333583343",
    name: "Men's Tree Dasher 2",
    sku: "AA000QM080",
    category: "Shoes",
    price: 140,
    quantity: 2
  },
]);


window._uxa.push(["ec:transaction:send"]);
```

### `ec:transaction:items:add`

iframe | webview | **Added in:** `11.10.0`

Add item to a transaction created with [`ec:transaction:create`](#ectransactioncreate).

```javascript
window._uxa.push([
  "ec:transaction:items:add",
  {
    id: TRANSACTION_ID,
    name: ITEM_NAME,
    price: ITEM_AMOUNT,
    quantity: ITEM_QUANTITY,
    sku: ITEM_SKU_CODE,
    category: ITEM_CATEGORY,
    merchant: MERCHANT_NAME
  },
]);
```

#### Parameters

* #### id   string  

  The Transaction ID.

* #### name   string  

  Item name.

* #### price   float  

  Item price.

* #### quantity   integer  

  Number of items.

* #### sku   string (optional)  

  A valid Stock Keeping Unit (SKU) code.

* #### category   string (optional)  

  Item category.

* #### merchant   string (optional)  

  The merchant name.

#### Examples

##### Adding two items to a transaction

```javascript
window._uxa = window._uxa || [];


window._uxa.push([
  "ec:transaction:create",
  {
    id: "037333583343",
    revenue: 280,
    currency: "EUR"
  },
]);


window._uxa.push([
  "ec:transaction:items:add",
  {
    id: "037333583343",
    name: "Men's Tree Dasher 2",
    sku: "AA000QM080",
    category: "Shoes",
    price: 140,
    quantity: 2
  },
]);


window._uxa.push(["ec:transaction:send"]);
```

### `ec:transaction:send`

iframe | webview | **Added in:** `10.5.0`

Send a transaction containing items added with `ec:transaction:items:add` to later associate a user's session with their purchases.

This command extends the session.

```javascript
window._uxa.push(["ec:transaction:send"]);
```

#### Parameters

* No parameters.

#### Examples

##### Sending a transaction with two items

```javascript
window._uxa = window._uxa || [];


window._uxa.push([
  "ec:transaction:create",
  {
    id: "037333583343",
    revenue: 280,
    currency: "EUR"
  },
]);


window._uxa.push([
  "ec:transaction:items:add",
  {
    id: "037333583343",
    name: "Men's Tree Dasher 2",
    sku: "AA000QM080",
    category: "Shoes",
    price: 140,
    quantity: 2
  },
]);


window._uxa.push(["ec:transaction:send"]);
```

### `ec:cart:add`

iframe | **Added in:** `10.5.0`

Register an add to cart event.

This command extends the session.

```javascript
window._uxa.push([
  "ec:cart:add",
  {
    merchant: MERCHANT_NAME,
    sku: SKU_CODE
  },
]);
```

#### Parameters

* #### merchant   string (optional)  

  The merchant name.

* #### sku   string (optional)  

  A valid Stock Keeping Unit (SKU) code.

Note

Either `merchant` or `sku` is required.

#### Examples

##### Sending an add to cart event (Merchandising customers)

```javascript
window._uxa = window._uxa || [];
window._uxa.push([
  "ec:cart:add",
  {
    merchant: "Pixel patterns",
    sku: "DC126O0FX-L11"
  },
]);
```

## Session

By default, a Tag session ends 30 minutes after the last event. These commands allow you to manage session behavior.

### `extendSession`

iframe | **Added in:** `9.7.0`

Extend session duration.

```javascript
window._uxa.push(["extendSession"]);
```

This command automatically extends a session until:

* The session duration reaches 4h00
* A new pageview (natural or artificial) is triggered

To achieve the extension of the session, it will periodically, with a period of 29 minutes:

* Update the session cookie [`cs_s`](https://docs.contentsquare.com/en/web/cookies/#_cs_s) and add 29 minutes.
* Send a dynamic variable `session_expiry_update:Counter` where the counter begins with the value 1 and is incremented (+1) after each call.

#### Parameters

* No parameters.

Commands extending the session

The following commands also extend the session duration:

* [identify](#identify)
* [addUserProperties](#adduserproperties)
* [ec:transaction:send](#ectransactionsend)
* [ec:cart:add](#eccartadd)

### `optout`

iframe | webview | **Added in:** `7.12.0`

Opt out the current user from data collection.

```javascript
window._uxa.push(["optout"]);
```

#### Parameters

* No parameters.

### `session:start:newVisitor`

iframe | **Added in:** `13.29.0`

Start a new visitor and a new session. Running the command generates a new pageview.

```javascript
window._uxa.push(["session:start:newVisitor"]);
```

#### Parameters

* No parameters.

### `session:clear:visitor`

iframe | **Added in:** `13.39.0`

Clear all data linked to previous visitors.

```javascript
window._uxa.push(["session:clear:visitor"]);
```

Warning

The command must be called before the Tag is loaded.

#### Parameters

* No parameters.

## Dynamic variables

Dynamic variables allow you to send key-value pairs that can be used for segmentation and analysis. Unlike custom variables which are attached to pageviews, dynamic variables are sent immediately when the command is called.

Calling [`trackDynamicVariable`](#trackdynamicvariable) multiple times in the same tick will batch the dynamic variables into a single request.

### `trackDynamicVariable`

iframe | webview | **Added in:** `5.19.0`

Send a dynamic variable.

```javascript
window._uxa.push(["trackDynamicVariable", { DYNAMIC_VARIABLE }]);
```

[Tag Configurator Template: Dynamic Variable ](https://support.contentsquare.com/hc/en-us/articles/37271814927633-CSTC-Template-Dynamic-Variable)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### DYNAMIC\_VARIABLE   object  

  The dynamic variable

  * #### key   string (<= 512 chars)  

    Dynamic variable key

  * #### value   number or string (<=255 chars)  

    Dynamic variable value

#### Examples

##### Sending dynamic variables for A/B testing campaigns

**First user**

```javascript
window._uxa = window._uxa || [];
window._uxa.push([
  "trackDynamicVariable",
  {
    key: "AB_ABT_Label_Best_Price_PC",
    value: "With best price"
  },
]);
window._uxa.push([
  "trackDynamicVariable",
  {
    key: "AB_ABT_Product_Show_Customer_Ratings",
    value: "Variation 1"
  },
]);
```

**Second user**

```javascript
window._uxa = window._uxa || [];
window._uxa.push([
  "trackDynamicVariable",
  {
    key: "AB_ABT_Label_Best_Price_PC",
    value: "Standard"
  },
]);
window._uxa.push([
  "trackDynamicVariable",
  {
    key: "AB_ABT_Product_Show_Customer_Ratings",
    value: "Variation 2"
  },
]);
```

## Page events

Page events allow you to track specific actions or states on a page. Once the command is called, a request is sent to the Contentsquare backend. If the session is collected, the page event is also sent to the Session Replay pipeline.

### `trackPageEvent`

iframe | **Added in:** `9.5.0`

Track a page event.

```javascript
window._uxa.push(["trackPageEvent", eventName]);
```

[Tag Configurator Template: Page Event ](https://support.contentsquare.com/hc/en-us/articles/37271705463185-CSTC-Template-Page-Event)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### eventName   string (<= 255 chars)  

  The name of the event to collect.

#### Examples

##### Collect when visitors save a property add for later consultation

```javascript
window._uxa = window._uxa || [];
window._uxa.push(["trackPageEvent", "SubscribedToPropertyButtonClick"]);
```

##### Collect user identifiers for Session Replays

**Added in:** `10.17.0`

```javascript
window._uxa = window._uxa || [];
window._uxa.push(["trackPageEvent", "@user-identifier@" + accountID]);
```

See [User Identifier](https://docs.contentsquare.com/en/web/personal-data-handling/#user-identifier).

## Custom events

### `trackEvent`

**Added in:** `15.116.0`

Required configuration

* `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap`

Track a custom event.

```javascript
const event = {
  name: "purchase",
  properties: { dollars: 50, items: ["socks", "shoes", "shirt"] },
};


window._uxa.push(["trackEvent", event]);
```

#### Parameters

* #### Event Object   object  

  Name and properties of the event to collect.

  * #### name   string (<= 1024 chars)  

    The name of the event.

  * #### properties   object (optional)  

    The properties of the event.

  * #### key   string (<= 512 chars)  

    The key of the property.

  * #### value   boolean, number, string, or array (<= 1024 chars)  

    The value of the property.

## Sending from submit

Deprecated

To track form [submit ↗](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) events, implement a command that will add submit events to the analytics events collected.

### `submit`

Deprecated | iframe | **Added in:** `11.8.0`

Send the submit state to the Contentsquare Tag.

```javascript
window._uxa.push(["submit", state, htmlElement]);
```

#### Parameters

* #### state   string  

  Submit state.

  Possible values: `attempt`, `success`, or `failure`.

* #### htmlElement   string  

  A CSS selector reference to a DOM element.

## Session Replay data collection

Masking (also known as "auto-masking") is the process where text node content (text in a web page) is replaced by `aaa` strings. This feature is enabled or disabled per project through feature flags.

For example, the string `Imagine this string in a textNode element` is replaced by `aaaaaaa aaa aaaaaa aa a aaaaaaaa aaaaaaa`.

In addition to replacing text content, masking removes most element attributes except an allowlist and all attributes on SVG elements. The allowlist can be extended through the Tag configuration in the back-office.

By design, replacing any string by "a" may result in altering the layout of the website because most websites do not use monospace fonts — any replacement may result in different placement of the text in replay. If this is a problem, disable masking and use [`setPIISelectors`](#setpiiselectors) to mask personal data on the website instead.

### `setCapturedElementsSelector`

iframe | webview | **Added in:** `9.22.0`

Capture elements' text data with Page Masking enabled.

```javascript
window._uxa.push(["setCapturedElementsSelector", CSS_SELECTORS]);
```

Warning

The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand.

[Tag Configurator Template: Element Unmasking ](https://support.contentsquare.com/hc/en-us/articles/37271866118033-CSTC-Template-Element-Unmasking)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### CSS\_SELECTORS   string  

  Comma-separated list of CSS selectors.

### `setPIISelectors`

iframe | webview | **Added in:** `9.28.0`

Mask Personal Data using specific selectors.

```javascript
const PIIobject = {
  PIISelectors: [".to-mask, #mask-me"],
  Attributes: [
    {
      selector: ".bar",
      attrName: "foo"
     }
  ]
};


window._uxa.push(['setPIISelectors', PIIObject]);
```

Warning

The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand.

[Tag Configurator Template: Element Masking ](https://support.contentsquare.com/hc/en-us/articles/37271836678545-CSTC-Template-Element-Masking)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### PIIObject   object  

  Elements and attributes to be masked in Session Replay.

  * #### PIISelectors   array (optional)  

    Comma-separated list of CSS selectors for elements to mask completely.

  * #### Attributes   array of objects (optional)  

    Attributes to mask

    * #### selector   string  

      CSS selector of the element

    * #### attrName   string  

      Attribute name to mask

### `setEncryptionSelectors`

iframe | webview | **Added in:** `11.63.0`

Encrypt sensitive data in elements matched by CSS selectors. An encryption key must be set using the Tag configuration in the Contentsquare console.

```javascript
window._uxa.push(["setEncryptionSelectors", CSS_SELECTORS]);
```

Warning

The command must be called before the Tag is loaded. In case of a [`trackPageview`](#trackpageview), this command should be called beforehand.

#### Parameters

* #### CSS\_selectors   string  

  Comma-separated list of CSS selectors

### `trackEventTriggerRecording`

iframe | **Added in:** `9.5.0`

Trigger Session Replay data collection after a specific event. When the collection mode is ETR (Event Triggered Replay), the Tag collects all sessions but only keeps those that trigger at least one ETR event.

There are two ETR types:

* **Session** (default): the pipeline keeps all pageviews of the session
* **Page**: the pipeline keeps at least the current pageview

To trigger a page-level ETR, prefix the event name with `@ETP@`. The `@ETS@` prefix is optional for session-level ETR.

```javascript
// Session ETR (default)
window._uxa.push(["trackEventTriggerRecording", eventName]);


// Page ETR
window._uxa.push(["trackEventTriggerRecording", "@ETP@" + eventName]);
```

#### Parameters

* #### eventName   string (<= 255 chars)  

  The name of the event that triggers Session Replay data collection. Truncated if longer than 255 characters. Prefix with `@ETP@` for page-level ETR.

### `excludeURLforReplay`

iframe | webview | **Added in:** `11.66.0`

Specify a regular expression to exclude matching URLs from Session Replay data collection.

```javascript
window._uxa.push(["excludeURLforReplay", regex]);
```

Call this command once, before the Tag is loaded. The regex is matched against the URL without the protocol. It is kept until the next page load.

#### Parameters

* #### regex   string  

  Regular expression string matched against the URL (without protocol) to exclude from Session Replay.

#### Examples

##### Exclude checkout and account pages across specific subdomains

```javascript
window._uxa = window._uxa || [];


window._uxa.push(["excludeURLforReplay", "(us|uk|de)\\.shoetune\\.eu/(checkout|account).*"]);
```

This excludes the `/checkout` and `/account` sections on `us.shoetune.eu`, `uk.shoetune.eu`, and `de.shoetune.eu`, including deeper paths and query strings such as `us.shoetune.eu/checkout/step-2?promo=SPRING`.

### `replay:consent:unanonymized:granted`

Personal Data Exposure

When misused, this command can lead to the exposure of personal data in Session Replays. Make sure to only grant and withdraw consent when you are sure that no personal data will be collected in Session Replays.

iframe | **Added in:** `13.33.0`

Disable masking for the current browser when masking is enabled on the project.

```javascript
window._uxa.push(["replay:consent:unanonymized:granted"]);
```

The consent is sticky for 13 months, stored in the [`_cs_c`](https://docs.contentsquare.com/en/web/cookies/#_cs_c) cookie. If masking is disabled on the project, this command has no effect.

Note

Before v13.33.0, this command was named `trackConsentGranted` (still supported).

#### Parameters

* No parameters.

### `replay:consent:unanonymized:withdrawn`

Personal Data Exposure

When misused, this command can lead to the exposure of personal data in Session Replays. Make sure to only grant and withdraw consent when you are sure that no personal data will be collected in Session Replays.

iframe | **Added in:** `13.33.0`

Re-enable masking for the current browser after consent was granted.

```javascript
window._uxa.push(["replay:consent:unanonymized:withdrawn"]);
```

The withdrawal is sticky for 13 months, stored in the [`_cs_c`](https://docs.contentsquare.com/en/web/cookies/#_cs_c) cookie. If masking is disabled on the project, this command has no effect.

Note

Before v13.33.0, this command was named `trackConsentWithdrawn` (still supported).

#### Parameters

* No parameters.

### `replay:resourceManager:enableForOnlineResource:nextPageviewOnly`

iframe | **Added in:** `13.66.0`

Activates the collection of remote resources of the page by the Static Resource Manager for the next pageview. By default, the pipeline downloads resources (images, CSS, etc.) from their URLs. When resources require authentication or VPN access, enable this command so the Tag sends resource content directly instead.

Should be used before a pageview containing protected resources starts.

```javascript
window._uxa.push(["replay:resourceManager:enableForOnlineResource:nextPageviewOnly"]);
```

#### Parameters

* No parameters.

### `replay:resourceManager:getStatus`

**Added in:** `13.66.0`

Returns information concerning the Static Resource Manager feature current state to help with implementation and troubleshooting.

```javascript
window._uxa.push(["replay:resourceManager:getStatus"]);
```

The response schema from a command run is:

```json
{
 "isStarted": boolean,
 "onlineAssets": {
  "activated": boolean,
  "enabledOnNextPageview": boolean,
  "enabledForChilddrenOnNextStart" boolean
 }
}
```

#### Parameters

* No parameters.

## API errors and network requests collection

Masking commands for network request URLs that are collected. This affects URLs that are collected in the context of API Errors and Network Details.

### `networkRequest:maskUrls`

iframe | webview | **Added in:** `15.24.0`

Register patterns to mask URLs collected for API errors and network details.

```javascript
window._uxa.push(["networkRequest:maskUrls", pattern]);
```

Compatibility with the api-errors:maskUrl command

If a pattern registered by the [api-errors:maskUrl](https://docs.contentsquare.com/en/web/command-reference/#api-errorsmaskurl) command matches a URL, patterns supplied to `networkRequest:maskUrls` are not taken into account.

[Tag Configurator Template: Network requests mask URLs ](https://support.contentsquare.com/hc/en-us/articles/37271848447761-CSTC-Template-Network-requests-mask-URLs)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### pattern   string or array of strings  

  One or several URL masking patterns. Patterns can match the full URL of the page or only a part of it.

  URL fragments to mask are prefixed by a colon. They are replaced by `CS_ANONYMIZED_{FRAGMENT}`.

You can also call this command multiple times with different patterns each time to register multiple patterns. No patterns are overridden.

#### Examples

Supplying the following URL masking patterns:

```javascript
window._uxa.push([
  "networkRequest:maskUrls",
  ["contracts/:contract_id/clients/:client_id", "resources/:resource_id"],
]);
```

On the following URLs:

```txt
https://host.com/contracts/123456/clients/llltgm/offers
https://resources/56789/locations
```

Results in these masked URLs which are collected by Tag:

```txt
https://host.com/contracts/CS_ANONYMIZED_CONTRACT_ID/clients/CS_ANONYMIZED_CLIENT_ID/offers
https://resources/CS_ANONYMIZED_RESOURCE_ID/locations
```

### `networkRequest:maskUrls:reset`

iframe | webview | **Added in:** `15.24.0`

Clear all patterns registered using the [`networkRequest:maskUrls`](https://docs.contentsquare.com/en/web/command-reference/#networkrequestmaskurls) command.

```javascript
window._uxa.push(["networkRequest:maskUrls:reset"]);
```

#### Parameters

* No parameters.

### `api-errors:maskUrl`

iframe | webview | Deprecated | **Added in:** `10.8.0`

Register patterns to mask URLs collected for API errors and network details.

```javascript
window._uxa.push(["api-errors:maskUrl", url]);
```

#### Parameters

* #### url   string  

  Full URL of the page.

  URL fragments to mask are prefixed by a colon. They are replaced by `CS_ANONYMIZED_{FRAGMENT}`.

#### Examples

##### Mask order IDs

```javascript
var urls = [
  "https://api.net/order/:order_id/merge/:order_id",
  "https://api.net/order/:order_id/item",
  "https://www.api.nl/nl/ajax/nfs/account/cancelOrder/:order_id",
];
for (var i = 0; i < urls.length; i++) {
  window._uxa.push(["api-errors:maskUrl", urls[i]]);
}
```

The URLs will be collected as:

```txt
https://api.net/order/CS_ANONYMIZED_ORDER_ID/merge/CS_ANONYMIZED_ORDER_ID
https://api.net/order/CS_ANONYMIZED_ORDER_ID/item
https://www.api.nl/nl/ajax/nfs/account/cancelOrder/CS_ANONYMIZED_ORDER_ID
```

## Custom Errors collection

Experience Monitoring Web

To send an error to Contentsquare without any JavaScript or API error triggered in the browser, it is possible to send a custom error.

### `trackError`

iframe | webview | **Added in:** `11.36.0`

Collect any text displayed on the user screen because of a specific action.

```javascript
window._uxa.push(["trackError", message, { ERROR_CATEGORIES }]);
```

[Tag Configurator Template: Custom Error ](https://support.contentsquare.com/hc/en-us/articles/37271813052817-CSTC-Template-Custom-Error)Learn how to use this command with the Contentsquare Tag Configurator.

#### Parameters

* #### message   string (<= 300 chars)  

  The text to collect.

* #### ERROR\_CATEGORIES   object \[1...5] (optional)  

  An object containing up to 5 key/value pairs to categorize the errors. Keys and values must be up to 30 characters. When these limitations are not respected, the command is ignored.

  * #### \[key\_name]   string (<= 30 chars)  

    The key name

  * #### \[value\_name]   string (<= 30 chars)  

    The value name

#### Examples

##### Send a custom error for incorrect user input

```javascript
window._uxa.push([
  "trackError",
  "140000 is not a valid postal code",
  {
    type: "formValidation",
    severity: "minor",
    lang: "english"
  },
]);
```

## Identity

Product Analytics

Identity commands allow you to attach a unique identity to the current user.

For more information, see [Track User Identity ↗](https://developers.heap.io/docs/using-identify)

Required configuration

* `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` ||
* `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap`

### `identify`

This command associates the current user with the provided identity string.

If this command is called while the current user already has a **different** identity string associated with them, the current session will be reset, the user ID will be re-generated, and a new pageview of type renewal will be sent.

Calling `identify` with the same identity does not reset the session.

This command extends the session.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.69.0`

  ```javascript
  window._uxa.push(["identify", <identityString>, <options>]);
  ```

  #### Parameters

  * #### identityString   string | number  

    The identity string that will be associated with the current user.

  * #### options   { hash: boolean }  

    With `{ hash: true }`, the identity string will be hashed before being sent to the server.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.1.0`

  ```javascript
  window._uxa.push(["identify", <identityString>]);
  ```

  This command acts as a wrapper for the `heap.identify` command. See [https://developers.heap.io/reference/identify ↗](https://developers.heap.io/reference/identify)

  #### Parameters

  * #### identityString   string | number  

    The identity string that will be associated with the current user.

### `resetIdentity`

When called while the current user has an identity string associated with them, the current session will be reset, the user ID will be re-generated, and a new pageview of type renewal will be sent. If the user is not identified, this command has no effect.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.69.0`

  ```javascript
  window._uxa.push(["resetIdentity"]);
  ```

  #### Parameters

  * No parameters.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.1.0`

  ```javascript
  window._uxa.push(["resetIdentity"]);
  ```

  #### Parameters

  * No parameters.

  This command acts as a wrapper for the `heap.resetIdentity` command. See [https://developers.heap.io/reference/resetidentity ↗](https://developers.heap.io/reference/resetidentity)

### `getIdentity`

This command is a helper command that determines whether the current user has an identity string associated with them.

* cs\_crosswrites\_heap

  iframe | **Added in:** `15.69.0`

  ```javascript
  window._uxa.push(["getIdentity"]);
  ```

  #### Parameters

  * No parameters.

  This command will not return the exact identity string but a hash computed from the identity string.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.1.0`

  ```javascript
  window._uxa.push(["getIdentity"]);
  ```

  #### Parameters

  * No parameters.

  This command acts as a wrapper for the `heap.getIdentity` command. See [https://developers.heap.io/docs/api-reference#getidentity ↗](https://developers.heap.io/docs/api-reference#getidentity)

## User properties

Product Analytics

User properties command allows you to attach custom properties to the current user.

For more information, see [Track User Identity ↗](https://developers.heap.io/docs/using-identify)

Required configuration

* `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` ||
* `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap`

### `addUserProperties`

This command associates the current user with the given custom properties, overwriting any previously set values for the same properties.

This command extends the session.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.69.0`

  ```javascript
  window._uxa.push(["addUserProperties", properties]);
  ```

  #### Parameters

  * #### properties   Record\<string, string | number | boolean | bigint>  

    The custom properties to attach to the current user.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.31.0`

  ```javascript
  window._uxa.push(["addUserProperties", properties]);
  ```

  #### Parameters

  * #### properties   Record\<string, string | number | boolean | bigint>  

    The custom properties to attach to the current user.

  This command acts as a wrapper for the `heap.addUserProperties` command. See [https://developers.heap.io/reference/adduserproperties ↗](https://developers.heap.io/reference/adduserproperties)

## Event properties

Product Analytics

Event properties commands allow you to attach custom properties to events. These properties will be included with all subsequent events until they are removed or cleared.

Required configuration

* `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap` ||
* `CS_CONF.heapEnvironment?.heap_tag_status === cs_sideloads_heap`

### `customProperties:visit:add`

Alias: `addEventProperties`

This command adds custom properties that will be attached to all subsequent events.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:add", properties]);
  ```

  #### Parameters

  * #### properties   Record\<string, string | number | boolean | bigint>  

    The custom properties to attach to all subsequent events.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:add", properties]);
  ```

  #### Parameters

  * #### properties   Record\<string, string | number | boolean | bigint>  

    The custom properties to attach to all subsequent events.

  This command acts as a wrapper for the `heap.addEventProperties` command. See [https://developers.heap.io/reference/addeventproperties ↗](https://developers.heap.io/reference/addeventproperties)

### `customProperties:visit:remove`

Alias: `removeEventProperty`

This command removes a custom property from subsequent events.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:remove", property]);
  ```

  #### Parameters

  * #### property   string  

    The name of the property to remove.

* cs\_sideloads\_heap

  iframe | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:remove", property]);
  ```

  #### Parameters

  * #### property   string  

    The name of the property to remove.

  This command acts as a wrapper for the `heap.removeEventProperty` command. See [https://developers.heap.io/reference/removeeventproperty ↗](https://developers.heap.io/reference/removeeventproperty)

### `customProperties:visit:clear`

Alias: `clearEventProperties`

This command removes all custom properties from subsequent events.

* cs\_crosswrites\_heap

  iframe | webview | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:clear"]);
  ```

* cs\_sideloads\_heap

  iframe | **Added in:** `15.152.0`

  ```javascript
  window._uxa.push(["customProperties:visit:clear"]);
  ```

  This command acts as a wrapper for the `heap.clearEventProperties` command. See [https://developers.heap.io/reference/cleareventproperties ↗](https://developers.heap.io/reference/cleareventproperties)

## Pageview properties

Product Analytics

Pageview properties commands allow you to attach custom properties to pageviews. These properties will be attached to the current pageview and all events that occur on that page.

Required configuration

* `CS_CONF.heapEnvironment?.heap_tag_status === cs_crosswrites_heap`

### `customProperties:page:add`

iframe | webview | **Added in:** `15.69.0`

This command adds custom properties to the current pageview and events on the page.

```javascript
window._uxa.push(["customProperties:page:add", properties]);
```

#### Parameters

* #### properties   Record\<string, string | number | boolean | bigint>  

  The custom properties to attach to the current pageview and subsequent events.

### `customProperties:page:remove`

iframe | webview | **Added in:** `15.69.0`

This command removes a custom property from subsequent events on the page.

```javascript
window._uxa.push(["customProperties:page:remove", property]);
```

#### Parameters

* #### property   string  

  The name of the property to remove.

### `customProperties:page:clear`

iframe | webview | **Added in:** `15.69.0`

This command clears all custom properties from the subsequent events on the current pageview.

```javascript
window._uxa.push(["customProperties:page:clear"]);
```

## Integrations

Integration commands allow you to retrieve session information and register callbacks to be run after pageviews or when the data collection context changes. These are used for integrating Contentsquare data with other tools and systems.

### `getSessionKey`

iframe | **Added in:** `5.15.0`

Retrieves a unique Contentsquare session key. Returns the `sessionKey` string if the natural pageview has already been sent, otherwise `undefined`. A unique session identifier formatted as `<userId>.<sessionNumber>` (example: `123abc.789`) — `userId` is a unique anonymous ID generated by Contentsquare.

```javascript
function callback(sessionKey) {
  const [userId, sessionNumber] = sessionKey.split(".");
  // do something with the session key
}


window._uxa = window._uxa || [];
_uxa.push(["getSessionKey", { callback }]);
```

#### Parameters

* #### options   object (optional)  

  Options object.

  * #### options.callback   function  

    Callback function which receives the `sessionKey` string.

### `afterPageView`

iframe | webview | **Added in:** `7.7.0`

Allows to run a callback function after a natural or artificial pageview.

```javascript
window._uxa.push(["afterPageView", callback]);


function callback(context) {
  const sessionKey = context.sessionKey;
  const pageNumber = context.pageNumber;
  const projectId = context.projectId;
  const pageViewType = context.pageViewType;
  const uxaDomain = context.uxaDomain;
  const isRecording = context.isRecording;
  const recordingConsentState = context.recordingConsentState;
  // ...
}
```

#### Parameters

* #### callback   function  

  Callback function which receives a context object.

  * #### context.sessionKey   string  

    A unique session identifier. A string that encodes `<userId>.<sessionNumber>` (example: `59e73d8b-2730u283i20-6712c43aaab3.3`) — `userId` is a unique anonymous ID generated by Contentsquare.

  * #### context.pageNumber   number  

    The page number

  * #### context.projectId   number  

    Your Contentsquare project ID.

  * #### context.pageViewType   string  

    Natural (n), Artificial (a), Renewal (r).

  * #### context.uxaDomain   string  

    The Contentsquare App domain.

  * #### context.isRecording   boolean  

    Whether Session Replay is on.

  * #### context.recordingConsentState   number  

    Indicates the visitor's choice regarding consent:

    * 1 = not required,
    * 2 = not expressed,
    * 3 = withdrawn,
    * 4 = granted

  The callback function is run after the natural pageview and after each `trackPageview`. You can register multiple callbacks by calling the command multiple times.

#### Examples

##### Check visitor consent for Session Replay a on specific page

```javascript
window._uxa = window._uxa || [];
_uxa.push(["afterPageView", callback]);


function callback(context) {
  if (context.recordingConsentState === 2 && context.pageNumber === 42) {
    displayConsentWidget();
  }
}
```

### `replay:link:generate`

iframe | **Added in:** `13.25.0`

Generate a replay link.

```javascript
window._uxa.push(["replay:link:generate", { withTimestamp: true }, onReplayLinkGenerated]);


function onReplayLinkGenerated(context) {
  var isRecording = context.isRecording;
  var replayLink = context.replayLink;
  // ...
}
```

#### Parameters

* #### options   object  

  Replay link options

  * #### withTimestamp   boolean  

    Whether the replay link is generated with a timestamp

* #### onReplayLinkGenerated   function  

  Callback function which receives a context object.

  * #### context.isRecording   boolean  

    Whether the data collection for Session Replay is in progress.

  * #### context.replayLink   string  

    The replay link of the session, optionally with a timestamp query parameter (`withTimeStamp`).

### `onRecordingContextChange`

iframe | webview | **Added in:** `13.55.0`

Note

The command alias `onRecordingStateChange` is still compatible.

Track changes to the data collection context to avoid false positives while generating replay links.

```javascript
window._uxa.push(["onRecordingContextChange", onRecordingContextChange]);


function onRecordingContextChange(context) {
  var isRecording = context.isRecording;
  var recordingStartTimestamp = context.recordingStartTimestamp;
  var etrState = context.etrState;
  var etrStatus = context.etrStatus;
  // ...
}
```

#### Parameters

* #### onRecordingContextChange   function  

  Callback function which receives a context object and called each time the data collection context changes.

  * #### context.isRecording   boolean  

    Whether the data collection for Session Replay is in progress.

  * #### context.recordingStartTimeStamp   number  

    Timestamp indicating when data collection for Session Replay started.

  * #### context.etrState   string  

    `0` (ETR is disabled) or `1` (ETR is enabled).

  * #### context.etrStatus   string  

    `0` (ETR is disabled), `1` (ETR is pending), `2` (ETR is triggered on **page**) or `3` (ETR is triggered on **session**).

## Webview mode

When the Tag is integrated in a WebView where the tracking is managed by the app opening the WebView (for example Android, iOS, or Cordova), the Tag should not be in charge of managing the session but only report tracked events (click, DOM mutation) to the Contentsquare SDK installed in the iOS or Android app.

It is necessary to enable the WebView mode for the Tag to enable this specific behavior.

### `setOption`

**Added in:** `4.0.1`

Enables webview mode when the Tag is managed by a mobile app opening the WebView.

```javascript
window._uxa.push(["setOption", "isWebView", true]);
```