Automatic properties

This page lists the properties that the Grain Analytics SDK collects on its own, and the properties that you collect. The tables come from the Analytics Web SDK reference. Every event has a Collected column with one of three values.

Value	Meaning
`always`	The SDK adds the property to every event, with or without consent
`with consent`	The SDK adds the property only after the user grants consent
`by you`	You pass the property in the `track` call or the template method

The TypeScript types of the published package win over this page when they disagree.

Standard events

`page_view`

Sent on every page navigation.

Property	Type	Collected	Description
`page`	string	`always`	Current page path, with or without query parameters based on `stripQueryParams`
`title`	string	`with consent`	Document title
`full_url`	string	`with consent`	Complete URL, including query parameters and hash
`referrer`	string	`with consent`	Previous page URL, from `document.referrer`
`referrer_domain`	string	`with consent`	Domain of the referrer
`referrer_category`	string	`with consent`	One of `organic`, `paid`, `social`, `direct`, `email`, `referral`
`previous_page`	string	`with consent`	Previous page in the same session
`landing_page`	string	`with consent`	First page of the session, only on page views after the first
`session_id`	string	`with consent`	Current session identifier
`utm_source`	string	`with consent`	UTM source parameter, if present
`utm_medium`	string	`with consent`	UTM medium parameter, if present
`utm_campaign`	string	`with consent`	UTM campaign parameter, if present
`utm_term`	string	`with consent`	UTM term parameter, if present
`utm_content`	string	`with consent`	UTM content parameter, if present
`first_touch_source`	string	`with consent`	First-touch attribution source
`first_touch_medium`	string	`with consent`	First-touch attribution medium
`first_touch_campaign`	string	`with consent`	First-touch attribution campaign
`first_touch_referrer_category`	string	`with consent`	First-touch referrer category
`device`	string	`always`	`Mobile`, `Tablet`, or `Desktop`
`browser`	string	`always`	`Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, or `Unknown`
`os`	string	`always`	`Windows`, `macOS`, `Linux`, `Android`, `iOS`, or `Unknown`
`language`	string	`always`	Browser language, from `navigator.language`
`timezone`	string	`always`	User time zone, for example `America/New_York`
`screen_resolution`	string	`always`	Screen resolution, for example `1920x1080`
`viewport`	string	`always`	Viewport size, for example `1440x900`
`timestamp`	number	`always`	Milliseconds since the epoch

`_grain_session_start`

Sent when a session begins, on page load.

Property	Type	Collected	Description
`session_id`	string	`always`	Unique session identifier
`landing_page`	string	`with consent`	First page of the session
`referrer`	string	`with consent`	Referrer URL, if present
`referrer_domain`	string	`with consent`	Referrer domain, if present
`referrer_category`	string	`with consent`	Referrer category
`utm_source`	string	`with consent`	UTM source, if present
`utm_medium`	string	`with consent`	UTM medium, if present
`utm_campaign`	string	`with consent`	UTM campaign, if present
`utm_term`	string	`with consent`	UTM term, if present
`utm_content`	string	`with consent`	UTM content, if present
`first_touch_source`	string	`with consent`	First-touch attribution source
`first_touch_medium`	string	`with consent`	First-touch attribution medium
`first_touch_campaign`	string	`with consent`	First-touch attribution campaign
`first_touch_referrer_category`	string	`with consent`	First-touch referrer category
`screen_resolution`	string	`with consent`	Screen resolution
`viewport`	string	`with consent`	Viewport size
`device`	string	`always`	`Mobile`, `Tablet`, or `Desktop`
`browser`	string	`always`	Browser name
`os`	string	`always`	Operating system
`language`	string	`with consent`	Browser language
`timezone`	string	`with consent`	User time zone
`timestamp`	number	`always`	Session start time

`_grain_session_end`

Sent when a session ends, on page unload or close.

Property	Type	Collected	Description
`session_id`	string	`always`	Session identifier
`duration`	number	`always`	Session duration in milliseconds
`event_count`	number	`always`	Events tracked during the session
`page_count`	number	`with consent`	Pages viewed during the session
`timestamp`	number	`always`	Session end time

`_grain_heartbeat`

Sent at a fixed interval to measure engagement. Read Automatic tracking for the intervals.

Property	Type	Collected	Description
`heartbeat_type`	string	`always`	`periodic` or `page_load`
`status`	string	`always`	`active` or `inactive`
`page`	string	`with consent`	Current page path
`session_id`	string	`with consent`	Current session identifier
`duration`	number	`with consent`	Milliseconds since the last heartbeat, `periodic` only
`event_count`	number	`with consent`	Events since the last heartbeat, `periodic` only
`timestamp`	number	`always`	Heartbeat time

`_grain_consent_granted`

Sent when the user grants analytics consent.

Property	Type	Collected	Description
`previous_session_id`	string	`always`	Session ID from before consent
`new_user_id`	string	`always`	Persistent user ID after consent
`timestamp`	number	`always`	Consent grant time

Template events

The template methods send these events. You call the method and pass the properties. Read Template events.

Analytics Web

await grain.trackLogin({
  method: 'email',
  success: true,
  errorMessage: 'Invalid credentials',
  loginAttempt: 1,
  rememberMe: true,
  twoFactorEnabled: false
});

Property	Type	Collected	Description
`method`	string	`by you`	Authentication method, for example `email` or `google`
`success`	boolean	`by you`	Whether the login succeeded
`errorMessage`	string	`by you`	Error message when `success` is `false`
`loginAttempt`	number	`by you`	Login attempt number
`rememberMe`	boolean	`by you`	Whether “remember me” was checked
`twoFactorEnabled`	boolean	`by you`	Whether two-factor authentication is on

Analytics Web

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

Property	Type	Collected	Description
`method`	string	`by you`	Registration method
`source`	string	`by you`	Where the user signed up from
`plan`	string	`by you`	Selected plan
`success`	boolean	`by you`	Whether the signup succeeded
`errorMessage`	string	`by you`	Error message when `success` is `false`

`purchase`

Analytics Web

await grain.trackPurchase({
  orderId: 'ORD-12345',
  total: 99.99,
  currency: 'USD',
  items: [
    { id: 'ITEM-1', name: 'Product A', price: 49.99, quantity: 2, category: 'electronics' }
  ],
  paymentMethod: 'credit_card',
  shippingMethod: 'express',
  tax: 8.50,
  shipping: 5.99,
  discount: 10.00,
  couponCode: 'SAVE10'
});

Property	Type	Collected	Description
`orderId`	string	`by you`	Unique order identifier
`total`	number	`by you`	Total order amount
`currency`	string	`by you`	Currency code, for example `USD` or `EUR`
`items`	array	`by you`	Purchased items
`paymentMethod`	string	`by you`	Payment method
`shippingMethod`	string	`by you`	Shipping method
`tax`	number	`by you`	Tax amount
`shipping`	number	`by you`	Shipping cost
`discount`	number	`by you`	Discount amount
`couponCode`	string	`by you`	Applied coupon code

`checkout`

Sent by trackCheckout when the checkout starts. The properties are the same as purchase, plus success.

Analytics Web

await grain.trackCheckout({
  orderId: 'ORD-12345',
  total: 99.99,
  currency: 'USD',
  items: [],
  paymentMethod: 'credit_card',
  success: true
});

`search`

Analytics Web

await grain.trackSearch({
  query: 'wireless headphones',
  results: 42,
  filters: { category: 'electronics', price: 'under-50' },
  sortBy: 'popularity',
  category: 'products',
  success: true
});

Property	Type	Collected	Description
`query`	string	`by you`	Search query text
`results`	number	`by you`	Number of results
`filters`	object	`by you`	Applied filters
`sortBy`	string	`by you`	Sort order
`category`	string	`by you`	Search category
`success`	boolean	`by you`	Whether the search succeeded

`add_to_cart`

Analytics Web

await grain.trackAddToCart({
  itemId: 'PROD-123',
  itemName: 'Wireless Headphones',
  price: 49.99,
  quantity: 1,
  currency: 'USD',
  category: 'electronics',
  variant: 'black'
});

Property	Type	Collected	Description
`itemId`	string	`by you`	Product ID
`itemName`	string	`by you`	Product name
`price`	number	`by you`	Unit price
`quantity`	number	`by you`	Quantity added
`currency`	string	`by you`	Currency code
`category`	string	`by you`	Product category
`variant`	string	`by you`	Product variant, for example a color or a size

`remove_from_cart`

Sent by trackRemoveFromCart. The properties are the same as add_to_cart.

Custom events

A custom event carries the properties that you pass. Read Name events for the naming convention.

Analytics Web

await grain.track('button_clicked', {
  button_id: 'signup-cta',
  button_text: 'Get Started',
  page: '/pricing',
  position: 'hero'
});

The SDK adds properties to every custom event. System events that start with _grain_ are the exception.

Property	Collected	Source
`device`, `browser`, `os`	`always`	Device detection
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	`with consent`	The current session
`first_touch_source`, `first_touch_medium`, `first_touch_campaign`, `first_touch_referrer_category`	`with consent`	First-touch attribution
`session_id`	`with consent`	The current session

As a result, every event has device context and attribution data for matrices and conversion tracking. A call of grain.track('signup', { plan: 'pro' }) sends:

{
  "plan": "pro",
  "device": "Desktop",
  "browser": "Chrome",
  "os": "macOS",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "spring_sale",
  "first_touch_source": "google",
  "first_touch_medium": "cpc",
  "first_touch_campaign": "spring_sale",
  "first_touch_referrer_category": "paid",
  "session_id": "..."
}

Properties that a custom event often needs:

Group	Properties
Context	`page`, `section`, `component`
Action details	`action_type`, `target`, `value`
User state	`is_authenticated`, `user_plan`, `user_role`
Experiment	`experiment_id`, `variant`
Performance	`duration`, `load_time`

Property scope

An event-scoped property exists on the event that carries it. Most properties are event-scoped. A user-scoped property exists on any event of the user. In a matrix, the filter “User Property (Any Event)” finds users who logged the property at least one time, on any event. These properties are user-scoped:

Property	Set on	Queried on
`first_touch_*`	`_grain_session_start`	Any event
`utm_*`	`page_view`	Any event, including conversion events
Properties from `setProperty`	The `setProperty` call	Any event

Read User properties.

Referrer categories

Category	Meaning
`organic`	A search engine: Google, Bing, Yahoo, and others
`paid`	Paid advertising, detected from `gclid`, `fbclid`, and similar parameters
`social`	A social network: Facebook, Twitter, LinkedIn, and others
`email`	An email client: Gmail, Outlook, and others
`referral`	Any other website
`direct`	No referrer: a typed URL or a bookmark

Browser and OS values

Property	Values
`browser`	`Chrome`, `Firefox`, `Safari`, `Edge`, `Opera`, `Unknown`
`os`	`Windows`, `macOS`, `Linux`, `Android`, `iOS`, `Unknown`

Configuration

Three options of GrainConfig change what the SDK collects.

Option	Effect
`disableAutoProperties: true`	The SDK adds no automatic properties
`stripQueryParams: true`	The `page` property has no query string. This is the default.
`allowedProperties: [...]`	Only the listed property names are sent

Analytics Web

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

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  disableAutoProperties: false,
  stripQueryParams: true,
  allowedProperties: ['page', 'button_id', 'action']
});

Rules for properties

Do not send null or undefined values. Leave the property out.
Use snake_case for property names.
Add page, section, and component to UI events.
Use the same event names across a user journey, so that a track can join them.
Test attribution with a URL that holds UTM parameters and a referrer.
Collect only the data that a report needs, and obey consent.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Standard events

`page_view`

`_grain_session_start`

`_grain_session_end`

`_grain_heartbeat`

`_grain_consent_granted`

Template events

`purchase`

`checkout`

`search`

`add_to_cart`

`remove_from_cart`

Custom events

Property scope

Referrer categories

Browser and OS values

Configuration

Rules for properties

​Standard events

​page_view

​_grain_session_start

​_grain_session_end

​_grain_heartbeat

​_grain_consent_granted

​Template events

​login

​signup

​purchase

​checkout

​search

​add_to_cart

​remove_from_cart

​Custom events

​Property scope

​Referrer categories

​Browser and OS values

​Configuration

​Rules for properties

Standard events

`page_view`

`_grain_session_start`

`_grain_session_end`

`_grain_heartbeat`

`_grain_consent_granted`

Template events

`login`

`signup`

`purchase`

`checkout`

`search`

`add_to_cart`

`remove_from_cart`

Custom events

Property scope

Referrer categories

Browser and OS values

Configuration

Rules for properties