Name events

A custom event name has three parts: a category, an object, and an action, joined with underscores. user_signup_clicked is a user event, about the signup, that was clicked. The form makes events sort by domain in the dashboard and easy to filter in a query.

{category}_{object}_{action}

Template events and system events do not follow the convention. Read the sections below before you rename one.

Category	Use for	Examples
`user_`	Authentication, profile, settings, account	`user_signup_clicked`, `user_profile_updated`
`product_`	Product browsing, filters, comparisons	`product_details_viewed`, `product_filter_applied`
`cart_`	Shopping cart operations	`cart_item_added`, `cart_checkout_started`
`checkout_`	Checkout flow steps	`checkout_payment_submitted`, `checkout_address_updated`
`content_`	Articles, videos, documentation	`content_article_viewed`, `content_video_played`
`nav_`	Navigation	`nav_menu_opened`, `nav_footer_clicked`
`form_`	Form interactions	`form_contact_submitted`, `form_newsletter_signed`
`modal_`	Modal and dialog interactions	`modal_promo_closed`, `modal_signup_opened`
`search_`	Search	`search_query_submitted`, `search_results_filtered`

Actions

The action is a verb in the past tense.

Group	Action	Meaning
Interaction	`clicked`	The user clicked or tapped an element
Interaction	`submitted`	The user submitted a form
Interaction	`opened`	The user opened a modal, menu, or expandable
Interaction	`closed`	The user closed a modal, menu, or expandable
Interaction	`toggled`	The user toggled a switch or option
Collection	`added`	An item was added to a collection
Collection	`removed`	An item was removed from a collection
Collection	`updated`	An item was changed
Collection	`deleted`	An item was removed for good
Progress	`started`	The user began a process
Progress	`completed`	The user finished a process
Progress	`failed`	The action failed
Progress	`cancelled`	The user cancelled the action
View	`viewed`	The user saw a page or section
View	`scrolled`	The user scrolled to a section
View	`hovered`	The user hovered over an element

Examples

A checkout flow, with context in properties and not in the name.

import { track } from '@grainql/tag';

track('product_details_viewed', { product_id: 'SKU123' });
track('cart_item_added', { product_id: 'SKU123', quantity: 1 });
track('cart_checkout_started');
track('checkout_shipping_updated', { method: 'express' });
track('checkout_payment_submitted', { method: 'credit_card' });
track('checkout_completed', { order_id: 'ORD-789', total: 99.99 });
track('checkout_payment_failed', { error: 'card_declined' });

await grain.track('product_details_viewed', { product_id: 'SKU123' });
await grain.track('cart_item_added', { product_id: 'SKU123', quantity: 1 });
await grain.track('cart_checkout_started');
await grain.track('checkout_shipping_updated', { method: 'express' });
await grain.track('checkout_payment_submitted', { method: 'credit_card' });
await grain.track('checkout_completed', { order_id: 'ORD-789', total: 99.99 });
await grain.track('checkout_payment_failed', { error: 'card_declined' });

Three patterns that come up on most sites:

Pattern	Rule	Example
Multi-step flow	One object for every step of the flow	`user_signup_started`, `user_signup_email_entered`, `user_signup_completed`
Failure	A `failed` event next to the `submitted` event, with the error in a property	`form_contact_failed` with `error: 'invalid_email'`
Call to action	The location and the trigger in properties	`user_signup_clicked` with `source: 'pricing_page'`
A/B test	The experiment and the variant in properties	`modal_promo_viewed` with `experiment: 'summer_sale'`, `variant: 'control'`

Template events and system events

Template events are the events behind trackLogin, trackSignup, trackPurchase, trackCheckout, trackSearch, trackAddToCart, and trackRemoveFromCart. Their names are login, signup, purchase, checkout, search, add_to_cart, and remove_from_cart. Do not rename them. The dashboard reads them by these names. Read Template events. System events start with _grain_. The SDK sends them on its own: _grain_session_start, _grain_session_end, _grain_heartbeat, _grain_consent_granted.

Do not create an event name that starts with _grain_. The prefix is reserved for the SDK.

Names in queries

GET /events/{tenantAlias} on the Query API returns every event name in your tenant, sorted. With the convention, the list groups by category on its own: every cart_ event, then every checkout_ event, then every user_ event. A funnel is a list of names in order, for example product_details_viewed, cart_item_added, cart_checkout_started, checkout_completed. Read Export and query data.

Limits

Limit	Value	Where
Event name length	50 characters	Convention, not enforced by the SDK

When a name is too long, shorten the object: checkout_address_autocomplete_selected instead of checkout_shipping_address_autocomplete_selected.

Migrate existing names

The SDK accepts any event name, so old names keep working. Migrate at the pace that fits your codebase.

Step	What to do
1	List the current names with `GET /events/{tenantAlias}` and map each one to a new name.
2	Track the old name and the new name together during the transition.
3	Update queries, dashboards, and tracks to the new names.
4	Remove the old names after 30 to 90 days.

Checklist

Before you track a new custom event, make sure that:

The name has the form {category}_{object}_{action}.
The category is in the table above, or extends one.
The action is a standard verb in the past tense.
The name is 50 characters or fewer.
The name is not a template event name and does not start with _grain_.
The name holds no ID, timestamp, or other data. Data goes in properties.
The name uses the same style as every other event in the application.
A colleague can understand the name without context.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Categories

Actions

Examples

Template events and system events

Names in queries

Limits

Migrate existing names

Checklist

​Categories

​Actions

​Examples

​Template events and system events

​Names in queries

​Limits

​Migrate existing names

​Checklist

Categories

Actions

Examples

Template events and system events

Names in queries

Limits

Migrate existing names

Checklist