Template events

A template event is a track call with a fixed event name and a TypeScript type for its properties. trackLogin({ method: 'email' }) sends the same event as track('login', { method: 'email' }). The type tells your editor which properties exist, and every part of your code sends the event with the same name. Analytics Web has eight template methods. Grain Tag has none. It sends every event with track.

Methods

Method	Event name	Property type
`trackLogin`	`login`	`LoginEventProperties`
`trackSignup`	`signup`	`SignupEventProperties`
`trackCheckout`	`checkout`	`CheckoutEventProperties`
`trackPurchase`	`purchase`	`PurchaseEventProperties`
`trackAddToCart`	`add_to_cart`	`AddToCartEventProperties`
`trackRemoveFromCart`	`remove_from_cart`	`RemoveFromCartEventProperties`
`trackPageView`	`page_view`	`PageViewEventProperties`
`trackSearch`	`search`	`SearchEventProperties`

Every method has the signature (properties?, options?) and returns Promise<void>. options is SendEventOptions, which holds one field, flush. With flush: true, the SDK sends the event at once instead of the next batch. Read Track an event.

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

Every property is optional. Every property type extends Record<string, unknown>, so you can add your own keys next to the typed ones. The types in @grainql/analytics-web win over the tables on this page.

trackLogin

Field	Type	Meaning
`method`	`string`	The login method: `email`, `google`, `github`.
`success`	`boolean`	`true` when the login succeeded.
`errorMessage`	`string`	The reason of a failed login.
`loginAttempt`	`number`	The attempt count for this login.
`rememberMe`	`boolean`	`true` when the user selected “remember me”.
`twoFactorEnabled`	`boolean`	`true` when the login used a second factor.

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

trackSignup

Field	Type	Meaning
`method`	`string`	The signup method: `email`, `google`, `github`.
`source`	`string`	Where the user came from, for example `landing_page`.
`plan`	`string`	The plan the user chose.
`success`	`boolean`	`true` when the signup completed.
`errorMessage`	`string`	The reason of a failed signup.

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

trackCheckout

Field	Type	Meaning
`orderId`	`string`	The order identifier.
`total`	`number`	The order total.
`currency`	`string`	The currency code, for example `USD`.
`items`	`Array<{ id, name, price, quantity }>`	The products in the order. `id` and `name` are strings, `price` and `quantity` are numbers.
`paymentMethod`	`string`	The payment method, for example `credit_card`.
`success`	`boolean`	`true` when the checkout completed.
`errorMessage`	`string`	The reason of a failed checkout.
`couponCode`	`string`	The coupon that the user applied.
`discount`	`number`	The discount amount.

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

trackPurchase

checkout marks the start or the end of a checkout. purchase marks a completed transaction. Send both, and the dashboard shows the checkout completion rate as a track. Read Tracks.

Field	Type	Meaning
`orderId`	`string`	The order identifier.
`total`	`number`	The order total.
`currency`	`string`	The currency code, for example `USD`.
`items`	`Array<{ id, name, price, quantity, category? }>`	The products in the order. `category` is an optional string.
`paymentMethod`	`string`	The payment method, for example `credit_card`.
`shippingMethod`	`string`	The shipping method.
`tax`	`number`	The tax amount.
`shipping`	`number`	The shipping cost.
`discount`	`number`	The discount amount.
`couponCode`	`string`	The coupon that the user applied.

await grain.trackPurchase(
  {
    orderId: 'order_456',
    total: 99.99,
    currency: 'USD',
    paymentMethod: 'credit_card',
    items: [{ id: 'prod_1', name: 'Blue Sneakers', price: 89.99, quantity: 1, category: 'footwear' }],
    shipping: 10.0,
  },
  { flush: true },
);

trackAddToCart

Field	Type	Meaning
`itemId`	`string`	The product identifier.
`itemName`	`string`	The product name.
`price`	`number`	The unit price.
`quantity`	`number`	The quantity added.
`currency`	`string`	The currency code, for example `USD`.
`category`	`string`	The product category.
`variant`	`string`	The product variant, for example a size or a color.

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

trackRemoveFromCart

RemoveFromCartEventProperties has the same fields as AddToCartEventProperties.

Field	Type	Meaning
`itemId`	`string`	The product identifier.
`itemName`	`string`	The product name.
`price`	`number`	The unit price.
`quantity`	`number`	The quantity removed.
`currency`	`string`	The currency code, for example `USD`.
`category`	`string`	The product category.
`variant`	`string`	The product variant.

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

trackPageView

Both SDKs track page views without code. Call trackPageView only when automatic page views are off, or when a route change is not visible to the SDK. Read Automatic tracking.

Field	Type	Meaning
`page`	`string`	The page path, for example `/products`.
`title`	`string`	The page title.
`referrer`	`string`	The URL the user came from.
`url`	`string`	The full URL.
`userAgent`	`string`	The browser user agent.
`screenResolution`	`string`	The screen size, for example `1920x1080`.
`viewportSize`	`string`	The viewport size, for example `1280x720`.

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

trackSearch

Field	Type	Meaning
`query`	`string`	The search text.
`results`	`number`	The number of results.
`filters`	`Record<string, unknown>`	The filters that the user applied.
`sortBy`	`string`	The sort order.
`category`	`string`	The category the user searched in.
`success`	`boolean`	`true` when the search returned results.

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

For an event that no template covers, call track with your own name. Read Name events. A full shop flow with these methods is in E-commerce tracking.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Methods

trackLogin

trackSignup

trackCheckout

trackPurchase

trackAddToCart

trackRemoveFromCart

trackPageView

trackSearch

​Methods

​trackLogin

​trackSignup

​trackCheckout

​trackPurchase

​trackAddToCart

​trackRemoveFromCart

​trackPageView

​trackSearch

Methods

trackLogin

trackSignup

trackCheckout

trackPurchase

trackAddToCart

trackRemoveFromCart

trackPageView

trackSearch