Choose a version:

Analytics events

The AnalyticsEvent object holds the names of the analytics events that Hydrogen supports. Use these constants to publish page, product, collection, cart, and search view events, and to subscribe an analytics destination to specific events.

The cart analytics functions publish the cart events for you.

Import AnalyticsEvent from @shopify/hydrogen.

Render ShopifyScripts before you publish events. The component creates the analytics bus at window.Shopify.analytics.

Anchor to PropertiesProperties

The names of the analytics events that Hydrogen supports. Pass a value as the event name when you publish an event or subscribe a destination. TypeScript narrows the payload to match the event name.

Anchor to CART_UPDATED CART_UPDATED 'cart_updated' required: Cart tracking publishes this event when the cart changes.
Anchor to CART_VIEWED CART_VIEWED 'cart_viewed' required: Publish when a customer views the cart. The payload carries the current cart.
Anchor to COLLECTION_VIEWED COLLECTION_VIEWED 'collection_viewed' required: Publish when a customer views a collection. The payload identifies the collection by ID and handle.
Anchor to PAGE_VIEWED PAGE_VIEWED 'page_viewed' required: Publish when a customer views a page. Hydrogen fills in the current URL when the payload has none.
Anchor to PRODUCT_ADD_TO_CART PRODUCT_ADD_TO_CART 'product_added_to_cart' required: Cart tracking publishes this event when the customer adds a line or raises a line's quantity.
Anchor to PRODUCT_REMOVED_FROM_CART PRODUCT_REMOVED_FROM_CART 'product_removed_from_cart' required: Cart tracking publishes this event when the customer removes a line or lowers a line's quantity.
Anchor to PRODUCT_VIEWED PRODUCT_VIEWED 'product_viewed' required: Publish when a customer views a product. The payload lists the viewed products.
Anchor to SEARCH_VIEWED SEARCH_VIEWED 'search_viewed' required: Publish when a customer views search results. The payload carries the search term.

Examples

TypeScript

import { AnalyticsEvent } from "@shopify/hydrogen";

export function publishPageView() {

window.Shopify?.analytics?.publish(AnalyticsEvent.PAGE_VIEWED);

}

export function publishCollectionView(collection: { id: string; handle: string }) {

window.Shopify?.analytics?.publish(AnalyticsEvent.COLLECTION_VIEWED, {

collection: { id: collection.id, handle: collection.handle },

});

}

Examples

Description

Publish page and collection views through the analytics bus.

TypeScript

import { AnalyticsEvent } from "@shopify/hydrogen";

export function publishPageView() {
  window.Shopify?.analytics?.publish(AnalyticsEvent.PAGE_VIEWED);
}

export function publishCollectionView(collection: { id: string; handle: string }) {
  window.Shopify?.analytics?.publish(AnalyticsEvent.COLLECTION_VIEWED, {
    collection: { id: collection.id, handle: collection.handle },
  });
}

Anchor to Event payloadsEvent payloads

A destination callback receives the payload for the event that the destination subscribes to. Every view event payload accepts an optional page URL, shop, and custom data. When a payload leaves out the URL or shop, the analytics bus adds the current page URL and the shop that you pass to ShopifyScripts.

Every payload includes BasePayload, and every view event payload also includes UrlPayload. The table lists the payload type for each event and the fields that the payload adds.

Event	Payload
`PAGE_VIEWED`	`PageViewPayload` adds no fields.
`PRODUCT_VIEWED`	`ProductViewPayload` adds `ProductsPayload`, the products that the customer views.
`COLLECTION_VIEWED`	`CollectionViewPayload` adds `CollectionPayload`, the ID and handle of the collection that the customer views.
`CART_VIEWED`	`CartViewPayload` adds `CartPayload`, the current cart.
`SEARCH_VIEWED`	`SearchViewPayload` adds `SearchPayload`, the customer's search term and optional search results.
`CART_UPDATED`	`CartUpdatePayload` adds `CartChangePayload`, the current cart and the cart before the change.
`PRODUCT_ADD_TO_CART`, `PRODUCT_REMOVED_FROM_CART`	`CartLineUpdatePayload` adds `CartChangePayload` and `CartLinePayload`, the line before and after the change.

For a new line, the payload has only currentLine. For a removed line, the payload has only prevLine. For a quantity change, the payload has prevLine and currentLine.

Cart update and cart line payloads also carry OtherData, which holds extra keys. Cart tracking adds eventTimestamp, the publish time in milliseconds.

Anchor to basepayloadBasePayload

The shop and custom data that every analytics event payload carries.

Anchor to customData customData Record<string, unknown>: Custom values for destinations. Cart tracking copies the bus configuration's custom data here.
Anchor to shop shop | null: The shop and sales channel. The bus fills in the configured shop when the payload omits the key, and normalizes the shop ID to a Shop GID.

ShopAnalytics

Identifies the shop and sales channel in every analytics payload. The `hydrogen` channel carries the storefront ID. The `headless` channel omits the storefront ID.

HydrogenShopAnalytics | HeadlessShopAnalytics

HydrogenShopAnalytics

