Hydrogen includes support for analytics that give you insight into how customers are interacting with a custom storefront.
This guide describes how to subscribe to the default events that Hydrogen offers, configure custom events, send analytics data from the server-side, and unsubscribe from events. It also provides example implementations of client analytics connectors, and shows how to write an end-to-end (E2E) for testing analytics connectors.
Subscribe to eventsAnchor link to section titled "Subscribe to events"
Subscribe to an event to enable your Hydrogen app to listen for the event. The following steps describe how to subscribe to the
Create a new client component in the
/componentsdirectory of your Hydrogen app. For example,
In your client component, add the following code to initialize the subscription to the
Add your client component to your app's top-level React component (
Test the event by refreshing the root page of your app. The
PAGE_VIEWpayload object details display in the browser’s console log.
Unsubscribe from eventsAnchor link to section titled "Unsubscribe from events"
You can unsubscribe from events that you no longer want your Hydrogen app to track. The following example shows how to unsubscribe from the
Configure custom eventsAnchor link to section titled "Configure custom events"
Aside from the default events that Hydrogen supports, you can also configure custom events. For example, you might want to configure a custom event that tracks the pages where a promotional banner is being clicked the most.
Emit a custom event by using the publish method and specifying a custom event name:
AnalyticsListener, use the
ClientAnalyticscomponent to subscribe to your custom event by name:
Retrieve data from other parts of your Hydrogen storefrontAnchor link to section titled "Retrieve data from other parts of your Hydrogen storefront"
You can capture analytics data wherever you make queries. The following are some examples:
Capture customer interaction dataAnchor link to section titled "Capture customer interaction data"
You can capture data on how customers are interacting with your storefront.
The following example captures the Shopify product collection that a customer has interacted with.
collectionId fields are added to the
PAGE_VIEW event object:
When the collection page is reloaded, a
PAGE_VIEW event displays in the console that includes the new
Capture events in client componentsAnchor link to section titled "Capture events in client components"
You can also capture events in client components, like when a customer makes a query that adds an item to their cart.
The following example captures when a customer clicks a promotional banner:
Retrieve analytics from client componentsAnchor link to section titled "Retrieve analytics from client components"
The following example shows how to retrieve page analytics data from a client component:
Retrieve data that's available elsewhereAnchor link to section titled "Retrieve data that's available elsewhere"
To retrieve the data that's available elsewhere in your Hydrogen storefront, you can add the following code to your server components:
Caution: Don't use the data from
useServerAnalytics()for rendering. This causes occasional mismatches during hydration.
Trigger analytics events on navigationAnchor link to section titled "Trigger analytics events on navigation"
If you need to trigger additional analytics events on navigation, then you can specify a list of analytics events to publish in your server component.
The following example publishes when a customer views a product:
Send analytics data from the server-sideAnchor link to section titled "Send analytics data from the server-side"
To send analytics data from the server-side, complete the following steps:
Create a client-side analytics listener that makes a fetch call to the
Create a server-side analytics connector:
Pass the analytics connector into the
Performance metricsAnchor link to section titled "Performance metrics"
Hydrogen's performance metrics provide insight into how fast pages are loading in your Hydrogen storefront.
Opt-in to page load performance metricsAnchor link to section titled "Opt-in to page load performance metrics"
<PerformanceMetrics /> in
Log performance debug metricsAnchor link to section titled "Log performance debug metrics"
To see performance debug metrics displayed in your browser console log, then include
<PerformanceMetricsDebug /> in
Implement a client analytics connectorAnchor link to section titled "Implement a client analytics connector"
The following example shows an implementation of a client analytics connector with Google Analytics 4:
The following example shows an implementation of a client analytics connector using the getanalytics.io Google Tag Manager package:
Test analytics connectors end-to-endAnchor link to section titled "Test analytics connectors end-to-end"
The following example shows how to write an end-to-end (E2E) test for Google Analytics 4.