Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Events are triggered as users interact with your site or app.
The data you can see in your serverside data comes from events that are triggered as users interact with your website and/or app. For example, a page_view
event is triggered each time a user views a page on your website
You can implement two types of events:
Recommended standard events are events that you implement yourself, but that have Commanders Act-predefined names and parameters. Recommended events unlock existing and future features/reporting/automatic-mapping/automatic-QA-alerting capabilities not available for custom events (events that you name yourself). Here are the events recommended for all sectors, Retail/Ecommerce/Travel/Real estate and Bank/Assurances.\
Custom events are events that you name and implement yourself. Before implementing a custom event, check that there is not a recommended event that already provides what you need. With custom events, best practice is to use recommended properties that you can find in our event references (ex: revenue, currency, ...) beside your custom properties.
Inside a standard events, you can add custom properties beside standard properties
Inside custom events, it is recommanded to put standard properties. Of course, custom properties can also be added
The JS SDK, Web container and GTM bridge add automatically specific properties in the event regarding the browser. Here is a complete event payload example :
IP Address is not collected by our libraries, but instead filled in by our servers when it receives a message for client side events only. Copying it from the request header containing the IP Address.
The following events are recommended for retail and ecommerce apps and websites. To learn how to implement these events for your website, refer to the developer documentation.
Retail and ecommerce apps should log the events listed in this article and the events for all apps. Logging events along with their prescribed parameters ensures maximum available detail in reports and lets you benefit from the latest features and integrations as they become available.
A full event is the addition of event specific information and data gathered by the SDK. For each event you'll find in the documentation "events reference" all the possible properties and the mandatory ones.
To create event, you will need to use classes from the SDK which represents the events. As this might be confusing, you'll find here a list of class name and their event counterparts.
All those class names are valid on both Android and iOS.
IOS and Android SDK add specific properties regarding the device and app. Those are in addition to event managed properties.
Here are an example of event playload :
Here are fields automatically added by the sdk.
(*) IP Address is not collected by our libraries, but instead filled in by our servers when it receives a message for client side events only.
The next fields require consent and are added when you call "addAdvertisingIDs" from the ServerSide class.
The page_view
call lets you record whenever a user sees a page of your website, along with any optional properties about the page.
Parameters (required and recommended)
Automatically added parameters by cact API for web sources
Example
Send this event to signify that a user has logged in.
Example
Use this event to contextualize search operations. This event can help you identify the most popular content in your app.
Example
This event signifies that a user has selected some content of a certain type. This event can help you identify popular content and categories of content in your app or click on internal promotion.
Example
This event indicates that a user has signed up for an account.
Example
When you send an event, it needs to carry enough information to identify which user made it. We can link events together using cookies. But destination partners require accurate identifiers to take actions.
id
and email
are usually the most useful parameters. Though some destination partners also use firstname
, lastname
, birthdate
, city
, ...
You won't always have all of those parameters. But it is recommended to send them as soon as you can during user's browsing.
About Hashing
In some cases, you won't be able to send a parameter plain value. It is either unavailable or restricted.
Every user.<property>
can be sent under hashed format with algorithm suffix: _md5
or _sha256
(underscore followed by lowercase algorithm name)
Example :
No need to send both plain and hashed values :
if you send plain value, the hashed values aren't necessary We can generate hashed values on server side using plain value
if you don't send plain value, then you should fill as much hashed values as possible Partners require different hash algorithms and without plain value, we can't generate any hash. That's why we need the exact hashed value
Field name | Example value | Description |
---|---|---|
event name | class name |
---|
COMMON SCHEMAS | class name |
---|
ENUMERATED VALUE | Class name |
---|
If you track your mobile applications without using the sdk (with the ), you should follow this specification to benefit from plug&play on destinations\
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
User contains all fields declared inside
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Field name | Example value | Description | Platform |
---|
Name | Type | Required | Example Value | Description |
---|
Name | Type | Required | Example Value | Description |
---|
Name | Type | Required | Example | Description |
---|
Name | Type | Required | Example value | Description |
---|
Name | Type | Required | Example value | Description |
---|
Name | Type | Required | Example | Description |
---|
Name | Type | Required | Example Value | Description |
---|
Thus it might be possible to send the hashed values. We currently accept 2 algorithm : and .
we only support hex (base16) encoding (i.e.: hashed values are carried by strings with [0-9a-f] characters) Other encodings are not supported yet
context.event_id
Id of the event
context.event_timestamp
Timestamp of the event sending time.
context.device.user_agent
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.0.0 Safari/537.36
The browser's user agent
context.device.lang
fr
Browser language
path
/path1/path2/
Path of the current url (only on page_view)
referrer
Referer url (only on page_view)
title
My page title
Title of the current page (only on page_view)
url
Url of the current page
page.*
pages information
when a user submits their payment information
coupon, currency, items, payment_type, value
when a user submits their shipping information
coupon, currency, items, shipping_tier, value
when a user adds items to cart
currency, items, value
when a user adds items to a wishlist
currency, items, value
when a user begins checkout
coupon, currency, items, value
when a user submits a form or request for information
value, currency
when a user completes a purchase
affiliation, coupon, currency, items, transaction_id, shipping, tax, value (required parameter)
when a refund is issued
affiliation, coupon, currency, items, transaction_id, shipping, tax, value
when a user removes items from a cart
currency, items, value
when an item is selected from a list
items, item_list_name, item_list_id
select_promotion
when a user selects a promotion
items, promotion_id, promotion_name, creative_name, creative_slot, location_id
when a user views their cart
currency, items, value
when a user views an item
currency, items, value
when a user sees a list of items/offerings
items, item_list_name, item_list_id
view_promotion
when a promotion is shown to a user
items, promotion_id, promotion_name, creative_name, creative_slot, location_id
When a user view a page
type, name
any custom event | TCCustomEvent |
add_payment_info | TCAddPaymentInfoEvent |
add_shipping_info | TCAddShippingInfoEvent |
add_to_cart | TCAddToCartEvent |
add_to_wishlist | TCAddToWishlistEvent |
begin_checkout | TCBeginCheckoutEvent |
generate_lead | TCGenerateLeadEvent |
login | TCLoginEvent |
page_view | TCPageViewEvent |
purchase | TCPurchaseEvent |
refund | TCRefundEvent |
remove_from_cart | TCRemoveFromCartEvent |
search | TCSearchEvent |
select_content | TCSelectContentEvent |
select_item | TCSelectItemEvent |
sign_up | TCSignUpEvent |
view_cart | TCViewCartEvent |
view_item | TCViewItem |
view_item_list | TCViewItemListEvent |
Item | TCItem |
Product | TCProduct |
User | TCUser |
Payment methods | ETCPaymentMethod |
Purchase status | ETCPurchaseStatus |
event_id | 8f6e05dd-6df0-476c-9c56-5d277fac7cea | A random UUID generated at the serialization of the event instance | Both |
event_timestamp | 1673571636026 | Timestamp of the event sending time. | Both |
namespace | com.tagcommander.TCDemo | The app name-space | Both |
name | TCDemo | The app name | Both |
build | 1 | The application build ID | Both |
version | 1.1 | The app version | Both |
serverside_version | 5.1.0 | The server-side module’s version | Both |
core_version | 5.1.0 | The core module’s version | Both |
consent_version | 5.3.3 | The consent module’s version | Both |
manufacturer | Apple | The manufacturer of the hardware | Both |
model | iPhone7.3 | The device model | Both |
name | maguro | The device given name | Both |
sdk_id | C32272DB0-C21E-11E4-8DFC-AA07A5B093DB | A random UUID generated at the first launch of the SDK | Both |
timezone | Europe/Paris | The detailed timezone | Both |
type | android | The os name | Both |
language | en | The device default language | Both |
region | US | The device default region | Both |
advertising_id | 705EB54D-9FC7-4730-BF1B-A5D0494E1D8C | Either IDFA or AAD | Both |
idfv | 5E35A9BA-C945-4A79-80B6-D89139471308 | IDFV | iOS |
ad_tracking_enabled | true | Has the user enabled ad tracking | Both |
consistent_anonymous_id | b5c6aa4e-0532-40c0-bf6b-a77bff46d600 | Anonymous id generated for consent. Usualy the same as sdk_id | Both |
consent_categories | ["1","2","10019","10018","13001"] | List of accepted categories | Both |
ID | "anything" | No default value but can be used by client if they need a specific ID | Both |
consentID | b5c6aa4e-0532-40c0-bf6b-a77bff46d600 | ID used to send consent information. Default to consistent_anonymous_id | Both |
name | ios | The operating system name | Both |
version | 15.5 | The OS version | Both |
width | 390 | The device’s screen width | Both |
height | 844 | The device’s screen height | Both |
density | 2 | The device’s screen density | Android |
bluetooth | false | Is the bluetooth connected | Both |
cellular | true | Is the cellular connected | Both |
carrier | T-Mobile US | Carrier's name (only when cellular is connected) | Android |
wifi | false | Is the wifi connected | Android |
session_id | F318C0D1-1DDB-4B53-9326-F2078A97CD38 | An id specific to this session | Both |
new_session | false | True if this hit is the first of a new session | Both |
session_duration | 8291 | The time spent during this session | Both |
current_session | 1655824764174 | Timestamp of the start of the current session | Both |
visit_number | 1 | Number of times the application was launched | Both |
current_visit | 1655824764174 | Timestamp of the start of the current visit | Both |
current_version_first_visit | 1655824764174 | Timestamp of the first visit for this application version | Both |
session_number | 1 | The number of sessions | Both |
first_visit | 1655824764174 | Timestamp of the first app visit | Both |
last_visit | 1655824764174 | Timestamp of the last visit | Both |
last_call | 1655824772416 | Timestamp of the previous call | Both |
last_session_start | 0 | Timestamp of the start of the previous session | Both |
last_session_last_hit | 0 | Timestamp of the last hit sent during the previous session | Both |
foreground_transitions | 2 | Number of times the app when from background to foreground | Both |
foreground_time | 8278 | Time the application spent in foreground | Both |
background_time | 0 | Time the application spent in background | Both |
first_execute | false | Is this the first hit of this cold launch | Both |
is_first_visit | true | Is this the first launch of this application. (together with first execute you can validate a new installations) | Both |
|
| Yes | product_list | Page category. Recommanded predefined types:
Equivalent to |
|
| No | Suggestion for Mother's Day | Name of the page. |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
|
| No | Products - MySite.com |
|
| No |
|
| No | /products/mothers |
|
| No |
|
| No | The method used to login. |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
|
| Yes | t-shirts | The term that was searched for. |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
|
| No | product | The type of selected content. |
|
| No | I_12345 | An identifier for the item that was selected. |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
|
| No | The method used for sign up. |
| Yes |
|
You should also add all user's properties in this user object, especially reconciliation key (id, email). |
|
| No* | 845454 | User's main identifier (e.g. CRM id) (*) required for many destinations and internal processing. |
|
| Yes* | john.doe@example.com | Email (plain value) (*) required for many destinations and internal processing. Not required if |
|
| No* | 8eb1b52... (size 32) |
|
| No* | 836f82d... (size 64) |
|
| No* | +33612345678 |
|
| No | John | First name |
|
| No | Doe | Last name |
|
| No | m | Gender
|
|
| No | 1970-01-01 | Birth date, |
|
| No | Boston | City |
|
| No | Massachusetts | State |
|
| No | 02108 | Zip code |
|
| No | USA |
|
| Yes | [1,2,3] | User's consent categories. Necessary to grant data sharing with destination partners. It is automatically filled from web sources if you use Commanders Act CMP. |
In this section, you will find all the events references supported by Commanders Act
Here are the most used events:
This event signifies a user has submitted their payment information
Parameters (required and recommended)
Example
This event signifies a user has submitted their shipping information.
Example
This event signifies that an item was added to a cart for purchase.
Parameters (required and recommended)
Example
The event signifies that an item was added to a wishlist. Use this event to identify popular gift items in your app.
Parameters (required and recommended)
Example
This event signifies that a user has begun a checkout.
Parameters (required and recommended)
Example
Log this event when a lead has been generated to understand the efficacy of your re-engagement campaigns.
Parameters (required and recommended)
Example
Send this event to signify that a user has logged in.
Example
The page_view
call lets you record whenever a user sees a page of your website, along with any optional properties about the page.
Parameters (required and recommended)
Automatically added parameters by cact API for web sources
Example
Fire this event when one or more items are purchased by a user.
Automatically added by cact API
Example
Fire this event when a purchase was refund
Automatically added by cact API
Example
This event signifies that an item was removed from a cart.
Parameters (required and recommended)
Example
Use this event to contextualize search operations. This event can help you identify the most popular content in your app.
Example
This event signifies that a user has selected some content of a certain type. This event can help you identify popular content and categories of content in your app or click on internal promotion.
Example
This event signifies an item was selected from a list.
Example
This event indicates that a user has signed up for an account.
Example
This event signifies that a user viewed their cart.
Parameters (required and recommended)
Example
This event signifies that some content was shown to the user. Use this event to manage the most popular items viewed.
Parameters (required and recommended)
Example
Log this event when the user has been presented with a list of items of a certain category.
Example
Parameters (required and recommended)
When you send an event, it needs to carry enough information to identify which user made it. We can link events together using cookies. But destination partners require accurate identifiers to take actions.
id
and email
are usually the most useful parameters. Though some destination partners also use firstname
, lastname
, birthdate
, city
, ...
You won't always have all of those parameters. But it is recommended to send them as soon as you can during user's browsing.
About Hashing
In some cases, you won't be able to send a parameter plain value. It is either unavailable or restricted.
Thus it might be possible to send the hashed values. We currently accept 2 algorithm : md5
and sha256
.
Every user.<property>
can be sent under hashed format with algorithm suffix: _md5
or _sha256
(underscore followed by lowercase algorithm name)
Example :
No need to send both plain and hashed values :
if you send plain value, the hashed values aren't necessary We can generate hashed values on server side using plain value
if you don't send plain value, then you should fill as much hashed values as possible Partners require different hash algorithms and without plain value, we can't generate any hash. That's why we need the exact hashed value
Enumerated Values for payment methods :
Enumerated Values for purchase status:
Here is the list of all properties for video events
Commanders Act's video specification lets you define how a customer engages with your videos and the related ad content.
This documentation details the conventions and best practices for sending events when tracking videos. The document clarifies the structure and classification of these events, which fall into four categories: Playback
, Content
, Ads
and Video Settings
.
Playback events are tied to the actual playback of video content and track information about the video player.
For example, when a customer plays a video on an app, a Video Playback Started event is sent along with a unique session_id. All subsequent events generated from that session are tied to the same session_id.
If a web page has two video players, there will be two separate sessions and associated session_ids. However, if two separate videos are played on the same video player, they will still be considered a single session with two associated pieces of content.
All the playback events share the same properties that describe the current state of the video player.
The following table lists all the properties of this playback event object in detail:
This section details all the video playback events.
For more information on each of the properties associated with these events, refer to the Playback Event Properties section.
This event is associated with the user action of pressing the play button on the video player to initiate the video playback.
A sample event is as shown below:
This event corresponds to the user action of pausing the video playback.
A sample event is as shown:
This event is sent when the video playback stops unintentionally. Network loss, user closing the browser, redirect, etc. are some of the common reasons. You can pass the cause within the property interruption_method
.
A sample event is as shown:
This corresponds to the event of buffering content or an advertisement.
A sample event is as shown:
This corresponds to the event when the playback finishes buffering the content or an advertisement.
A sample event is as shown:
This event is sent when a user manually seeks a certain cursor position of the video content or an advertisement in the playback. The cursor_position
property indicates where the user is seeking from (time in seconds) and the seek_position
indicates the cursor position in the playback where the user is seeking to.
A sample event is as shown:
This event is sent after a user manually seeks to a certain cursor position of the video or ad in the playback. The cursor_position
property indicates where the user resumes the playback.
A sample event is as shown:
This event is sent after the user resumes the video playback after it was paused.
A sample event is as shown:
This event is sent after the playback is complete and when the pod session is finished. Note that the cursor_position
property has the same value as the total_length
property.
A sample event is as shown:
A content pod refers to a part / group / segment of the video content or the advertisement within the playback.
Suppose a video playback session has a video and one mid-roll advertisement. This means that the mid-roll ad splits the playback in two separate content pods. The mid-roll ad is included within a single ad pod.
The flow is as follows:
User starts and completes the first content pod
User starts and completes the ad
User starts and completes the second content pod
All of these events within the flow happen within one video playback.
All the content events share the same properties that describe the current state of the video content that is viewed by the user during the playback.
The following table lists all the properties of this playback event object in detail:
This section details all the video content events.
This event is sent once the user starts playing video content segment within a playback.
A sample event is as shown:
These events are sent as heartbeats every after a set interval to indicate the length of video viewed by the user, determined by the cursor_position
property.
A sample event is as shown:
These events are sent when a quarter of the video is reached, determined by the cursor_position
property.
A sample event is as shown:
This event is sent once the video segment within the playback is completed. Note that the cursor_position
property has the same value as the total_length
property.
A sample event is as shown:
All the ad events share the same properties that describe the current state of the video ad content that a user is interacting with during the playback.
The following table lists all the properties of this ad event object in detail:
This section details all the ad events.
For more information on each of the properties associated with these events, refer to the Ad Event Properties section.
This event is sent when an advertisement roll starts playing within the video playback.
A sample event is as shown:
This event is sent between set intervals when the video ad is playing and is determined by the cursor_position
property.
A sample event is as shown:
This event is sent after the user has viewed a video ad completely. Note that the cursor_position
property has the same value as the total_length
property.
This event is sent after the user has viewed the video ad roll completely. Note that the cursor_position
property has the same value as the total_length
property.
This event is sent when the user click on the skip ad button.
This event is sent when an advertisement break starts playing while the video playback.
A sample event is as shown:
This event is sent after the user has viewed the video ad break pod completely. Note that the cursor_position
property has the same value as the total_length
property.
This event is sent when the user click on the add.
All the settings events share the same properties that describe the current state of the video content that a user is interacting with during the playback.
This section details all the video settings events.
This event is sent when the user modify the audio volume of the video player.
A sample event is as shown below:
This event is sent when the user modify the speed of the video player.
A sample event is as shown below:
This event is sent when the user turns on the subtitles of the video player.
A sample event is as shown below:
This event is sent when the user turns off the subtitles of the video player.
A sample event is as shown below:
This event is sent when the user turns on the full screen view of the video player.
A sample event is as shown below:
This event is sent when the user turns off the full screen view of the video player.
A sample event is as shown below:
This event is sent when the video quality of the video player is modified.
A sample event is as shown below:
This event is sent when the video is shared by the user.
A sample event is as shown below:
Every Video Playback Resumed
the event should be followed by an event Video Content Playing
or a Video Ad Playing
event, depending on what asset the playback resumes to.
Commanders Act also lets you track and analyze the performance and quality of your video content during the playback.
Whenever a user changes the video quality during playback, you can track a Video Quality Updated event along with the following properties:
bitrate
: Denotes the updated bit rate in kbps
.
framerate
: Denotes the updated frame rate in fps
.
startupTime
: Denotes the time when the video quality was changed by the user.
droppedFrames
: Indicates if any frames were dropped during the video quality change.
The following event flow demonstrates how you can implement the Commanders Act video specification:
Ads that appear before the start of the video playback are called pre-roll ads.
Ads that appear in the middle of the playback are mid-roll ads.
Ads that appear after the video playback are called post-roll ads.
These ads can be a promotional video by the sponsors or a piece of content offered by the content provider.
Title of the page : from the DOM API
Full URL of the page. Equivalent to from the DOM API.
Path portion of the URL of the page : from the DOM API.
Full URL of the previous page : from the DOM API.
Email, hashed using . Not required if email
is provided (see below)
Email, hashed using . Not required if email
is provided (see below)
Phone number, format (*) required for some destinations.
Country code, ISO 3166-1 or formats
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
we only support hex (base16) encoding (i.e.: hashed values are carried by strings with [0-9a-f] characters) Other encodings are not supported yet
Property | Value |
---|---|
Property | Value |
---|---|
Property | Events using this property | Type |
---|
Property | Type | Required | Description |
---|
Property | Type | Required | Description |
---|
For more information on each of the properties associated with these events, refer to the section.
Property | Type | Required | Description |
---|
Property | Type | Required | Description |
---|
For more information on each of the properties associated with these events, refer to the section.
payment_method
string
Yes
card
The chosen method of payment (see list of possible values below)
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list and is mandatory to manage consents. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
revenue
number
No
16.00
Revenue (shipping price and taxes excluded) after discount.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
items
No
The items for the event.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
or value
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
shipping_tier
string
No
Ground
The shipping tier (e.g. Next-day
, Air`) selected for delivery of the purchased item.
items
Yes
The items for the event.
value
number
Yes*
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
value
number
No
8.00
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
value
number
No*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
id
string
No
Lead id
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
method
string
No
The method used to login.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
page_type
string
Yes
product_list
Page category. Recommanded predefined types:
home
landing
product_list
product
content_list
content
search
funnel
success
funnel_confirmation
account
cart
legal (e.g. Privacy Policy)
Equivalent to tc_vars.env_template
page_name
string
No
Suggestion for Mother's Day
Name of the page.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
title
string
No
Products - MySite.com
Title of the page :document.title
from the DOM API
url
string
No
Full URL of the page. Equivalent tolocation.href
from the DOM API.
path
string
No
/products/mothers
Path portion of the URL of the page : location.pathname
from the DOM API.
referrer
string
No
Full URL of the previous page : document.referrer
from the DOM API.
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Tax associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
items
Yes
The items for the event.
payment_method
string
Yes
card
Payment method type (see list of possible values below)
status
string
Yes
in_progress
Status of the conversion (see list of possible values below). Conversions with status "pending" are not included in default sum and counts aggregated on augmented user attributes feature
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Shipping cost associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
items
No*
(*) items
is required for partial refunds but it can be omitted for full refunds.
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
search_term
string
Yes
t-shirts
The term that was searched for.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
content_type
string
No
product
The type of selected content.
item_id
string
No
I_12345
An identifier for the item that was selected.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
items
Yes
The items for the event. The items
array is expected to have a single element, representing the selected item.
method
string
No
The method used for sign up.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
revenue
number
Yes*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
id
string
Yes
SKU_12345
The ID of an item.
If you don't have an item id, you can use the product id as value. This field is used as key for updates (ex : refund)
product
Yes
The product details
variant
string
No
red
The variant of the item.
list_position
number
No
1
The item's position in a list or collection.
discount
number
No
2.00
Monetary value of discount for one current item
quantity
number
Yes
2
The quantity of the item.
affiliation
string
No*
DOWNLOAD
Required for most affiliation's destination.
coupon
string
No
CHRISTMAS
The coupon code associated with an item.
id
string
Yes*
12345
The ID of the product (ex: in your product catalog database)
The item.id
and product.id
do not have to be different. If they are different, typically the product.id
is a database identifier, like 9714107479
and the item.id
is a public-facing identifier like SKU-12345
.
(*) If you have imported your product's catalog in the platform, the product.id
corresponds to the unique product id in the catalog and can be used with id expansion feature.
name
string
Yes
Trex
Product name
price
number
Yes
14.99
The price of the product (taxes and discount excluded)
currency
string (ISO 4217)
No
EUR
Currency of the price
, in 3-letter ISO 4217 format.
If set, event-level currency
is ignored.
Multiple currencies per event is not supported. Each item should set the same currency.
category_1
string
No
T-Shirts
Product Category (context-specific). item_category2
through item_category5
can also be used if the product has many categories.
brand
string
No
Lacoste
Product brand
colors
Array[string]
No
[blue, white]
The color(s) of the product
size
string
No
128
Size of the article
id
string
No*
845454
User's main identifier (e.g. CRM id)
(*) required for many destinations and internal processing.
email
string
Yes*
john.doe@example.com
Email (plain value)
(*) required for many destinations and internal processing. Not required if email_sha256
is provided
email_md5
string
No*
8eb1b52... (size 32)
Email, hashed using MD5 algorithm. Not required if email
is provided (see below)
email_sha256
string
No*
836f82d... (size 64)
Email, hashed using SHA-256 algorithm. Not required if email
is provided (see below)
phone
string
No*
+33612345678
Phone number, E.164 format (*) required for some destinations.
firstname
string
No
John
First name
lastname
string
No
Doe
Last name
gender
string
No
m
Gender
f
for Female
m
for Male
birthdate
string
No
1970-01-01
Birth date, YYYY-MM-DD
format
city
string
No
Boston
City
state
string
No
Massachusetts
State
street
string
No
303 Sumner St
Street address
zipcode
string
No
02108
Zip code
country
string
No
USA
consent_categories
Array
Yes
[1,3,4]
User's consent categories. It should contain only the categories where the user has given his consent. Necessary to grant data sharing with destination partners. It is automatically filled from web sources if you use Commanders Act CMP.
status
string
No
New
Status as reported in your CRM (E.g. "New", "Existing", "Premium")
payment_method
by_invoice
payment_method
by_bank_transfer_in_advance
payment_method
card
payment_method
check_in_advance
payment_method
cod
payment_method
coupon
payment_method
direct_debit
payment_method
online_payment_system
payment_method
other
status
canceled
status
delivered
status
in_progress
status
partially_delivered
status
partially_returned
status
partially_shipped
status
pending_shipment
status
returned
status
shipped
status
pending
|
| Yes | A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events. |
|
| No | Denotes the title of the video content. |
|
| No | Denotes the genre of the video content asset. |
|
| No | Denotes the publisher / creator / author of the video content asset. |
|
| Yes | Content asset ID/s of the video/s playing or about to be played. For of unique asset IDs should be sent. For other playback events, a singular content asset ID at the time of the event should be sent. |
|
| No | Content pod ID/s of the video/s playing or about to be played. For of unique pod IDs should be sent. For other playback events, a singular content pod ID associated with the current content pod at the time of the event should be sent. |
|
| No | Ad asset ID/s of the video/s playing or about to be played. For of unique ad asset IDs should be sent. For other playback events, a singular ad asset ID at the time of the event should be sent. |
|
| No | Ad pod ID/s of the video/s playing or about to be played. For of unique ad pod IDs should be sent. For other playback events, a singular content pod ID associated with the current ad pod at the time of the event should be sent. |
|
| No | Denotes the type of ad playing at the time of the event. The values can be ' ' |
|
| Yes | Denotes the current index position of the playhead
in seconds. It includes the duration of any seen ads.
Not required in |
|
| No | Denotes the index position of the playhead where the user is seeking to. Only applicable on the the |
|
| Yes | Denotes the total duration of the video playback in seconds. Includes the whole duration of all the content and ads included in the session. Set to |
|
| No | Bit rate of the video playback, denoted in |
|
| No | Denotes the average frame rate of the video
playback in |
|
| No | Denotes the name of the video player used for playback. Example: |
|
| No | Denotes the sound level of the video playback. Range is from 0-100, where 0 represents mute and 100 is full volume. |
|
| No | Set to |
|
| No | Set to If the user can view your video ads, it is set to
|
|
| No | Specifies the quality of the video. Examples: 'hd1080', 'highres' |
|
| No | For the playback was interrupted. Some examples include 'device_lock', 'call', and 'browser_redirect'. |
|
| No | Set to |
|
| Yes | A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events. |
|
| Yes | Denotes the unique ID of the video content asset. |
|
| No | Denotes the unique ID of the video content pod. |
|
| No | Denotes the title of the video content. |
|
| No | Describes the video content asset in short. |
|
| No | Denotes the relevant keywords associated with the categorizing the video content |
|
| No | Denotes the season number, if applicable. |
|
| No | Denotes the episode number, if applicable. |
|
| No | Denotes the genre of the video content asset. |
|
| No | Denotes the name of the program / show of which the video content is a part. |
|
| No | Denotes the publisher / creator / author of the video content asset. |
|
| No | Denotes the channel in which the video content is playing. |
|
| No | Set to |
| Boolean | No | If the video content is a live stream, this is set to
|
|
| No | Denotes the original date of airing / publishing the video content. |
|
| Yes | Denotes the current playhead position into the video content in seconds. This does not include any ads played in this duration. In case of live streams, refer to the relevant destination's documentation for details on how to pass this property. |
|
| Yes | The total duration of the video content in seconds. This does not include any ads included in the playback of this content asset. For livestream playback, this should be set to |
|
| No | Denotes the current bit rate in |
|
| No | Denotes the frame rate in |
|
| Yes | A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events. |
|
| Yes | Denotes the unique ID of the ad asset. |
|
| Yes | Denotes the unique ID of the ad pod. |
|
| No | Denotes the position of the ad asset relative to other ads in the same pod. |
|
| No | Denotes the type of ad playing at the time of the event. The values can be ' ' |
|
| No | Denotes the number of ad assets in the current ad pod. |
|
| No | Denotes the title of the ad. |
|
| No | Denotes the author/ creator/ publisher of the ad. |
|
| Yes | The current playhead position in relation to the total length of the ad, in seconds. |
|
| Yes | Denotes the total length of the ad asset in seconds. |
|
| No | Denotes if the ads are loaded dynamically or if they are the same for all the users.
Values can be either ' |
|
| No | For the can be used to indicate when a specific ad quartile is reached. If you are using a client-side library to track your video events, this property is optional as Commanders Act automatically tracks the ad quartiles. |
|
| Yes | A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events. |
|
| Yes | Denotes the unique ID of the video content asset. |
|
| No | Denotes the unique ID of the video content pod. |
|
| No | Denotes the unique ID of the ad asset. |
|
| No | Denotes the unique ID of the ad pod. |
|
| No | Denotes the type of ad playing at the time of the event. The values can be ' ' |
|
| No | Denotes the title of the video content. |
|
| No | Describes the video content asset in short. |
|
| No | Denotes the relevant keywords associated with the categorizing the video content |
|
| No | Denotes the season number, if applicable. |
|
| No | Denotes the episode number, if applicable. |
|
| No | Denotes the genre of the video content asset. |
|
| No | Denotes the name of the program / show of which the video content is a part. |
|
| No | Denotes the publisher / creator / author of the video content asset. |
|
| No | Denotes the channel in which the video content is playing. |
|
| No | Set to |
|
| No | If the video content is a live stream, this is set to
|
|
| No | Denotes the original date of airing / publishing the video content. |
|
| Yes | Denotes the current playhead position into the video content in seconds. This does not include any ads played in this duration. In case of live streams, refer to the relevant destination's documentation for details on how to pass this property. |
|
| Yes | The total duration of the video content in seconds. This does not include any ads included in the playback of this content asset. For livestream playback, this should be set to |
|
| Yes | Denotes the current bit rate in |
|
| No | Denotes the frame rate in |
|
| Yes | Denotes the current video sound level Required in |
|
| Yes | Denotes the current video screen mode.
Required in |
|
| No | Denotes if ad were enabled |
|
| Yes | Denotes the current video queity resolution.
Required in |
In this section, you will find all the properties references
There is a tab global properties, which includes all commons properties including e-commerce properties, and there is a tab video properties, dedicated only to video events properties
video_session_id | All video events |
|
content_asset_id | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete * video_share |
|
content_pod_id | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete * video_share |
|
ad_asset_id | * video_start * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
ad_pod_id | * video_start * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
ad_type | * video_start * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
cursor_position | All video events |
|
seek_position | * video_seek_start * video_seek_complete |
|
total_length | All video events |
|
bitrate | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_content_playing * video_share |
|
framerate | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_content_playing * video_share |
|
video_player | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_share |
|
sound | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_share |
|
full_screen | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_share |
|
ad_enabled | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_share |
|
image_quality | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_share |
|
livestream | * video_start * video_pause * video_error * video_buffer_start * video_buffer_complete * video_seek_start * video_seek_complete * video_resume * video_complete * video_content_start * video_share |
|
video_title | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
video_description | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
keywords | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
season | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
episode | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
video_category | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
program | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
publisher | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
channel | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
full_episode | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
airdate | * video_content_start * video_content_playing * video_content_quarter_reached * video_content_complete |
|
pod_position | * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
pod_length | * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
load_type | * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
content | * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
ad_quartile | * video_ad_start * video_ad_playing * video_ad_stop * video_ad_complete * video_ad_skip * video_ad_break_start * video_ad_break_complete * video_ad_click |
|
interruption_method | * video_error |
|
user | All video events |
This event is associated with your ad being displayed, can be used to track the touch point "impressions" in Campaign Analytics module
This event is associated with someone clicking your ad, can be used to track the touch point "clicks" in Campaign Analytics module
Example
To create touch points 'sites' and 'orders' you can use the following events:
'page_view' to create a touch point 'sites'
'purchase' to create a touch point 'orders'
Returns the list of segments for the user
https://api.commander1.com/api/dms/segmentation/segments
GET
https://api.commander1.com/api/dms/segmentation/segments?site=1234&callback=tC_funcEngage
Returns the list of segments created in Engage UIX
https://api.commander1.com/api/dms/segmentation/segments/list
GET
https://api.commander1.com/api/dms/segmentation/segments/list?site=1234&token=WvNIX8955cnZ7WF0f632s0Wb99Ql3rtA
Here is the list of all properties for common and e-commerce events
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Response formats | javascript (JSONP) |
---|---|
NAME | REQUIREMENT | EXAMPLE VALUES | DESCRIPTION |
---|---|---|---|
Response formats | JSON |
---|---|
NAME | REQUIREMENT | EXAMPLE VALUES | DESCRIPTION |
---|---|---|---|
Property | Events using this property | Type |
---|---|---|
ad_cost_id
string
No
1254965
replace the tclid
from MixCommander
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
ad_format
string
No
image
Ad type/format
campaign
string
No
my_campaign
campaign name
keyword
string
No
t-shirt
keywords of the campaign
medium
string
Yes
seo
medium of touch point
source
string
Yes
my_source
source of touch point
Requires authentication?
No if tcid is not set, token if tcid is set
site
\d+
1234
Id of the site to query detail for
tcid (optional)
\d+
1234
Id of the tcid (if cookie is disable)
token (optional)
[a-zA-Z0-9]*
WvNIX8955cnZ7WF0f632s0Wb99Ql3rtA
Security token (if tcid is set)
callback
\w+
do_something
javascript callback method for JSONP
Requires authentication?
Yes (token)
site
d+
1234
Id of the site to query detail for
token
[a-zA-Z0-9]*
WvNIX8955cnZ7WF0f632s0Wb99Ql3rtA
Security token
content_type
* select_content
string
coupon
* add_payment_info
* add_shipping_info
* begin_checkout
* purchase
* refund
string
currency
* purchase
* refund
* begin_checkout
* add_to_cart
* add_payment_info
* add_shipping_info
* add_to_wishlist
* generate_lead
* remove_from_cart
* view_cart
string (ISO 4217)
id
* purchase
* generate_lead
* refund
string
items
* add_shipping_info
* add_to_cart
* add_to_wishlist
* begin_checkout
* remove_from_cart
* select_item
* view_cart
* view_item
* view_item_list
* purchase
* add_payment_info
* refund
item_id
* select_content
string
item_list_name
* select_item
* view_item_list
string
method
* login
* sign_up
string
page_name
* page_view
string
page_type
* page_view
string
payment_method
* purchase
* add_payment_info
string
revenue
* add_payment_info
* begin_checkout
* view_item
* purchase
* refund
number
search_term
* search
string
shipping_amount
* purchase
* refund
number
shipping_tier
* add_shipping_info
string
status
* purchase
string
tax_amount
* purchase
* refund
number
type
* purchase
* refund
string
user
All events
value
* purchase
* refund
* begin_checkout
* add_to_cart
* add_payment_info
* add_shipping_info
* add_to_wishlist
* generate_lead
* remove_from_cart
* view_cart
number
This event signifies a user has submitted their payment information
Parameters (required and recommended)
Example
This event signifies a user has submitted their shipping information.
Example
This event signifies that an item was added to a cart for purchase.
Parameters (required and recommended)
Example
The event signifies that an item was added to a wishlist. Use this event to identify popular gift items in your app.
Parameters (required and recommended)
Example
This event signifies that a user has begun a checkout.
Parameters (required and recommended)
Example
Log this event when a lead has been generated to understand the efficacy of your re-engagement campaigns.
Parameters (required and recommended)
Example
Fire this event when one or more items are purchased by a user.
Automatically added by cact API
Example
Fire this event when a purchase was refund
Automatically added by cact API
Example
This event signifies that an item was removed from a cart.
Parameters (required and recommended)
Example
This event signifies an item was selected from a list.
Example
This event signifies that a user viewed their cart.
Parameters (required and recommended)
Example
This event signifies that some content was shown to the user. Use this event to manage the most popular items viewed.
Parameters (required and recommended)
Example
Log this event when the user has been presented with a list of items of a certain category.
Example
Parameters (required and recommended)
When you send an event, it needs to carry enough information to identify which user made it. We can link events together using cookies. But destination partners require accurate identifiers to take actions.
id
and email
are usually the most useful parameters. Though some destination partners also use firstname
, lastname
, birthdate
, city
, ...
You won't always have all of those parameters. But it is recommended to send them as soon as you can during user's browsing.
About Hashing
In some cases, you won't be able to send a parameter plain value. It is either unavailable or restricted.
Thus it might be possible to send the hashed values. We currently accept 2 algorithm : md5
and sha256
.
Every user.<property>
can be sent under hashed format with algorithm suffix: _md5
or _sha256
(underscore followed by lowercase algorithm name)
Example :
No need to send both plain and hashed values :
if you send plain value, the hashed values aren't necessary We can generate hashed values on server side using plain value
if you don't send plain value, then you should fill as much hashed values as possible Partners require different hash algorithms and without plain value, we can't generate any hash. That's why we need the exact hashed value
Enumerated Values for payment methods :
Enumerated Values for purchase status:
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
Name | Type | Required | Example Value | Description |
---|---|---|---|---|
we only support hex (base16) encoding (i.e.: hashed values are carried by strings with [0-9a-f] characters) Other encodings are not supported yet
Property | Value |
---|---|
Property | Value |
---|---|
payment_method
string
Yes
card
The chosen method of payment (see list of possible values below)
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list and is mandatory to manage consents. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
revenue
number
No
16.00
Revenue (shipping price and taxes excluded) after discount.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
items
No
The items for the event.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
or value
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
shipping_tier
string
No
Ground
The shipping tier (e.g. Next-day
, Air`) selected for delivery of the purchased item.
items
Yes
The items for the event.
value
number
Yes*
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
value
number
No
8.00
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
value
number
No*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
No*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
id
string
No
Lead id
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Tax associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
items
Yes
The items for the event.
payment_method
string
Yes
card
Payment method type (see list of possible values below)
status
string
Yes
in_progress
Status of the conversion (see list of possible values below). Conversions with status "pending" are not included in default sum and counts aggregated on augmented user attributes feature
last_channel
string
No
display
The last channel just before the purchase.
last_source
string
No
google.com
The last source (referrer) just before the purchase.
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
id
string
Yes
O_1245
Transaction id. Used as key for updates
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
All properties that you add here will be used as conditions for matching users in our database.
cosent_categories
is automatically filled if you use Commanders Act CMP.
revenue
number
Yes
16.00
The monetary value of the event (shipping price and taxes excluded) after discount
value
number
Yes
22.53
The monetary value of the event (shipping price and taxes included) after discount
shipping_amount
number
No
3.33
Shipping cost associated with a transaction.
tax_amount
number
No
3.20
Shipping cost associated with a transaction.
currency
string (ISO 4217)
Yes
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
coupon
string
No
CHRISTMAS
Coupon code used for a purchase.
type
string
Yes
offline
Type of conversion (online, offline, call etc.)
items
No*
(*) items
is required for partial refunds but it can be omitted for full refunds.
url
string(url)
No
none
URL to the website where you can buy the item
Equivalent to window.location.href
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
items
Yes
The items for the event. The items
array is expected to have a single element, representing the selected item.
value
number
No
8.00
The monetary value of the event.
()value
is typically required for meaningful reporting.
()currency
is required if you set value
.
currency
string (ISO 4217)
No
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
(*) If you supply the revenue
parameter, you must also supply the currency
parameter so revenue metrics can be computed accurately.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
revenue
number
Yes*
9.99
The monetary value of the event.
()revenue
is typically required for meaningful reporting.
()currency
is required if you set revenue
.
currency
string (ISO 4217)
Yes*
EUR
Currency of the purchase or items associated with the event, in 3-letter ISO 4217 format.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
item_list_name
string
No
Related products
The name of the list in which the item was presented to the user.
user
Yes
{
id: '12345',
email: 'toto@domain.fr',
consent_categories: [1,3]
}
consent_categories
is the user's consents list. It is automatically filled from web sources if you use Commanders Act CMP.
You should also add all user's properties in this user object, especially reconciliation key (id, email).
items
Yes
The items for the event.
id
string
Yes
SKU_12345
The ID of an item.
If you don't have an item id, you can use the product id as value. This field is used as key for updates (ex : refund)
product
Yes
The product details
variant
string
No
red
The variant of the item.
list_position
number
No
1
The item's position in a list or collection.
discount
number
No
2.00
Monetary value of discount associated with a purchase
quantity
number
Yes
2
The quantity of the item.
affiliation
string
No*
DOWNLOAD
Required for most affiliation's destination.
coupon
string
No
CHRISTMAS
The coupon code associated with an item.
id
string
Yes*
12345
The ID of the product (ex: in your product catalog database)
The item.id
and product.id
do not have to be different. If they are different, typically the product.id
is a database identifier, like 9714107479
and the item.id
is a public-facing identifier like SKU-12345
.
(*) If you have imported your product's catalog in the platform, the product.id
corresponds to the unique product id in the catalog and can be used with id expansion feature.
name
string
Yes
Trex
Product name
price
number
Yes
14.99
The price of the product
currency
string (ISO 4217)
No
EUR
Currency of the price
, in 3-letter ISO 4217 format.
If set, event-level currency
is ignored.
Multiple currencies per event is not supported. Each item should set the same currency.
category_1
string
No
T-Shirts
Product Category (context-specific). item_category2
through item_category5
can also be used if the product has many categories.
brand
string
No
Lacoste
Product brand
colors
Array[string]
No
[blue, white]
The color(s) of the product
size
string
No
128
Size of the article
id
string
No*
845454
User's main identifier (e.g. CRM id)
(*) required for many destinations and internal processing.
email
string
Yes*
john.doe@example.com
Email (plain value)
(*) required for many destinations and internal processing. Not required if email_sha256
is provided
email_md5
string
No*
8eb1b52... (size 32)
Email, hashed using MD5 algorithm. Not required if email
is provided (see below)
email_sha256
string
No*
836f82d... (size 64)
Email, hashed using SHA-256 algorithm. Not required if email
is provided (see below)
phone
string
No*
+33612345678
Phone number, E.164 format (*) required for some destinations.
firstname
string
No
John
First name
lastname
string
No
Doe
Last name
gender
string
No
m
Gender
f
for Female
m
for Male
birthdate
string
No
1970-01-01
Birth date, YYYY-MM-DD
format
city
string
No
Boston
City
state
string
No
Massachusetts
State
zipcode
string
No
02108
Zip code
country
string
No
USA
consent_categories
Array
Yes
[1,2,3]
User's consent categories. Necessary to grant data sharing with destination partners. It is automatically filled from web sources if you use Commanders Act CMP.
payment_method
by_invoice
payment_method
by_bank_transfer_in_advance
payment_method
card
payment_method
check_in_advance
payment_method
cod
payment_method
coupon
payment_method
direct_debit
payment_method
online_payment_system
payment_method
other
status
canceled
status
delivered
status
in_progress
status
partially_delivered
status
partially_returned
status
partially_shipped
status
pending_shipment
status
returned
status
shipped
status
pending