> ## 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.

# Template events

> Eight Analytics Web methods send a common event with a fixed name and typed properties.

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](/core/event-tracking).

```typescript theme={null}
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. |

```typescript theme={null}
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. |

```typescript theme={null}
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. |

```typescript theme={null}
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](/features/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. |

```typescript theme={null}
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. |

```typescript theme={null}
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. |

```typescript theme={null}
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](/core/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`. |

```typescript theme={null}
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. |

```typescript theme={null}
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](/core/event-naming). A full shop flow with these methods is in
[E-commerce tracking](/guides/ecommerce).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.