Template Events

What Are Template Events?

Template events are pre-built methods for common tracking scenarios. Instead of remembering property names and structure, use ready-made methods: Without templates:

grain.track('login', {
  method: 'email',
  success: true,
  rememberMe: false
});

With templates:

grain.trackLogin({
  method: 'email',
  success: true,
  rememberMe: false
});

Same result, but template methods guide you with type hints and ensure consistency.

Why Use Templates?

Type Safety: TypeScript knows which properties are available:

grain.trackLogin({
  method: 'email',
  success: true,
  // TypeScript suggests: rememberMe, errorMessage, loginAttempt, etc.
});

Consistency: Everyone on your team tracks events the same way. Documentation: Method names make it clear what you’re tracking. You can still use grain.track() for custom events. Templates are optional helpers for common cases.

Authentication Events

trackLogin()

Track when users log in:

await grain.trackLogin({
  method: 'email',
  success: true
});

Common properties:

method: ‘email’, ‘google’, ‘github’, etc.
success: Whether login succeeded
errorMessage: If login failed, why?
rememberMe: Whether “remember me” was checked
twoFactorEnabled: If 2FA was used

Example with error:

await grain.trackLogin({
  method: 'email',
  success: false,
  errorMessage: 'Invalid password',
  loginAttempt: 3
});

trackSignup()

Track new user registrations:

await grain.trackSignup({
  method: 'google',
  source: 'landing_page',
  plan: 'free'
});

Common properties:

method: How they signed up
source: Where they came from
plan: Which plan they chose
success: Whether signup completed
referralCode: If they used a referral

E-commerce Events

trackCheckout()

Track when users start or complete checkout:

await grain.trackCheckout({
  orderId: 'order_123',
  total: 99.99,
  currency: 'USD',
  paymentMethod: 'credit_card',
  success: true
});

Common properties:

orderId: Unique order identifier
total: Total amount
currency: Currency code (USD, EUR, etc.)
items: Array of products (see below)
paymentMethod: How they’re paying
couponCode: Any discount codes used

With items:

await grain.trackCheckout({
  orderId: 'order_123',
  total: 149.98,
  items: [
    { id: 'prod_1', name: 'Blue Sneakers', price: 89.99, quantity: 1 },
    { id: 'prod_2', name: 'Socks', price: 59.99, quantity: 1 }
  ]
});

trackPurchase()

Track completed purchases:

await grain.trackPurchase({
  orderId: 'order_123',
  total: 99.99,
  currency: 'USD',
  paymentMethod: 'credit_card'
});

Similar to checkout, but specifically for completed transactions. Track both to measure checkout completion rate.

trackAddToCart()

Track when items are added to cart:

await grain.trackAddToCart({
  itemId: 'prod_123',
  itemName: 'Blue Sneakers',
  price: 89.99,
  quantity: 1,
  currency: 'USD'
});

trackRemoveFromCart()

Track when items are removed:

await grain.trackRemoveFromCart({
  itemId: 'prod_123',
  itemName: 'Blue Sneakers',
  quantity: 1
});

trackPageView()

Track page views:

await grain.trackPageView({
  page: '/products',
  title: 'Product Catalog',
  url: 'https://yoursite.com/products'
});

Common properties:

page: Page path
title: Page title
url: Full URL
referrer: Where user came from

SPA (Single Page App) example:

// Track route changes
router.afterEach((to) => {
  grain.trackPageView({
    page: to.path,
    title: to.meta.title
  });
});

trackSearch()

Track search queries:

await grain.trackSearch({
  query: 'blue shoes',
  results: 24,
  filters: { category: 'footwear', color: 'blue' }
});

Common properties:

query: What user searched for
results: Number of results found
filters: Any filters applied
sortBy: Sort order used

Using Template Events

All template methods work like track():

// Basic usage
await grain.trackLogin({ method: 'email' });

// With flush
await grain.trackLogin({ 
  method: 'email' 
}, { flush: true });

// With user ID override
await grain.trackLogin({ 
  method: 'email' 
}, { userId: 'user_123' });

Creating Custom Events

For events not covered by templates, use track():

// Custom event
grain.track('video_watched', {
  video_id: 'video_123',
  duration: 120,
  completed: false,
  progress: 0.75
});

Templates are just helpers. You’re never limited to them.

Real-World Example

Here’s a complete user flow with template events:

// User lands on site
await grain.trackPageView({
  page: '/',
  referrer: 'https://google.com'
});

// Searches for products
await grain.trackSearch({
  query: 'running shoes',
  results: 48
});

// Adds item to cart
await grain.trackAddToCart({
  itemId: 'prod_123',
  itemName: 'Running Shoes',
  price: 79.99,
  quantity: 1
});

// Completes checkout
await grain.trackCheckout({
  orderId: 'order_456',
  total: 79.99,
  paymentMethod: 'credit_card',
  success: true
});

// Completes purchase
await grain.trackPurchase({
  orderId: 'order_456',
  total: 79.99
}, { flush: true });

Now you can analyze the complete journey from landing to purchase.

Available Templates

Current template methods:

trackLogin() - User login
trackSignup() - User registration
trackCheckout() - Checkout process
trackPurchase() - Completed purchase
trackAddToCart() - Add to cart
trackRemoveFromCart() - Remove from cart
trackPageView() - Page views
trackSearch() - Search queries

More templates may be added based on common use cases.

Next Steps

E-commerce Guide

Complete e-commerce tracking guide

Template Methods API

Full API reference for templates

Event Tracking

Learn more about custom events

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

What Are Template Events?

Why Use Templates?

Authentication Events

trackLogin()

trackSignup()

E-commerce Events

trackCheckout()

trackPurchase()

trackAddToCart()

trackRemoveFromCart()

Navigation Events

trackPageView()

trackSearch()

Using Template Events

Creating Custom Events

Real-World Example

Available Templates

Next Steps

E-commerce Guide

Template Methods API

Event Tracking

​What Are Template Events?

​Why Use Templates?

​Authentication Events

​trackLogin()

​trackSignup()

​E-commerce Events

​trackCheckout()

​trackPurchase()

​trackAddToCart()

​trackRemoveFromCart()

​Navigation Events

​trackPageView()

​trackSearch()

​Using Template Events

​Creating Custom Events

​Real-World Example

​Available Templates

​Next Steps

E-commerce Guide

Template Methods API

Event Tracking

What Are Template Events?

Why Use Templates?

Authentication Events

trackLogin()

trackSignup()

E-commerce Events

trackCheckout()

trackPurchase()

trackAddToCart()

trackRemoveFromCart()

Navigation Events

trackPageView()

trackSearch()

Using Template Events

Creating Custom Events

Real-World Example

Available Templates

Next Steps