Tag API reference

Reference of public Tag commands and their signature, and examples.

Send an artificial pageview.

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

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

Parameters

• path string (optional, <= 255 chars)

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

Override the path to send within a pageview.

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

Parameters

• path string

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

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

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

Parameters

• queryString string

  Masked query string.

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

Parameters

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

Parameters

No parameters.

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

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

Parameters

No parameters.

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

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

Parameters

• index positive integer

  Variable index (between 1 and 20).

• name string (<= 512 chars)

  Variable name.

• value string (<= 255 chars)

  Variable value.

• scope string : 'visit' | 'page' | 'nextPageOnly' or integer : 2 | 3 | 4 (optional)

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

Create transactions before adding items and sending them to Contentsquare.

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 (<= 10)

  Currency value.

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

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

window._uxa.push(['ec:transaction:items:add', {
  id: "6677807431755",
  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: ITEM_ID,
  name: ITEM_NAME,
  sku: ITEM_SKU_CODE,
  category: ITEM_CATEGORY,
  price: AMOUNT,
  quantity: QUANTITY
}]);

Parameters

• id string

  Item 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: "6677807431755",
  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']);

Parameters

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

Parameters

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

Parameters

No parameters.

Opt out the current user from data collection.

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

Parameters

No parameters.

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

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

Parameters

No parameters.

Clear all data linked to previous visitors.

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

Parameters

No parameters.

Send a dynamic variable.

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

Parameters

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

Parameters

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

Parameters

• state string

  Submit state (‘attempt’ | ‘success’ | ‘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 ])

Parameters

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

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

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

• CSS_selectors string

  Comma-separated list of CSS selectors

Trigger a Session Replay after a specific event.

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

Parameters

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

Parameters

• regex RegExp

  Regular expression to exclude matching URLs from Session Replay.

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

Parameters

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

Parameters

No parameters.

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

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