Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grainql.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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