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.
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:
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
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 , and .\
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 (ex: revenue, currency, ...) beside your custom properties.
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
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.
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.
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 |
---|
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
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 |