Tracking checklist

Every event your code sends appears in the dashboard at https://grainql.com/dashboard. This checklist holds the practices that make those events useful there. Each item states the reason, shows one example, and links the page that holds the details. The examples use Analytics Web. Grain Tag sends the same events with GrainTag.track and the same names and properties.

Name an event as object and action

The dashboard lists events by name. checkout_completed says what happened, and action does not. Use lowercase words with underscores.

grain.track('checkout_completed', { order_id: 'order_456', total: 99.99 });

Read Name events.

Use the same property names on related events

A track or a filter that spans several events matches on the property name. When video_started sends video_id and video_paused sends id, the dashboard cannot join them.

grain.track('video_started', { video_id: 'abc', duration_seconds: 120 });
grain.track('video_paused', { video_id: 'abc', duration_seconds: 120, current_time: 45 });

Put the context in properties

A filter in the dashboard reads properties, not the event name. An event with category and source can be grouped by both.

grain.track('product_viewed', {
  product_id: 'prod_123',
  category: 'footwear',
  price: 89.99,
  currency: 'USD',
  source: 'search_results',
});

Read Track an event.

Use a template event for login, signup, cart, checkout, purchase, and search

A template method sends a fixed event name with typed properties, so every part of the code sends the same event.

await grain.trackPurchase({ orderId: 'order_456', total: 149.99, currency: 'USD' });

Read Template events.

Identify the user after login

Without a user ID, the events of one person on two days are two anonymous visitors. After identify, they are one journey.

grain.identify('user_8f3a2c1b');

Read Identify users.

Store segments as user properties

A user property such as plan lets the dashboard compare groups of users, and remote configuration reads it to pick a value.

await grain.setProperty({ plan: 'premium', signup_date: '2024-01-15' });

Read User properties.

Send one event per step of a funnel

A track shows where users leave a flow. It needs one event per step, in order.

grain.track('signup_form_viewed');
grain.track('signup_form_started', { method: 'email' });
await grain.trackSignup({ method: 'email', source: 'landing_page', success: true });

Read Tracks.

Track an error as an event

An error event with error_type and error_message shows in the dashboard next to the events that came before it.

try {
  await processPayment();
} catch (error) {
  grain.track('payment_error', { error_type: error.name, error_message: error.message });
  throw error;
}

Flush an event that comes right before a navigation

The SDK batches events. An event that a redirect follows, such as a purchase, must go out before the page unloads.

await grain.trackPurchase({ orderId: 'order_456', total: 99.99 }, { flush: true });

Read Track an event.

Do not track page views and sessions by hand

Both SDKs send page views, sessions, and heartbeats without code. A manual copy doubles the counts.Read Automatic tracking.

For a custom dashboard on top of the same events, use the Query API. Read Export and query data.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced