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 initialize the subscription to the PAGE_VIEW event:

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

4. Test the event by refreshing the root page of your app. The PAGE_VIEW payload object details display in the browser’s console log.

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.

1. Emit a custom event by using the publish method and specifying a custom event name:

2. In AnalyticsListener, use the ClientAnalytics component to subscribe to your custom event by name:

You can gather analytics data wherever you make queries. For example, to capture information about the Shopify product collection that a customer has interacted with, you can add the collectionName and collectionId fields to the PAGE_VIEW event object.

When you reload the collection page you, a PAGE_VIEW event displays in the console that includes the new collectionName and collectionId fields.

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 storefront, 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 information that isn't relevant to storefront customers, but might be helpful for the development team, is only available on the server. For example, server-side information includes detailed information about how many API calls a single page render makes, or how long each API call took.

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 accepts-marketing event:

Performance metrics provide insight into how fast pages are loading in your Hydrogen storefront. 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 storefront by including <PerformanceMetrics /> in App.server.js.

If you want to see performance debug metrics displayed in your browser console log, then include <PerformanceMetricsDebug /> in App.server.js:

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:

• ShopifyAnalytics

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