Tag API reference
Reference of public Tag commands and their signature, and examples.
Pageview
Section titled PageviewtrackPageview
Section titled trackPageview1.1.0
Send an artificial pageview.
If run before the loading of the tag, the command will behave as setPath
.
Parameters
Section titled Parameters-
path string (optional, <= 255 chars)
The URL pathname to send.
If not set, the current documenthref
attribute is used instead. -
options object (optional)
Path options
decodeURI boolean
Single attempt to decode the provided
path
using thedecodeURI
native API. Since 13.97.0.decodeURIDeep boolean
Up to 10 attempts to fully decode the provided
path
using thedecodeURI
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
.
setPath
Section titled setPath2.0.0
Override the path to send within a pageview.
Parameters
Section titled Parameters-
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 thedecodeURI
native API. Since 13.97.0.decodeURIDeep boolean
Up to 10 attempts to fully decode the provided
path
using thedecodeURI
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
.
Examples
Section titled ExamplesCollect URL with custom decoded path
Section titled Collect URL with custom decoded pathURL is https://www.company.es/specials/campañas-y-ofertas
.
Using decodeURI
, the URL in the next pageview request is collected without encoding:
instead of:
setQuery
Section titled setQuery7.16.0
Replace a URL query string containing personal data with a masked one.
Parameters
Section titled Parameters-
queryString string
Masked query string.
-
options object (optional)
Query string options
decodeURI boolean
Single attempt to decode the provided
queryString
using thedecodeURI
native API. Since 13.97.0.decodeURIDeep boolean
Up to 10 attempts to fully decode the provided
queryString
using thedecodeURI
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
.
Examples
Section titled ExamplesCollect URL with custom decoded query string
Section titled Collect URL with custom decoded query stringURL is https://www.company.es/specials/ofertas?code=mañanas2024
.
Using decodeURI
, the query string URL in the next pageview request is collected without encoding:
instead of:
referrer:maskUrl
Section titled referrer:maskUrl11.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.
Parameters
Section titled Parameters-
url string
URL containing parameters prefixed with a colon for making purposes.
Examples
Section titled ExamplesThe referrer URL to be sent is:
By calling referrer:maskUrl
with this URL:
The referrer URL that is sent becomes:
referrer:keepQueryString
Section titled referrer:keepQueryString11.53.0
Reverts the action of referrer:removeQueryString
for the next pageview.
Examples
Section titled ExamplesThe referrer URL to be sent is:
referrer:keepQueryString
will keep the query string if referrer:removeQueryString
was used:
Parameters
Section titled ParametersNo parameters.
referrer:removeQueryString
Section titled referrer:removeQueryString11.53.0
Remove all characters in the query string.
Parameters
Section titled ParametersNo parameters.
Examples
Section titled ExamplesThe referrer URL to be sent is:
By calling referrer:removeQueryString
:
The referrer URL becomes:
setCustomVariable
Section titled setCustomVariable1.1.0
Define a custom variable to add meta information to pageviews about the page, user, or the session.
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.
Parameters
Section titled 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
, ornextPageOnly
.
Possible integer values:2
,3
, or4
.
Examples
Section titled ExamplesSetting a custom variable with the scope visit
at index 5
Section titled Setting a custom variable with the scope visit at index 5Setting and deleting custom variables with specific scopes
Section titled Setting and deleting custom variables with specific scopesSetting a custom var in both scopes (visit + page) at index 6 and named cname
value cvalue
:
To delete the custom variable:
Setting a custom variable with the scope nextPageOnly
Section titled Setting a custom variable with the scope nextPageOnlyAttach and send the custom variable to an specific artificial pageview:
After sending another artificial pageview:
The custom variable is automatically deleted.
hidePageTitle
Section titled hidePageTitle15.10.0
Replace the page title by ****
in the next pageview or in all the next pageviews.
Parameters
Section titled Parameters-
scope string
When
scope
equals toonNextPageviewOnly
, the command only affects the next pageview. Otherwise, it affects all subsequent pageviews.
Examples
Section titled ExamplesConsider the following HTML page:
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
Section titled resetHidePageTitle15.10.0
Reverts the action of hidePageTitle
for the next pageviews.
Parameters
Section titled ParametersNo parameters.
eCommerce
Section titled eCommerceec:transaction:create
Section titled ec:transaction:create11.5.0
Create transactions before adding items and sending them to Contentsquare.
Parameters
Section titled 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
Section titled ExamplesCreating a transaction in euros
Section titled Creating a transaction in eurosec:transaction:items:add
Section titled ec:transaction:items:add11.10.0
Add item to a transaction created with ec:transaction:create
.
Parameters
Section titled 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
Section titled ExamplesAdding two items to a transaction
Section titled Adding two items to a transactionec:transaction:send
Section titled ec:transaction:send10.5.0
Send a transaction containing items added with ec:transaction:items:add
to later associate a user’s session with their purchases.
Parameters
Section titled ParametersNo parameters.
Examples
Section titled ExamplesSending a transaction with two items
Section titled Sending a transaction with two itemsec:cart:add
Section titled ec:cart:add10.5.0
Register an add to cart event.
Parameters
Section titled Parameters-
merchant string (optional)
The merchant name.
-
sku string (optional)
A valid Stock Keeping Unit (SKU) code.
Examples
Section titled ExamplesSending an add to cart event (Merchandising customers only)
Section titled Sending an add to cart event (Merchandising customers only)Session
Section titled SessionextendSession
Section titled extendSession9.7.0
Extend session duration.
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
Section titled ParametersNo parameters.
optout
Section titled optout7.12.0
Opt out the current user from data collection.
Parameters
Section titled ParametersNo parameters.
session:start:newVisitor
Section titled session:start:newVisitor13.29.0
Start a new visitor and a new session.
Running the command generates new pageview.
Parameters
Section titled ParametersNo parameters.
session:clear:visitor
Section titled session:clear:visitor13.39.0
Clear all data linked to previous visitors.
Parameters
Section titled ParametersNo parameters.
Dynamic variables
Section titled Dynamic variablestrackDynamicVariable
Section titled trackDynamicVariable5.19.0
Send a dynamic variable.
Parameters
Section titled Parameters-
DYNAMIC_VARIABLE object
The dynamic variable
key string (<= 512 chars)
Dynamic variable key
value number or string (<=255 chars)
Dynamic variable value
Examples
Section titled ExamplesSending dynamic variables for A/B testing campaigns
Section titled Sending dynamic variables for A/B testing campaignsFirst user
Second user
Page event
Section titled Page eventtrackPageEvent
Section titled trackPageEvent9.5.0
Track a page event.
Parameters
Section titled Parameters-
eventName string (<= 255 chars)
The name of the event to collect.
Examples
Section titled ExamplesCollect when visitors save a property add for later consultation
Section titled Collect when visitors save a property add for later consultationCollect user identifiers for Session Replays
Section titled Collect user identifiers for Session Replays10.17.0
See User Identifier.
Sending from submit
Section titled Sending from submitsubmit
Section titled submit11.8.0
Send the submit state to the Contentsquare Tag.
Parameters
Section titled Parameters-
state string
Submit state.
Possible values:
attempt
,success
, orfailure
. -
htmlElement string
A CSS selector reference to a DOM element.
API Error Collection
Section titled API Error Collectionapi-errors:maskUrl
Section titled api-errors:maskUrl10.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.
Parameters
Section titled Parameters-
url string
Full URL of the page.
Parameters containing personal data are prefixed by a colon.
Examples
Section titled ExamplesMask order IDs
Section titled Mask order IDsThe URLs will be collected as:
Custom Error Collection
Section titled Custom Error CollectiontrackError
Section titled trackError11.36.0
Collect any text displayed on the user screen as a result of a specific action.
Parameters
Section titled 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
Section titled ExamplesSend a custom error for incorrect user input
Section titled Send a custom error for incorrect user inputIntegrations
Section titled IntegrationsgetSessionKey
Section titled getSessionKey5.15.0
Retrieves a unique Contentsquare session key.
Parameters
Section titled 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.)
afterPageView
Section titled afterPageView7.7.0
Allows to execute a callback function after a natural or artificial pageview.
Parameters
Section titled 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.
Examples
Section titled ExamplesCheck visitor consent for Session Replay a on specific page
Section titled Check visitor consent for Session Replay a on specific pagereplay:link:generate
Section titled replay:link:generate13.25.0
Generate a replay link.
Parameters
Section titled 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
).
onRecordingStateChange
Section titled onRecordingStateChange13.55.0
Track changes to replay data collection changes to avoid false positives while generating replay links.
Parameters
Section titled 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.
Session Replay data collection
Section titled Session Replay data collectionsetCapturedElementsSelector
Section titled setCapturedElementsSelector9.22.0
Capture elements’ text data with auto-masking enabled.
Parameters
Section titled Parameters-
CSS_SELECTORS string
Comma-separated list of CSS selectors.
setPIISelectors
Section titled setPIISelectors9.28.0
Mask Personal Data using specific selectors.
Parameters
Section titled 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
setEncryptionSelectors
Section titled setEncryptionSelectors11.63.0
Encrypt sensitive data in elements matched by CSS selectors.
Parameters
Section titled Parameters-
CSS_selectors string
Comma-separated list of CSS selectors
trackEventTriggerRecording
Section titled trackEventTriggerRecording9.5.0
Trigger a Session Replay after a specific event.
Parameters
Section titled Parameters-
eventName string (<= 255 chars)
The name of the event to collect that triggers the Session Replay.
excludeURLforReplay
Section titled excludeURLforReplay11.66.0
Specify a regular expression to exclude matching URLs from Session Replay data collection.
The command must be called before the Tag is loaded. The regex is kept until the next page load.
Parameters
Section titled Parameters-
regex string
Regular expression string to exclude matching URLs from Session Replay.
Examples
Section titled ExamplesExclude selected ranges of product category pages
Section titled Exclude selected ranges of product category pagesreplay:resourceManager:enableForOnlineResource:nextPageviewOnly
Section titled replay:resourceManager:enableForOnlineResource:nextPageviewOnly13.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.
Parameters
Section titled ParametersNo parameters.
replay:resourceManager:getStatus
Section titled replay:resourceManager:getStatus13.53.0
Returns information concerning the Static Resource Manager feature current state to help with implementation and troubleshooting.
The response schema from a command run is:
Parameters
Section titled ParametersNo parameters.
Webview mode
Section titled Webview modesetOption
Section titled setOption4.0.1
Enables webview mode when the Tag is managed by a mobile app opening the WebView.