Custom Events: Best Practices
Last updated September 18, 2023
Overview
Custom events are used to track important customer behaviors and system events throughout your app. In Atlas, they can be used in three places:
- the customer timeline
- session recordings
- as search or trigger criteria in finder, chatbots, and automations
In this article, we'll review best practices for:
- when to use client vs server API calls
- when to use each event type
- how to name custom events
- common events for different business models
When to use client vs server API calls
Sending events via the client typically provides more context, while sending events via the server is typically more reliable.
Use client-side API calls when:
- information isn't stored in your database (eg, page views, button clicks, page scroll length, etc.)
- it's easier to send information from the client (eg, UTM tag, device, user agent, etc.)
When to use each event type
There are six different event types you can call with Atlas: identify, track, page, screen, group, and alias. Each one answers a different question about a customer:
identify: who is this customer?
- call this at account creation, account updated, user login, and when a user accesses any login gated pages
track: what are they doing?page/screen: which page (web) / screen (app) are they on?
- call this when a customer navigates to a new page or screen in your app
group: which account do they belong to?
- call this when a customer is assigned to a new account
alias: do they have a past id?
How to name custom events
Use the "Object-Action" naming convention for events when possible. For instance, "Account Created," "Customer Signed Up," and "Product Searched."
When naming properties, use snake case (eg, property_name).
Common events for different business models
Two common business models we encounter are ecommerce and B2B SaaS. Here are some common events for each type of business:
Ecommerce
- Browsing: Products Searched, Product List Viewed, Product List Filtered
- Promotions: Promotion Viewed, Promotion Clicked
- Core Ordering: Product Clicked, Product Viewed, Product Added, Product Removed, Cart Viewed, Checkout Started, Checkout Step Viewed, Checkout Step Completed, Payment Info Entered, Order Completed, Order Updated, Order Refunded, Order Cancelled
- Coupons: Coupon Entered, Coupon Applied, Coupon Denied, Coupon Removed
- Wishlisting: Product Added to Wishlist, Product Removed from Wishlist, WIshlist Product Added to Cart
- Sharing: Product Shared, Cart Shared
- Reviewing: Product Reviewed
B2B SaaS
- Account Created, Account Deleted, Signed Up, Signed In, Signed Out, Invite Sent, Account Added User, Account Removed User, Trial Started, Trial Ended
References
" Collecting Data on the Client or Server ," Segment
" Spec Overview ," Segment
" Best Practices for Event Calls ," Segment