Tag API reference

Reference of public Tag commands and their signature, 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

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

• url   string  

  URL containing parameters prefixed with a colon for making purposes.

Keep the query string from the referrer URL.
Reverts the behavior of referrer:removeQueryString.
You can be called multiple times to mask different URL patterns.

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

No parameters.

Remove all characters in the query string after the question mark (?).

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

No parameters.

Define a custom variable — additional information on the page, user, or the session.

window._uxa.push(['setCustomVariable', index, name, value, scope]);

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

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,
  sku: ITEM_SKU_CODE,
  category: ITEM_CATEGORY,
  price: AMOUNT,
  quantity: QUANTITY
}]);

• id   string  

  The Transaction ID.

• name   string  

  Item name.

• sku   string  

  A valid Stock Keeping Unit (SKU) code.

• category   string  

  Item category.

• price   float  

  Item price.

• quantity   integer  

  Number of items.

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.

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

Track a page event.

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

• eventName   string (<= 255 chars)  

  The name of the event to collect.

Examples

Collect when visitors save a property add for later consultation

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

Collect user identifiers for Session Replays

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.

Rewrite the URL before the Tag is tracking the API errors and collecting the request URL.
You can be called multiple times to mask different URL patterns.

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

• url   string  

  Full URL of the page.
  Parameters containing personal data are prefixed by a colon.

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

Examples

Send a custom error for incorrect user input

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

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 that encodes <userId>.<sessionNumber> e.g. 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> e.g. 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  

  Session Replay link options

  withTimestamp   boolean  

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

• onRecordingStateChange   function  

  Callback function which receives a context object and called each time the replay state changes.

  context.etrState   string  

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

  context.isRecording   boolean  

  Whether the data collection for Session Replay is in progress.

  context.recordingTimeStamp   number  

  Timestamp indicating when data collection for Session Replay started.

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 a Session Replay after a specific event.

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

• eventName   string (<= 255 chars)  

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

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.

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

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