Analytics
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.
How it works
Anchor link to section titled "How it works"The following diagram describes how analytics data is processed on the server and client in Hydrogen:
On the server, the
useServerAnalytics
hook collects data in a single render request.On the client, the data is streamed as part of the
Suspense
component. This single render request waits for all queries to complete, outputs the collected data from the server-side, and triggers aPAGE_VIEW
event.Events can be published to external endpoints from the client or server-side:
- Client: The client can subscribe to events and publish them to external endpoints.
- Server: Events are published to the
/__event
endpoint, a server analytics route. You can use server analytics connectors to publish the event to an external endpoint.
Default events
Anchor link to section titled "Default events"By default, Hydrogen publishes the following events to subscribers (ClientAnalytics.subscribe
):
Event name | When the event is published |
---|---|
PAGE_VIEW |
A customer visits a storefront page |
ADD_TO_CART |
A customer adds an item to their cart |
UPDATE_CART |
A customer updates an item in their cart |
REMOVE_FROM_CART |
A customer removes an item from their cart |
DISCOUNT_CODE_UPDATED |
A discount code that a customer applies to a cart is updated |
VIEWED_PRODUCT |
A customer views a product details page. This is set with publishEventsOnNavigate on product pages. |
PERFORMANCE |
The performance metrics for page loads in a Hydrogen app. This is available when you opt in to <PerformanceMetrics /> . |
Subscribe to an event
Anchor link to section titled "Subscribe to an event"Subscribe to an event to enable your Hydrogen app to listen for the event. The following steps describe how to subscribe to the PAGE_VIEW
event.
Create a new client component in the
/components
directory of your Hydrogen app. For example,components/AnalyticsListener.client.jsx
.In your client component, add the following code to subscribe to the event:
Add your client component to your app's top-level React component (
App.server.jsx
):
Configure a custom event
Anchor link to section titled "Configure a custom event"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:
Retrieving data from other parts of your Hydrogen app
Anchor link to section titled "Retrieving data from other parts of your Hydrogen app"You can collect analytics data wherever you make queries. For example, to gather information about the collection that a customer has interacted with, you can make collectionName
and collectionId
available when you receive the PAGE_VIEW
event:
You can also capture events in client components. For example, when a customer makes a query, such as adding an item to their cart, or clicking on a promotional banner, you can capture the event in your client component:
To retrieve the data that's available elsewhere in your Hydrogen app, you can add the following code to your server components:
Caution:
Don't use the data from useServerAnalytics()
for rendering. This will cause occasional mismatches during hydration.
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 shows how to retrieve analytics data from a client component:
Send analytics data from the server-side
Anchor link to section titled "Send analytics data from the server-side"Some data is only available on the server. For example, detailed information about how many API calls a single page render makes and how long each API call took is only available on the server. This is information that users don't need to see and helps development teams gain insights about performance. If this is your use case, then sending analytics data from the server-side a good option.
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
__event
endpoint.Create a server-side analytics connector and pass it into the
serverAnalyticsConnectors
configuration:
The following table describes the request function parameters for ServerAnalyticsConnector
:
Parameter | Type | Description |
---|---|---|
request |
request | The analytics request object. |
data |
object or text | The result from .json() or .text() . |
contentType |
string | The content type. Valid values: json or text . |
Unsubscribe from an event
Anchor link to section titled "Unsubscribe from an event"You can unsubscribe from events that you no longer want your Hydrogen app to track. The following example shows how to unsubscribe from the PAGE_VIEW
event:
Performance metrics
Anchor link to section titled "Performance metrics"Performance metrics provide insight into how fast pages are loading in your Hydrogen app. For example, you might want to gather the following metrics for full and sub page loads:
- Time to First Byte (TTFB): The time between a browser requesting a page and receiving the first byte of information from the server
- First Contentful Paint (FCP): The time it takes for a browser to render content on a page
- Largest Contentful Paint (LCP): The time it takes to render and interact with the largest content element on the page
- Duration: The total amount of time it takes for a page to finish streaming
You can opt in to receive performance metrics for page loads in your Hydrogen app by including <PerformanceMetrics />
and PerformanceMetricsServerAnalyticsConnector
in App.server.js
.
If you want to see performance debug metrics displayed in your browser console log, then include <PerformanceMetricsDebug />
in your client component:
Example analytics connectors
Anchor link to section titled "Example analytics connectors"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:
Testing analytics connectors
Anchor link to section titled "Testing analytics connectors"The following example shows how to write an end-to-end (E2E) test for Google Analytics 4. This test will also work for Google Tag Manager if you've configured it with Google Analytics 4:
- Learn how to configure queries to preload in your Hydrogen app.
- Learn how to customize the output of SEO-related tags in your Hydrogen client and server components.
- Learn about Hydrogen's configuration properties and how to change the location of the configuration file.