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

> ## Documentation index
> Fetch the complete documentation index at: 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.

### Legacy Heap sideloading

The Product Analytics commands on this page are documented for native collection. On the legacy projects where the Contentsquare Tag loads the Heap SDK, some of these commands behave differently — see [Heap sideloading (legacy)](https://docs.contentsquare.com/en/web/heap-sideloading/).

## 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`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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
```

### `referrer:removeQueryString`

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

Remove all characters in the query string.

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

#### 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`](https://docs.contentsquare.com/en/web/command-reference/#hidepagetitle) for the next pageviews.

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

## 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`](https://docs.contentsquare.com/en/web/command-reference/#ectransactioncreate) to create a transaction which can contain items
2. [`ec:transaction:items:add`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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"]);
```

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

Commands extending the session

The following commands also extend the session duration:

* [identify](https://docs.contentsquare.com/en/web/command-reference/#identify)
* [addUserProperties](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties)
* [ec:transaction:send](https://docs.contentsquare.com/en/web/command-reference/#ectransactionsend)
* [ec:cart:add](https://docs.contentsquare.com/en/web/command-reference/#eccartadd)

### `optout`

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

Opt out the current user from data collection.

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

### `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"]);
```

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

## 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`](https://docs.contentsquare.com/en/web/command-reference/#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`

webview | **Added in:** `15.116.0`

Track a custom event.

Note

Requires a [Product Analytics](https://contentsquare.com/platform/product-analytics/) plan, the [User Lifecycle Extension](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension), the [Data Connect](https://support.contentsquare.com/hc/en-us/articles/37271863730705-Get-started-with-Data-Connect) module, or enrollment in the **Contentsquare Experience Platform Early Access program**.

Voice of Customer survey targeting

The Tag processes the event, then forwards it to the legacy [`hj("event")` ↗](https://help.hotjar.com/hc/en-us/articles/36819965075473-Events-API-Reference) API, so [Voice of Customer](https://docs.contentsquare.com/en/web/voice-of-customer/) can target surveys on it. Pushing `["trackEvent", { name: "my_event" }]` is equivalent to calling `hj("event", "my_event")`, and matches a survey targeting rule on the `my_event` trigger. Only the event name is forwarded, not the event properties.

Use `trackEvent` instead of `hj("event")` in new implementations.

```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`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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`](https://docs.contentsquare.com/en/web/command-reference/#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 tested against the URL (without protocol) using a partial match — the pattern does not need to match the full URL.

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

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

### `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"]);
```

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

## 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"]);
```

### `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 users](https://docs.contentsquare.com/en/web/track-users/).

Note

Requires a [Product Analytics](https://contentsquare.com/platform/product-analytics/) plan, the [User Lifecycle Extension](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension), the [Data Connect](https://support.contentsquare.com/hc/en-us/articles/37271863730705-Get-started-with-Data-Connect) module, or enrollment in the **Contentsquare Experience Platform Early Access program**.

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

Voice of Customer survey targeting

The Tag processes the identity string, then forwards it to the legacy [`hj("identify")` ↗](https://help.hotjar.com/hc/en-us/articles/36820006120721-Identify-API-Reference) API, so [Voice of Customer](https://docs.contentsquare.com/en/web/voice-of-customer/) can target surveys on it. Pushing `["identify", "101"]` is equivalent to calling `hj("identify", "101")`, and matches a survey targeting rule on the `userId` attribute with the value `101`.

The identity string is not forwarded when you set the `hash` option to `true`, because the hashed value cannot be anticipated when the survey is created.

Use `identify` instead of `hj("identify")` in new implementations.

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.

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

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

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

### `getIdentity`

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

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

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

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

## User properties

Product Analytics

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

For more information, see [Adding user properties](https://docs.contentsquare.com/en/web/track-users/#adding-user-properties).

Note

Requires a [Product Analytics](https://contentsquare.com/platform/product-analytics/) plan, the [User Lifecycle Extension](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension), the [Data Connect](https://support.contentsquare.com/hc/en-us/articles/37271863730705-Get-started-with-Data-Connect) module, or enrollment in the **Contentsquare Experience Platform Early Access program**.

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

Voice of Customer survey targeting

The Tag processes the properties, then forwards them to the legacy [`hj("identify")` ↗](https://help.hotjar.com/hc/en-us/articles/36820006120721-Identify-API-Reference) API, so [Voice of Customer](https://docs.contentsquare.com/en/web/voice-of-customer/) can target surveys on them. Pushing `["addUserProperties", { my_attr: "test" }]` is equivalent to calling `hj("identify", null, { my_attr: "test" })`, and matches a survey targeting rule on the `my_attr` attribute with the value `test`. User properties are called user attributes in the Voice of Customer survey targeting interface.

This command is also available when Product Analytics is disabled. In that case, it only forwards the properties to Voice of Customer.

Use `addUserProperties` instead of `hj("identify")` in new implementations.

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.

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

Note

Requires a [Product Analytics](https://contentsquare.com/platform/product-analytics/) plan, the [User Lifecycle Extension](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension), the [Data Connect](https://support.contentsquare.com/hc/en-us/articles/37271863730705-Get-started-with-Data-Connect) module, or enrollment in the **Contentsquare Experience Platform Early Access program**.

### `customProperties:visit:add`

Alias: `addEventProperties`

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

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.

### `customProperties:visit:remove`

Alias: `removeEventProperty`

This command removes a custom property from subsequent events.

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.

### `customProperties:visit:clear`

Alias: `clearEventProperties`

This command removes all custom properties from subsequent events.

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

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

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

Note

Requires a [Product Analytics](https://contentsquare.com/platform/product-analytics/) plan, the [User Lifecycle Extension](https://support.contentsquare.com/hc/en-us/articles/37271864562961-Introduction-to-the-User-Lifecycle-extension), the [Data Connect](https://support.contentsquare.com/hc/en-us/articles/37271863730705-Get-started-with-Data-Connect) module, or enrollment in the **Contentsquare Experience Platform Early Access program**.

### `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]);
```


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Tag API reference","description":"Tag commands reference including signature, parameter descriptions, and examples","url":"https://docs.contentsquare.com/en/web/command-reference/","inLanguage":"en","dateModified":"2026-10-02T16:39:51+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```