Template methods

A template method is a track call with a fixed event name and a typed property object. Every method is a member of a GrainAnalytics instance. Every property is optional, and every property type extends Record<string, unknown>, so a custom property is allowed next to the listed ones. Read Template events for when to use them.

Method	Property type
`trackLogin(properties?, options?)`	`LoginEventProperties`
`trackSignup(properties?, options?)`	`SignupEventProperties`
`trackCheckout(properties?, options?)`	`CheckoutEventProperties`
`trackPageView(properties?, options?)`	`PageViewEventProperties`
`trackPurchase(properties?, options?)`	`PurchaseEventProperties`
`trackSearch(properties?, options?)`	`SearchEventProperties`
`trackAddToCart(properties?, options?)`	`AddToCartEventProperties`
`trackRemoveFromCart(properties?, options?)`	`RemoveFromCartEventProperties`

Every method returns Promise<void>. options is a SendEventOptions object. Its one field, flush, sends the event now instead of with the next batch.

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({ tenantId: 'your-tenant-id' });

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

trackLogin

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

Property	Type	Meaning
`method`	`string`	The login method, for example `'email'` or `'google'`.
`success`	`boolean`	Whether the login succeeded.
`errorMessage`	`string`	The error text when the login failed.
`loginAttempt`	`number`	The attempt number.
`rememberMe`	`boolean`	Whether the user selected “remember me”.
`twoFactorEnabled`	`boolean`	Whether the login used a second factor.

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

trackSignup

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

Property	Type	Meaning
`method`	`string`	The signup method.
`source`	`string`	Where the user came from.
`plan`	`string`	The selected plan.
`success`	`boolean`	Whether the signup succeeded.
`errorMessage`	`string`	The error text when the signup failed.

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

trackCheckout

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

Property	Type	Meaning
`orderId`	`string`	The order identifier.
`total`	`number`	The total amount.
`currency`	`string`	The currency code.
`items`	`Array<{ id: string; name: string; price: number; quantity: number }>`	The cart items.
`paymentMethod`	`string`	The payment method.
`success`	`boolean`	Whether the checkout succeeded.
`errorMessage`	`string`	The error text when the checkout failed.
`couponCode`	`string`	The coupon code.
`discount`	`number`	The discount amount.

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,
});

trackPageView

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

Property	Type	Meaning
`page`	`string`	The page path.
`title`	`string`	The page title.
`referrer`	`string`	The referrer URL.
`url`	`string`	The full URL.
`userAgent`	`string`	The user agent string.
`screenResolution`	`string`	The screen size.
`viewportSize`	`string`	The viewport size.

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

trackPurchase

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

Property	Type	Meaning
`orderId`	`string`	The order identifier.
`total`	`number`	The total amount.
`currency`	`string`	The currency code.
`items`	`Array<{ id: string; name: string; price: number; quantity: number; category?: string }>`	The purchased items.
`paymentMethod`	`string`	The payment method.
`shippingMethod`	`string`	The shipping method.
`tax`	`number`	The tax amount.
`shipping`	`number`	The shipping cost.
`discount`	`number`	The discount amount.
`couponCode`	`string`	The coupon code.

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

trackSearch

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

Property	Type	Meaning
`query`	`string`	The search text.
`results`	`number`	The number of results.
`filters`	`Record<string, unknown>`	The active filters.
`sortBy`	`string`	The sort order.
`category`	`string`	The search category.
`success`	`boolean`	Whether the search succeeded.

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

trackAddToCart

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

Property	Type	Meaning
`itemId`	`string`	The product identifier.
`itemName`	`string`	The product name.
`price`	`number`	The item price.
`quantity`	`number`	The quantity added.
`currency`	`string`	The currency code.
`category`	`string`	The product category.
`variant`	`string`	The product variant.

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

trackRemoveFromCart

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

Property	Type	Meaning
`itemId`	`string`	The product identifier.
`itemName`	`string`	The product name.
`price`	`number`	The item price.
`quantity`	`number`	The quantity removed.
`currency`	`string`	The currency code.
`category`	`string`	The product category.
`variant`	`string`	The product variant.

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

SDK reference

Query API

trackLogin

trackSignup

trackCheckout

trackPageView

trackPurchase

trackSearch

trackAddToCart

trackRemoveFromCart

​trackLogin

​trackSignup

​trackCheckout

​trackPageView

​trackPurchase

​trackSearch

​trackAddToCart

​trackRemoveFromCart

trackLogin

trackSignup

trackCheckout

trackPageView

trackPurchase

trackSearch

trackAddToCart

trackRemoveFromCart