Custom events
Custom events are a group of events that are manually tailored for each customer. As opposed to system events, custom events included in different projects greatly vary as it is your choice which of them you decide to incorporate. This article lists and explains the most commonly used custom events and attributes. If you want to learn how to set up their tracking, go to our Web tracking article.
Location,os,device&browserare already tracked by default in every event usingexponea.track()function of the SDK. If you want to add some more default properties TO EVERY EVENT then you can use thetrack.default_properties. If you need it only for some events, you can also update the events individually. Find out more.
purchase
purchase happens when the customer purchases a product/products on your website.
| Attribute | Description | Example |
|---|---|---|
| purchase_id | Automatically-generated ID of the purchase. | 123456a |
| purchase_status | Status of the purchase. | success / refund |
| purchase_source_type | Type of the source from which the purchase was done. | online / store |
| purchase_source_name | Name of the source from which the purchase was done. | domain.com / Corner Store 1st Street, ... |
| product_list | List of all purchased products, their quantities and other required properties. | [ {"product_id": "abc123", "quantity":1} ] |
| product_ids | List of IDs of all purchased products. | [ "abc123", "abc456", "abc789" ] |
| total_price | Total price paid by the customer in the reference currency including tax and shipping. | 24 |
| total_price_without_tax | Total price paid by customer in reference currency including shipping but not the tax. | 20 |
| total_price_local_currency | Total price paid by the customer in the currency they used for the payment. | 2 |
| local_currency | Currency the customer used for the payment. | USD, GBP, EUR |
| total_quantity | Total quantity of the products purchased. | 2 |
| payment_type | Payment method. | bank transfer / online payment / cash / cod |
| shipping_type | Type of delivery. | courier / personally |
| shipping_company | Delivery company. | ups |
| shipping_cost | Price of the delivery. | 69 |
| shipping_country | Name of the country to which the products are delivered. | USA |
| shipping_city | Name of the city to which the products are delivered. | New York |
| tax_percentage | Sales tax expressed as a percentage. | 20 |
| tax_value | Sales tax expressed as money. | 4 |
| voucher_code | Code of the voucher used in this purchase. | KA54-548C |
| voucher_percentage | The discount rate conferred on the customer by the voucher expressed as a percentage. | 10 |
| voucher_value | The amount that the voucher subtracted from the prize of the purchase. | 2 |
| variant_list | List of all purchased variants, their quantities and other required properties. | [ {"variant_id": "abc123", "quantity":1} ] |
| variant_ids | List of IDs of all purchased variants. | [ "abc123", "abc456", "abc789" ] |
| language | Language of website from which the purchase was made. | en |
| location | URL of the page where the purchase event occurred. | https://webshop.com/purchase |
| domain | Default domain of your website. | webshop.com |
purchase_item
purchase_item happens when the customer purchases a product on your website. For each item within a purchase, a separate purchase_item should also be rendered. There should be as many purchase_item events along with a single purchase event as there were items bought.
| Attribute | Description | Example |
|---|---|---|
| purchase_id | Automatically-generated ID of the purchase. | 123456a |
| purchase_status | Status of the purchase. | success / refund |
| purchase_source_type | Type of the source from which the purchase was done. | online / store |
| purchase_source_name | Name of the source from which the purchase was done. | domain.com / Corner Store 1st Street, ... |
| product_id | Automatically-generated ID of the product. | abc123 |
| variant_id | Automatically-generated ID of the variant of the product that includes information about colour, size or materials. | abc123small |
| title | Item name that includes colour, size or materials if available. | Tassel Loafers in Navy Faux Sued |
| brand | Brand of the purchased item. | END. |
| price | Price of one unit of the item paid by the customer in the reference currency. | 18 |
| price_local_currency | Price of one unit of the item paid by the customer in the currency they used for the payment. | 90 |
| discount_percentage | In case of a discount, the discount rate used on the item expressed as a percentage. | 10 |
| discount_value | In case of a discount, the amount subtracted from the price of the product as a result of the discount. | 2 |
| original_price | Price of the item without a discount in a reference currency. | 20 |
| original_price_local_currency | Price of the item without a discount in a currency the customer used for the payment. | 100 |
| quantity | Quantity of the purchased products. | 2 |
| total_price | Total price paid by the customer in the reference currency including tax and shipping. | 24 |
| total_price_without_tax | Total price paid by the customer in reference currency including shipping but not the tax. | 20 |
| total_price_local_currency | Total price paid by the customer in the currency they used for the payment. | 43 |
| local_currency | Currency the customer used for the payment. | USD, GBP, EUR |
| tags | Custom tags for describing the item. | ["new", "sales", "teen", "man"] |
| category_1 | Top level category of products on the website where the item can be found. | Shoes |
| category_2 | Second level category of products on the website where the item can be found. | Trekking |
| category_3 | Third level category of products on the website where the item can be found. (number of categories is not limited to 3) | Ankle boots |
| categories_path | Path through the categories leading to the product. | Shoes > Trekking > Ankle boots |
| category_id | Automatically-generated ID of the final category where the purchased product belongs. | abc123 |
| categories_ids | List of IDs of all categories from root until the final one where the purchased product belongs. | ["abc123","abc456","abc789"] |
| language | Language of website from which the purchase was made. | en |
| location | URL of the page where the purchase event occurred. | https://webshop.com/purchase |
| domain | Default domain of your website. | webshop.com |
cart_update
cart_update happens when an item/items are added or removed from the cart.
| Attribute | Description | Example |
|---|---|---|
| action | Customer's action on the basket. | add / remove / empty |
| button_copy | Text of the button used for adding item to the cart. | Add / Purchase / Add to cart |
| page_type | Type of a page where cart contents changed. | product / homepage / category / page / checkout |
| product_id | Automatically-generated ID of the product added/removed. | abc123 |
| variant_id | Automatically-generated ID of the variant of the product added/removed that includes information about colour, size or materials. | abc123small |
| title | Name of the item added/removed that includes colour, size or materials if available. | Tassel Loafers in Navy Faux Sued |
| brand | Brand of an item added/removed. | END. |
| price | Price of one unit of the item added/removed to be paid by the customer in the reference currency. | 18 |
| price_local_currency | Price of one unit of the item added/removed to be paid by the customer in the currency they are going to use for the payment. | 90 |
| discount_percentage | In case of a discount, the discount rate used on the item added/removed expressed as a percentage. | 10 |
| discount_value | In case of a discount, the amount subtracted from the price of the item added/removed as a result of the discount. | 2 |
| original_price | Price of the item added/removed without a discount in a reference currency. | 20 |
| original_price_local_currency | Price of the item added/removed without a discount in a currency the customer used for the payment. | 100 |
| product_list | List of all products in the cart after cart update. | [ {"product_id": "abc123", "quantity":1} ] |
| product_ids | List of IDs of all products in the cart after cart update. | [ "abc123", "abc456", "abc789" ] |
| total_quantity | Total quantity of the products in the cart. | 2 |
| total_price | Total price of the products in the cart in the reference currency. | 24 |
| total_price_without_tax | Total price of items in the cart in the reference currency including the shipping but not the tax. | 20 |
| total_price_local_currency | Total price of items in the cart in the currency the customer will use for the payment. | 43 |
| local_currency | Currency the customer will use for the payment. | USD, GBP, EUR |
| tags | Custom tags for describing the item. | ["new", "sales", "teen", "man"] |
| category_1 | Top level category of products on the website where the item can be found. | Shoes |
| category_2 | Second level category of products on the website where the item can be found. | Trekking |
| category_3 | Third level category of products on the website where the item can be found. | Ankle boots |
| categories_path | Path through the categories leading to the product. | Shoes > Trekking > Ankle boots |
| category_id | Automatically-generated ID of the final category from which the cart was updated. | abc123 |
| categories_ids | List of IDs of all categories from root until the final one from which the cart was updated. | ["abc123","abc456","abc789"] |
| variant_list | List of all variants of the items in the cart, their quantities and other required properties. | [ {"variant_id": "abc123", "quantity":1} ] |
| variant_ids | List of IDs of all variants of the items in the cart. | [ "abc123", "abc456", "abc789" ] |
| language | Language of website where the cart was updated. | en |
| location | URL of the page where the cart_update event occurred. | https://webshop.com/cart-update |
| domain | Default domain of your website. | webshop.com |
checkout
checkout happens on with every step (page) of the checkout process.
| Attribute | Description | Example |
|---|---|---|
| step_number | Number of the step of the checkout process. | 1 |
| step_title | Title of the step of the checkout process. | Shipping / Personal information / Completed |
| product_list | List of all products in the cart. | [ {"product_id": "abc123", "quantity":1} ] |
| product_ids | List of IDs of all products in the cart. | [ "abc123", "abc456", "abc789" ] |
| payment_type | Payment method. | bank transfer / online payment / cash / cod |
| total_price | Total price of the products to be purchased. | 24 |
| total_price_without_tax | Total price of items in the cart in the reference currency including the shipping but not the tax. | 20 |
| total_price_local_currency | Total price of items in the cart in the currency the customer will use for the payment. | 43 |
| local_currency | Currency the customer will use for the payment. | USD, GBP, EUR |
| total_quantity | Total quantity of the products to be purchased. | 2 |
| tax_value | Sales tax expressed as money. | 24 |
| tax_percentage | Sales tax expressed as a percentage. | 20 |
| shipping_type | Type of delivery. | courier / personally |
| shipping_company | Delivery company. | ups |
| shipping_cost | Price of shipping. | 69 |
| shipping_country | Name of the country to which the products will be delivered. | USA |
| shipping_city | Name of the city to which the products will be delivered. | New York |
| voucher_code | Code of the voucher to be used in this purchase. | KA54-548C-TEST |
| voucher_percentage | The discount rate conferred on the customer by the voucher expressed as a percentage. | 10 |
| voucher_value | The amount that the voucher will subtract from the prize of the purchase. | 2 |
| variant_list | List of all variants of the items in the cart, their quantities and other required properties. | [ {"variant_id": "abc123", "quantity":1} ] |
| variant_ids | List of IDs of all variants of the items in the cart. | [ "abc123", "abc456", "abc789" ] |
| language | Language of website. | en |
| location | URL of the page where the checkout event occurred. | https://webshop.com/checkout |
| domain | Default domain of your website. | webshop.com |
view_item
view_item happens every time the customer opens the page of a particular product.
| Attribute | Description | Example |
|---|---|---|
| product_id | Automatically-generated ID of the product. | abc123 |
| variant_id | Automatically-generated ID of the variant of the viewed product that includes information about colour, size or materials. | abc123small |
| title | Name of the item viewed that includes colour, size or materials if available. | Tassel Loafers in Navy Faux Sued |
| brand | Brand of an item viewed. | END. |
| price | Price of one unit of the item viewed to be paid by the customer in the reference currency. | 18 |
| price_local_currency | Price of one unit of the item viewed by the customer in the currency listed on the website. | 90 |
| discount_percentage | In case of a discount, the discount rate used on the viewed item expressed as a percentage. | 10 |
| discount_value | In case of a discount, the amount subtracted from the price of the viewed item as a result of the discount. | 2 |
| original_price | Price of the viewed item without a discount in a reference currency. | 20 |
| original_price_local_currency | Price of the viewed item without a discount in the currency listed on the website. | 100 |
| local_currency | Currency the customer will use for the payment. | USD, GBP, EUR |
| stock_level | Number of the particular item in stock. | 46 |
| tags | Custom tags for describing the item. | ["new", "sales", "teen", "man"] |
| category_1 | Top level category of products on the website where the item can be found. | Shoes |
| category_2 | Second level category of products on the website where the item can be found. | Trekking |
| category_3 | Third level category of products on the website where the item can be found. (number of categories is not limited to 3) | Ankle boots |
| categories_path | Path through the categories leading to the product. | Shoes > Trekking > Ankle boots |
| category_id | Automatically-generated ID of the final category where the viewed product belongs. | abc123 |
| categories_ids | List of IDs of all categories from root until the final where the viewed item belongs. | ["abc123","abc456","abc789"] |
| language | Language of website. | en |
| location | URL of the page where the view_item event occurred. | https://webshop.com/shoes/end.-red-39 |
| domain | Default domain of your website. | webshop.com |
view_category
view_category happens every time the customer opens the page of a particular category of products.
| Attribute | Description | Example |
|---|---|---|
| category_id | Automatically-generated ID of the viewed category. | abc123 |
| category_name | Name of the category. | Shoes |
| category_listed_products | List of all product IDs in the category. | ["A1", "C3", "G5", "A2"] |
| category_1 | Either the top level category of products preceding the currently viewed category or the currently viewed category. | Shoes |
| category_2 | Either the second level category of products preceding the currently viewed category or the currently viewed category. | Trekking |
| category_3 | Either the third level category of products preceding the currently viewed category or the currently viewed category. (number of categories is not limited to 3) | Ankle boots |
| categories_path | Path through the categories leading to the category page currently seen. | Shoes > Trekking > Ankle boots |
| categories_ids | List of IDs of all categories from the root until the selected category. | ["abc123","abc456","abc789"] |
| local_currency | Currency the customer will use for the payment. | USD, GBP, EUR |
| language | Language of website. | en |
| location | URL of the page where the view_category event occurred. | https://webshop.com/shoes/shoes |
| domain | Default domain of your website. | webshop.com |
consent
Attributes of the consent can be found in our Tracking consent events article.
banner
banner happens when the customer is shown a banner you had created. banner is considered to be a semi-custom event because you have to manually set up the tracking of a new custom-made banner while the banner templates provided are tracked automatically. Learn more about weblayers in our guide.
Javascript editing
Web layer conditions rely on the event
bannerand attributesaction = showandinteraction = true / false. If you change this structure in the JS editor, the web layer won't work properly.
| Attribute | Description | Example |
|---|---|---|
| action | User's action towards the banner. If there was none the value is just "show". | click / subscribe / show / close |
| banner_name | Custom-given name of the banner. | Subscription banner |
| banner_id | Automatically-generated ID of the banner. | 4sa5729971a4f992sj9 |
| banner_type | Template or custom-given name of the type of a banner with certain properties. | medium_rectangle |
| interaction | Information on whether the user interacted with the banner. | true |
| category_listed_products | List of all product IDs in the category. | ["A1", "C3", "G5", "A2"] |
| category_1 | Top level category of products on the website where the banner can be found. | Shoes |
| category_2 | Second level category of products on the website where the banner can be found. | Trekking |
| category_3 | Third level category of products on the website where the banner can be found. (number of categories is not limited to 3) | Ankle boots |
| categories_path | Path through the categories leading to the category page currently seen. | Shoes > Trekking > Ankle boots |
| categories_ids | List of IDs of all categories from the root until the selected category. | ["abc123","abc456","abc789"] |
| local_currency | Currency the customer will use for the payment. | USD, GBP, EUR |
| language | Language of website. | en |
| domain | Default domain of your website. | webshop.com |
| location | URL of the page with the banner. | http://eshop.exponea.com/chaz-kangeroo-hoodie-banner.html |
| path | Last part of the URL of the page with the banner. | chaz-kangeroo-hoodie-banner.html |
| device | Mobile device from which the user sees the page with the banner. If the visit was not through a mobile device then it is marked as "other". | Iphone |
| os | Operating system of the device through which the user sees the page with the banner. | Windows |
| browser | Browser through which the the user sees the page with the banner. | Chrome |
Values of the action attribute for a banner
| Value | Description |
|---|---|
| click | The customer clicked on the promotional banner to see more about the offer. |
| subscribe | The customer filled the subscribe banner with their contact information and sent it. |
| show | The banner was shown to the customer. |
| close | The customer closed the banner. |
Additional banner attributes for in-app personalization
In mobile apps, in-app messages and in-app content blocks shown to the customer are also tracked as banner events. In these cases, the following additional attributes are tracked:
| Attribute | Description | Example |
|---|---|---|
| app_version | The version of the mobile app. | 2.21.3 |
| device_model | The device model used. | iPhone |
| device_type | The type of device used. | mobile |
| os_name | The name of the operating system used. | iOS |
| os_version | The version of the operating system used. | 17.2 |
| placeholder | The name of the placeholder in the app in where the in-app content block was shown. Not tracked for in-app messages. | example_top |
| platform | The platform used. | iOS |
| sdk | The name of the mobile SDK used by the app. | Exponea iOS SDK |
| sdk_version | The version of the mobile SDK used by the app. | 2.21.3 |
| type | The type of the banner shown (in-app message or in-app content block). | in-app message |
recommendation
recommendation happens when the customer is shown a recommendation box you had created. recommendation is considered to be a semi-custom event because you have to manually set up the tracking of a new custom-made recommendation while the recommendation templates provided are tracked automatically. Learn more about recommendations in our guide.
| Attribute | Description | Example |
|---|---|---|
| action | User's action towards the banner. If there was none the value is just "show". | serve / get / show / timeout / click |
| recommendation_id | Automatically-generated ID of the recommendation engine variant (model) used. | 4sa5729971a4f992sj9 |
| recommendation_variant_id | Automatically-generated ID of the recommendation engine variant (model) used. | cf_5729971a4f992sj9 |
| product_id | Automatically-generated ID of a product from the recommendation box that was clicked on by the customer. | abc123 |
| product_ids | List of automatically-generated IDs of the products shown in the recommendation. | a262740, b256429, c270262, d248197 |
| price | Price of a product from the recommendation box that was clicked on by the customer. | 15 |
| placement | Placement of the recommendation box rendering. | homepage / product_detail / ... |
| ab_variant | Name of the particular recommendation variant. | Variant A / Variant B / Control Group |
| variant_id | Automatically-generated ID of a particular variant of a product from the recommendation box that was clicked on by the customer. | abc123small |
Values of the action attribute for a recommendation
| Value | Description |
|---|---|
| serve | The webpage requested information on the recommendation from the server. |
| get | The webpage received the information on the recommendation from the server and rendered the recommendation on the page. (The customer might still not have seen it, for example, if the box was located at the bottom and they did not scroll down the page enough) |
| show (often named wrapper_reach) | The webpage received the information on the recommendation from the server and rendered the recommendation on the page AND the customer actually saw it. |
| timeout | The requested recommendation was not returned by the servers to the webpage within the specified time period. |
| click | The customer clicked on the recommendation box to see the recommended product. |
| close | The customer closed the recommendation box. |
Efficient Engagement usage
When generated, custom events get procesed and stored, thus counting toward your Monthly Processed Events (MPE) and Maximum Events Storage (MES) covered by your contract. Learn how to optimize your MPE and MES in this best practices article to get the most out of your Engagement experience!
Updated 9 days ago