Tag API reference

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

Send an artificial pageview.

window._uxa.push(['trackPageview', path, options]);

If run before the loading of the tag, the command will behave as setPath.

• 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

  decodeURI   boolean  

  Single attempt to decode the provided path using the decodeURI ↗ native API. Since 13.97.0.

  decodeURIDeep   boolean  

  Up to 10 attempts to fully decode the provided path using the decodeURI ↗ native API. Since 13.97.0.

  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.

Override the path to send within a pageview.

window._uxa.push(['setPath', path, options]);

• path   string  

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

• options   object (optional)  

  Path options

  decodeURI   boolean  

  Single attempt to decode the provided path using the decodeURI ↗ native API. Since 13.97.0.

  decodeURIDeep   boolean  

  Up to 10 attempts to fully decode the provided path using the decodeURI ↗ native API. Since 13.97.0.

  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.

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

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

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

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

instead of:

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

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

window._uxa.push(['setQuery', queryString, options]);

• queryString   string  

  Masked query string.

• options   object (optional)  

  Query string options

  decodeURI   boolean  

  Single attempt to decode the provided queryString using the decodeURI ↗ native API. Since 13.97.0.

  decodeURIDeep   boolean  

  Up to 10 attempts to fully decode the provided queryString using the decodeURI ↗ native API. Since 13.97.0.

  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.

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

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:

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

instead of:

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

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.

window._uxa.push(['referrer:maskUrl', url]);

• url   string  

  URL containing parameters prefixed with a colon for making purposes.

The referrer URL to be sent is:

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

By calling referrer:maskUrl with this URL:

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

The referrer URL that is sent becomes:

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

Reverts the action of referrer:removeQueryString for the next pageview.

window._uxa.push(['referrer:removeQueryString']);

The referrer URL to be sent is:

https://hello?withQueryString=true

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

window._uxa.push(['referrer:removeQueryString'])
// Referrer URL will be https://hello?

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

No parameters.

Remove all characters in the query string.

window._uxa.push(['referrer:removeQueryString']);

No parameters.

The referrer URL to be sent is:

https://hello?withQueryString=true

By calling referrer:removeQueryString:

window._uxa.push(['referrer:removeQueryString']);

The referrer URL becomes:

https://hello?

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

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 exist with a given index, the new name and value will override the old one.

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

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

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

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

To delete the custom variable:

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

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:

window._uxa.push(['trackPageview', '/a-path']);

After sending another artificial pageview:

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

The custom variable is automatically deleted.

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

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

• scope   string  

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

Consider the following HTML page:

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

Reverts the action of hidePageTitle for the next pageviews.

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

No parameters.

Create transactions before adding items and sending them to Contentsquare.

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

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

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']);

Add item to a transaction created with ec:transaction:create.

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
}]);

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

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']);

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

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

No parameters.

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']);

Register an add to cart event.

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

• merchant   string (optional)  

  The merchant name.

• sku   string (optional)  

  A valid Stock Keeping Unit (SKU) code.

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

Extend session duration.

window._uxa.push(['extendSession']);

This command automatically extends a session until:

• The session duration reaches 4h00
• A new pageview is triggered

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

• Update the session cookie 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.

No parameters.

Opt out the current user from data collection.

window._uxa.push(['optout']);

No parameters.

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

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

No parameters.

Clear all data linked to previous visitors.

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

No parameters.

Send a dynamic variable.

window._uxa.push(['trackDynamicVariable', {DYNAMIC_VARIABLE}]);

• DYNAMIC_VARIABLE   object  

  The dynamic variable

  key   string (<= 512 chars)  

  Dynamic variable key

  value   number or string (<=255 chars)  

  Dynamic variable value

First user

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

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

Track a page event.

window._uxa.push(['trackPageEvent', eventName]);

• eventName   string (<= 255 chars)  

  The name of the event to collect.

window._uxa = window._uxa || [];
window._uxa.push(['trackPageEvent', 'SubscribedToPropertyButtonClick']);

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

See User Identifier.

Send the submit state to the Contentsquare Tag.

window._uxa.push(['submit', state, htmlElement]);

• state   string  

  Submit state.

  Possible values: attempt, success, or failure.

• htmlElement   string  

  A CSS selector reference to a DOM element.

Capture elements’ text data with auto-masking enabled.

window._uxa.push(['setCapturedElementsSelector', CSS_SELECTORS]);

• CSS_SELECTORS   string  

  Comma-separated list of CSS selectors.

Mask Personal Data using specific selectors.

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

window._uxa.push(['setPIISelectors', {PII Object}]);

• PII Object   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

Encrypt sensitive data in elements matched by CSS selectors.

window._uxa.push(['setEncryptionSelectors', CSS_SELECTORS]);

• CSS_selectors   string  

  Comma-separated list of CSS selectors

Trigger Session Replay data collection after a specific event.

window._uxa.push(['trackEventTriggerRecording', eventName]);

• eventName   string (<= 255 chars)  

  The name of the event to collect that triggers Session Replay data collection.

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

window._uxa.push(['excludeURLforReplay', regex]);

The command must be called before the Tag is loaded. The regex is kept until the next page load.

• regex   string  

  Regular expression string to exclude matching URLs from Session Replay.

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

window._uxa.push(['excludeURLforReplay', "shoetune\\.eu.*/mens-runners.*"]);

Activates the collection of remote resources of the page by the Static Resource Manager for the next pageview. Should be used before a pageview containing protected resources starts.

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

No parameters.

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

window._uxa.push(['replay:resourceManager:getStatus']);

The response schema from a command run is:

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

No parameters.

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

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

• 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}.

Supplying the following URL masking patterns:

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

On the following URLs:

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

Results in these masked URLs which are collected by Tag:

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

Clear all patterns registered using the networkRequest:maskUrls command.

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

No parameters.

Deprecated | Added in: 10.8.0

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

window._uxa.push([ 'api-errors:maskUrl', url ])

• url   string  

  Full URL of the page.

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

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:

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

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

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

• 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

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

Identity commands help attaching the current user with a unique identity.

For more information, see Track User Identity ↗

window._uxa.push(["identify", identityString]);

See https://developers.heap.io/reference/identify ↗

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

See https://developers.heap.io/reference/resetidentity ↗

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

See https://developers.heap.io/docs/api-reference#getidentity ↗

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

See https://developers.heap.io/reference/adduserproperties ↗

window._uxa.push(["addEventProperties", properties]);

See https://developers.heap.io/reference/addeventproperties ↗

window._uxa.push(["removeEventProperty", property]);

See https://developers.heap.io/reference/removeeventproperty ↗

window._uxa.push(["clearEventProperties"]);

See https://developers.heap.io/reference/cleareventproperties ↗

Retrieves a unique Contentsquare session key.

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

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

• callback   function  

  Callback function which receives a 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.

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

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;
  // ...
}

• 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 executed after the natural pageview and after each trackPageview. You can register multiple callbacks by calling the command multiple times.

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

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

Generate a replay link.

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

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

• options   object  

  Replay link options

  withTimestamp   boolean  

  Whether the replay link is generated with a timestamp

• onReplayLinkGenerated   function  

  Callback function with 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).

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

window._uxa.push(['onRecordingStateChange', onRecordingStateChange]);

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

• onRecordingStateChange   function  

  Callback function which receives a context object and called each time the replay state 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).

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

window._uxa.push(['setOption', 'isWebView', true]);