The shop and storefront for a storefront on the Hydrogen sales channel.

channel
The Hydrogen sales channel serves the storefront.
```
'hydrogen'
```
shopId
The shop's ID, as a numeric string or a Shop GID.
```
string
```
storefrontId
The Hydrogen storefront's ID.
```
string
```

HeadlessShopAnalytics

The shop for a storefront on the Headless sales channel.

channel
The Headless sales channel serves the storefront.
```
'headless'
```
shopId
The shop's ID, as a numeric string or a Shop GID.
```
string
```
storefrontId
Leave the storefront ID out. The Headless sales channel has no storefront ID.
```
never
```

Anchor to urlpayloadUrlPayload

The page URL that every view event payload carries.

Anchor to url url string: The page URL. For view events, the bus fills in the current URL when the payload omits it.

Anchor to productspayloadProductsPayload

The products in a product_viewed event.

Anchor to products products Array< & > required: The products that the customer views.

ProductPayload

A product in a product view payload.

id
The product ID.
```
string
```
price
The selected variant's price.
```
MoneyV2
```
productType
The product type.
```
string
```
quantity
The selected quantity.
```
number
```
sku
The selected variant's SKU, or `null` when the variant has none.
```
string | null
```
title
The product title.
```
string
```
variantId
The selected variant's ID.
```
string
```
variantTitle
The selected variant's title.
```
string
```
vendor
The product vendor.
```
string
```

MoneyV2

A price with an amount and a currency code, in the `MoneyV2` shape that the Storefront API and Customer Account API return. The currency code accepts any string, including Customer Account API currencies such as USDC that the Storefront API currency enum doesn't list.

amount
Decimal amount as a string, such as `19.99`. `formatMoney` throws an error when the amount doesn't parse as a number.
```
string
```
currencyCode
Currency code, such as `USD`, in any letter case. A code that isn't three letters formats as a decimal amount followed by the code, such as `19.00 USDC`. An unrecognized three-letter code appears as the code, such as `XYZ 19.00`.
```
string
```

OtherData

Extra keys that a payload can carry. Cart tracking adds `eventTimestamp`, the publish time in milliseconds.

Anchor to collectionpayloadCollectionPayload

The collection in a collection_viewed event.

Anchor to collection collection { id: string; handle: string; } required: The ID and handle of the collection that the customer views.

Anchor to cartpayloadCartPayload

The current cart in a cart event.

Anchor to cart cart | null required: The current cart.

AnalyticsCart

A cart snapshot in cart analytics payloads.

cost

The currency codes of the cart's subtotal and total.

{ subtotalAmount?: { currencyCode?: string; }; totalAmount?: { currencyCode?: string; }; }

id
The cart ID.
```
string
```
lines
The cart lines, as a `nodes` list or an `edges` list. Cart tracking fills `nodes`.
```
{ nodes?: AnalyticsCartLine[]; edges?: { node: AnalyticsCartLine; }[]; }
```
updatedAt
The time of the cart's last update, as an ISO 8601 string.
```
string
```

AnalyticsCartLine

A cart line in an analytics payload, with the Storefront API fields that cart tracking reads.

id
The cart line ID.
```
string
```

merchandise

The variant on the line, with its product.

{ id: string; title: string; price: { amount: string; currencyCode?: string; }; sku?: string; product: { id: string; title: string; vendor: string; productType?: string; handle?: string; }; }

quantity
The number of units on the line.
```
number
```

Anchor to searchpayloadSearchPayload

The search term and results in a search_viewed event.

Anchor to searchTerm searchTerm string required: The customer's search query.
Anchor to searchResults searchResults unknown: The search results, in any shape that your destinations read.

Anchor to cartchangepayloadCartChangePayload

The current cart and the cart before the change, in a cart update or cart line event.

Anchor to cart cart | null required: The current cart.
Anchor to prevCart prevCart | null required: The cart before the change, or null when cart tracking has no earlier snapshot.

Anchor to cartlinepayloadCartLinePayload

The cart line before and after the change, in a product_added_to_cart or product_removed_from_cart event.

Anchor to currentLine currentLine: The line after the change.
Anchor to prevLine prevLine: The line before the change.

Examples

TypeScript

import { AnalyticsEvent } from "@shopify/hydrogen";

export function addConsoleDestination() {

return window.Shopify?.analytics?.addDestination({

name: "console-logger",

setup({ subscribe }) {

return subscribe(AnalyticsEvent.PRODUCT_ADD_TO_CART, (payload) => {

console.log("[analytics] product_added_to_cart", payload.currentLine);

});

}

Examples

Description

Add a destination that logs the added cart line from each add-to-cart event.

TypeScript

import { AnalyticsEvent } from "@shopify/hydrogen";

export function addConsoleDestination() {
  return window.Shopify?.analytics?.addDestination({
    name: "console-logger",
    setup({ subscribe }) {
      return subscribe(AnalyticsEvent.PRODUCT_ADD_TO_CART, (payload) => {
        console.log("[analytics] product_added_to_cart", payload.currentLine);
      });
    },
  });
}

Was this page helpful?