Tag API reference

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

Ajouté à la version : 1.1.0

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.

Ajouté à la version : 2.0.0

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.

Collect URL with custom decoded path
Section titled Collect URL with custom decoded path

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
Ajouté à la version : 7.16.0

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.

Collect URL with custom decoded query string
Section titled Collect URL with custom decoded query string

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
Ajouté à la version : 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.

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
Ajouté à la version : 11.53.0

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.

Ajouté à la version : 11.53.0

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?
Ajouté à la version : 1.1.0

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.

Setting a custom variable with the scope visit at index 5
Section titled Setting a custom variable with the scope visit at index 5
window._uxa.push(['setCustomVariable', 5, "cname", "cvalue", "visit"]);
Setting and deleting custom variables with specific scopes
Section titled 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:

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
Setting a custom variable with the scope nextPageOnly
Section titled Setting a custom variable with the scope nextPageOnly
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.

Ajouté à la version : 15.10.0

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.

Ajouté à la version : 15.10.0

Reverts the action of hidePageTitle for the next pageviews.

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

    No parameters.

Ajouté à la version : 11.5.0

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.

Creating a transaction in euros
Section titled Creating a transaction in euros
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']);
Ajouté à la version : 11.10.0

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.

Adding two items to a transaction
Section titled Adding two items to a transaction
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']);
Ajouté à la version : 10.5.0

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.

Sending a transaction with two items
Section titled Sending a transaction with two 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']);
Ajouté à la version : 10.5.0

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.

Sending an add to cart event (Merchandising customers only)
Section titled Sending an add to cart event (Merchandising customers only)
window._uxa = window._uxa || [];
window._uxa.push(['ec:cart:add', {
merchant: "Pixel patterns",
sku: "DC126O0FX-L11"
}]);
Ajouté à la version : 9.7.0

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.

Ajouté à la version : 7.12.0

Opt out the current user from data collection.

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

    No parameters.

Ajouté à la version : 13.29.0

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

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

    No parameters.

Ajouté à la version : 13.39.0

Clear all data linked to previous visitors.

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

    No parameters.

Ajouté à la version : 5.19.0

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

Sending dynamic variables for A/B testing campaigns
Section titled Sending dynamic variables for A/B testing campaigns

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"
}]);
Ajouté à la version : 9.5.0

Track a page event.

window._uxa.push(['trackPageEvent', eventName]);
  • eventName   string (<= 255 chars)  

    The name of the event to collect.

Collect when visitors save a property add for later consultation
Section titled 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
Section titled Collect user identifiers for Session Replays
Ajouté à la version : 10.17.0
window._uxa = window._uxa || [];
window._uxa.push(['trackPageEvent', '@user-identifier@' + accountID]);

See User Identifier.

Ajouté à la version : 11.8.0

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.

Ajouté à la version : 10.8.0

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
Ajouté à la version : 11.36.0

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

Send a custom error for incorrect user input
Section titled 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"
}
])
Ajouté à la version : 5.15.0

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

Ajouté à la version : 7.7.0

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.

Section titled Check visitor consent for Session Replay a on specific page
window._uxa = window._uxa || [];
_uxa.push(["afterPageView", callback]);
function callback(context) {
if (context.recordingConsentState === 2 && context.pageNumber === 42) {
displayConsentWidget();
}
}
Ajouté à la version : 13.25.0

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

Ajouté à la version : 13.55.0

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.

Session Replay data collection

Section titled Session Replay data collection
Ajouté à la version : 9.22.0

Capture elements’ text data with auto-masking enabled.

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

    Comma-separated list of CSS selectors.

Ajouté à la version : 9.28.0

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

Ajouté à la version : 11.63.0

Encrypt sensitive data in elements matched by CSS selectors.

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

    Comma-separated list of CSS selectors

Ajouté à la version : 9.5.0

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.

Ajouté à la version : 11.66.0

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.

Exclude selected ranges of product category pages
Section titled Exclude selected ranges of product category pages
window._uxa = window._uxa || [];
window._uxa.push(['excludeURLforReplay', "shoetune\\.eu.*/mens-runners.*"]);

replay:resourceManager:enableForOnlineResource:nextPageviewOnly

Section titled replay:resourceManager:enableForOnlineResource:nextPageviewOnly
Ajouté à la version : 13.53.0

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.

replay:resourceManager:getStatus

Section titled replay:resourceManager:getStatus
Ajouté à la version : 13.53.0

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.

Ajouté à la version : 4.0.1

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

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