Template Methods

Overview

Template methods provide type-safe, pre-structured events for common tracking scenarios. They’re shortcuts that ensure consistent event structure. All template methods accept optional properties and options parameters.

trackLogin()

Track user login events.

await grain.trackLogin(
  properties?: LoginEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  method?: string;              // 'email', 'google', 'facebook', etc.
  success?: boolean;            // Whether login succeeded
  errorMessage?: string;        // Error message if failed
  loginAttempt?: number;        // Attempt number
  rememberMe?: boolean;         // "Remember me" checkbox
  twoFactorEnabled?: boolean;   // 2FA used
  // ... plus any custom properties
}

Example:

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

trackSignup()

Track user registration events.

await grain.trackSignup(
  properties?: SignupEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  method?: string;        // Signup method
  source?: string;        // Where they came from
  plan?: string;          // Selected plan
  success?: boolean;      // Signup succeeded
  referralCode?: string;  // Referral code used
  // ... plus any custom properties
}

Example:

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

trackCheckout()

Track checkout process events.

await grain.trackCheckout(
  properties?: CheckoutEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  orderId?: string;                // Order identifier
  total?: number;                  // Total amount
  currency?: string;               // Currency code
  items?: Array<{                  // Cart items
    id: string;
    name: string;
    price: number;
    quantity: number;
  }>;
  paymentMethod?: string;          // Payment method
  success?: boolean;               // Checkout succeeded
  errorMessage?: string;           // Error if failed
  couponCode?: string;             // Discount code
  discount?: number;               // Discount amount
  // ... plus any custom properties
}

Example:

await grain.trackCheckout({
  orderId: 'order_123',
  total: 149.98,
  currency: 'USD',
  items: [
    { id: 'prod_1', name: 'Shoes', price: 89.99, quantity: 1 },
    { id: 'prod_2', name: 'Socks', price: 59.99, quantity: 1 }
  ],
  paymentMethod: 'credit_card',
  success: true
});

trackPurchase()

Track completed purchase events.

await grain.trackPurchase(
  properties?: PurchaseEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  orderId?: string;        // Order identifier
  total?: number;          // Total amount
  currency?: string;       // Currency code
  paymentMethod?: string;  // Payment method
  shipping?: number;       // Shipping cost
  tax?: number;            // Tax amount
  // ... plus any custom properties
}

Example:

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

trackAddToCart()

Track items added to cart.

await grain.trackAddToCart(
  properties?: AddToCartEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  itemId?: string;      // Product ID
  itemName?: string;    // Product name
  price?: number;       // Item price
  quantity?: number;    // Quantity added
  currency?: string;    // Currency code
  // ... plus any custom properties
}

Example:

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

trackRemoveFromCart()

Track items removed from cart.

await grain.trackRemoveFromCart(
  properties?: RemoveFromCartEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  itemId?: string;      // Product ID
  itemName?: string;    // Product name
  price?: number;       // Item price
  quantity?: number;    // Quantity removed
  // ... plus any custom properties
}

Example:

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

trackPageView()

Track page view events.

await grain.trackPageView(
  properties?: PageViewEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  page?: string;      // Page path
  title?: string;     // Page title
  url?: string;       // Full URL
  referrer?: string;  // Referrer URL
  // ... plus any custom properties
}

Example:

await grain.trackPageView({
  page: '/products',
  title: 'Product Catalog',
  url: window.location.href,
  referrer: document.referrer
});

trackSearch()

Track search query events.

await grain.trackSearch(
  properties?: SearchEventProperties,
  options?: SendEventOptions
): Promise<void>

Properties:

{
  query?: string;                      // Search query
  results?: number;                    // Number of results
  filters?: Record<string, unknown>;   // Applied filters
  sortBy?: string;                     // Sort order
  // ... plus any custom properties
}

Example:

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

Custom Properties

All template methods accept additional custom properties:

await grain.trackLogin({
  method: 'email',
  success: true,
  // Custom properties
  ip_address: req.ip,
  user_agent: req.headers['user-agent'],
  custom_field: 'custom_value'
});

Flush Option

All template methods support the flush option:

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

Forces immediate sending instead of batching.

Next Steps

Template Events Guide

Learn about template events

E-commerce Guide

E-commerce tracking guide

API Documentation

Query API

Overview

trackLogin()

trackSignup()

trackCheckout()

trackPurchase()

trackAddToCart()

trackRemoveFromCart()

trackPageView()

trackSearch()

Custom Properties

Flush Option

Next Steps

Template Events Guide

E-commerce Guide

​Overview

​trackLogin()

​trackSignup()

​trackCheckout()

​trackPurchase()

​trackAddToCart()

​trackRemoveFromCart()

​trackPageView()

​trackSearch()

​Custom Properties

​Flush Option

​Next Steps

Template Events Guide

E-commerce Guide

Overview

trackLogin()

trackSignup()

trackCheckout()

trackPurchase()

trackAddToCart()

trackRemoveFromCart()

trackPageView()

trackSearch()

Custom Properties

Flush Option

Next Steps