Javascript SDK
Last updated
Last updated
The onsite API is used to interact with Commanders Act features with JavaScript.
There are different commands available within cact()
: config
is used to set general options, trigger
event is used to send data, and other specific get/update/revoke
commands are used to interract with platform features (ex : get user consent)
To use the API, you must have either a web container on the page or the JS SDK library script: https://cdn.tagcommander.com/events/sdk.js
The onsite API consists of a single function, cact()
, with the following strict signature:
Argument | Descriptions | Required |
---|---|---|
Onsite API is included in each containers and privacy banners.
Use the config
command to initialize and configure settings for a particular workspace.
This command is optional, you can also set custom settings directly inside a trigger
command, through the config object parameter.
The config command takes the following format:
Config object accept 4 parameters, they are optional if you use a web container on your page :
siteId
: if not set, the default value is the site id of the last web container loaded (tC.id_site
)
sourceKey
: if not set, the default value is derivative from you web container id. If you don't have a web container, the sourceKey is mandatory and correspond to your JS SDK source.
collectionDomain
: if not set, the default value is collect.commander1.com
(or your first party domain, if you setup one and use a web container)
eventId
: if not set, an random id is set for this event and will be put in context.event_id
Example :
To use the API, you must have either a web container on the page or the JS SDK library script : https://cdn.tagcommander.com/events/sdk.js
To send event data to the serverside Commanders Act platform, use this command:
Example : to send a purchase event :
Example : to send a purchase event, overriding the default tracking domain / workspace / sourcekey :
To get various values from Commanders Act, use this command:
Example : to get consent from TrustCommander, you can call the consent.get
API like this:
The onsite API methods are called asynchronously. In case e.g. you need information synchronous in the <head>
of the document it is recommended to cache and retrieve the result of the API in localStorage
.
You can handle errors through error property in the callback object. Example:
The meta
property includes metadata and context for the consent that was provided on a browser. You can see the list of Meta properties here
For advance usage, we provide also an API stub that can be added when you need to interact with the API before containers or banners have loaded. This stub is already included in containers and privacy banners, so you do not have to add in most use cases. The stub is used to buffer all methods in a JavaScript array until Commanders Act JavaScript is loaded and ready to process the methods. This allows for example to use the onsite API before TrustCommander JavaScript was loaded.
window.caReady
is a JavaScript array that buffers the interactions with the API. window.cact
is a JavaScript function used to interact with the onsite API.
In case you work in a big team and are unsure the stub was already installed it is ok to install the JavaScript stub multiple times.
Our system now includes several new and improved features to help you efficiently manage and implement tags on your website. This guide provides comprehensive information on using our TMS webcontainers and JavaScript SDK, including browser-side events, command references, and tag context variables.
Introduction
Our new cact('emit')
API is a new approach of tC.event.XXX
functions, ensuring safer and more reliable event handling.
Here’s how you can use these events:
Note that hyphens (-
) in event names will be converted to underscores (_
). For example, cact('emit', 'my-custom-event')
will actually call tC.event.my_custom_event
.
container_ready: Fires for every loaded container.
container_<siteId>_<containerId>
_ready: Fires a specific event for each containercontainer_ready
event (ex: container_1234_1_ready
)
consent-ready: Fires when the consent cookie is set or the banner is accepted/refused.
consent-updated: Fires when consent is updated.
consent-revoke: Fires when consent is revoked.
consent-signal-ready: Used for Google Consent Mode setups.
banner-show: Fires when the privacy banner is shown.
banner-hide: Fires when the privacy banner is hidden.
privacy-center-show: Fires when the privacy center is shown.
privacy-center-hide: Fires when the privacy center is closed.
tag_trigger_form_submission: Standard form trigger.
tag_trigger_clicks: Standard clicks trigger.
tag_trigger_scroll: Standard scroll trigger.
track_all_events: Server-side event sent with cact('trigger')
API.
track_*: Similar to track_all_events
but with specific event names (e.g., track_page_view
, track_add_to_cart
).
privacy-module-loaded: Internal event fired when tC.privacy
is initialized.
Custom events: Sent using cact('emit')
.
consent-update
eventYou can listen to all events using the cact('on', '*')
API.
To fire a custom trigger, use the cact('emit', 'my_custom_event')
command. Note that hyphens will be converted to underscores when launching the trigger.
You will be able to use this event as a TMS custom trigger:
The container provides a set of commands, some of which trigger browser-side events. To see all commands, type tC.cact
in your console.
config
Set various website configurations.
setProperty
Set properties to be merged with server-side events sent via the trigger API.
emit
(Alias: dispatchEvent
)
Dispatch a browser-side event for use as a custom tag trigger.
on
(Alias: addEventListener
)
Subscribe to a browser-side event.
once
Similar to on
, but the callback fires only once.
off
(Alias: removeEventListener
)
Remove an event listener.
trigger
Send a server-side event. Any call to cact('trigger', ...)
will also dispatch a generic track_all_events
event.
The Tag Context provides variables used within a tag. If you need a Tag Context similar to "Container Loaded," consider using the container_ready
custom trigger.
cact_container
Contains information about the container.
cact_event
The event that triggered the tag, with a property cact_event.type
.
cact_event_vars
Contains all event variables from the trigger.
cact_event_attrs
Contains event attributes, set using the from
property in emit
or trigger
API.
For more examples and a live demo, refer to the documentation links provided.
Resolving Site-ID/Source-Key Conflicts
In multi-container websites, events were sometimes sent with incorrect site-id or source-key. This issue is fixed for tags using triggers other than native "Container Loaded." Use the new container_ready
custom trigger for accurate site-id/source-key resolution.
Privacy-Related Events
You can use various privacy-related events as custom triggers:
consent_ready
consent_updated
consent_revoke
banner_show
banner_hide
privacy_center_show
privacy_center_hide
Server-Side Tracking as Custom Triggers
Need to track an event sent in Server Side ?
Our cact('trigger', ...)
will dispatch a corresponding track_*
event, that you can use as a custom trigger.
To use this feature as a TMS custom tag trigger, you'll need to prefix the event name with "track_*" Example:
Using cact('on')
for Event Subscription
You can subscribe to any event sent using cact('emit')
.