Analytics

The following diagram describes how analytics data is processed on the server and client in Hydrogen:

1. On the server, the useServerAnalytics hook collects data in a single render request.

2. 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 a PAGE_VIEW event.

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

By default, Hydrogen publishes the following events to subscribers (ClientAnalytics.subscribe):

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.

1. Create a new client component in the /components directory of your Hydrogen app. For example, components/AnalyticsListener.client.jsx.

2. In your client component, add the following code to subscribe to the event:

3. Add your client component to your app's top-level React component (App.server.jsx):

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:

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:

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:

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:

1. Create a client-side analytics listener that makes a fetch call to the __event endpoint.

2. Create a server-side analytics connector and pass it into the serverAnalyticsConnectors configuration:

The following table describes the request function parameters for ServerAnalyticsConnector:

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 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:

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:

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.