--- gid: 8559f2f8-940b-45e1-a897-9c49798bb285 title: Analytics event tracking with Hydrogen description: Learn how to set up analytics with Hydrogen and Oxygen, and transmit metrics events to Shopify analytics. --- <Repo extension="javascript" href="https://github.com/Shopify/hydrogen/tree/main/examples/analytics" /> <Repo extension="typescript" href="https://github.com/Shopify/hydrogen/tree/main/examples/analytics" /> <Picker name="framework"> <PickerOption name="hydrogen" /> </Picker> <Picker name="extension"> <PickerOption name="javascript" /> <PickerOption name="typescript" /> </Picker> <Overview> Learn how to implement analytics events in your Hydrogen project and send tracked events to Shopify analytics and, optionally, third-party services. <Notice type="info" title="Tip">Hydrogen includes analytics by default as of version 2024.4.3. You only need to do these tasks if you're upgrading an older version.</Notice> </Overview> <Requirements> <Requirement href="https://apps.shopify.com/hydrogen" label="Hydrogen channel installed" /> <Requirement href="/docs/storefronts/headless/hydrogen/getting-started" label="Complete “Getting started with Hydrogen and Oxygen”" /> <Requirement href="/docs/storefronts/headless/hydrogen/analytics/consent" label="Configure Customer Privacy API settings" /> </Requirements> <StepSection> <Step> ## Update <If extension="typescript">root.tsx</If><If extension="javascript">root.jsx</If> To start sending analytics events, you need to set up the `Analytics` component in your Hydrogen project's root route. <Substep> Import the `Analytics` component and the `getShopAnalytics` utility from Hydrogen. The `Analytics` component automatically checks for [consent](/docs/storefronts/headless/hydrogen/analytics/consent) before collecting any event data. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> <br /> <Notice type="warning">If you haven’t [configured consent](/docs/storefronts/headless/hydrogen/analytics/consent) through the Customer Privacy API, then analytics events won't fire and no data is tracked.</Notice> <Substep> Update the root loader function to destructure the `env` object from the Hydrogen context. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="env" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="env" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> <Substep> Return the `shop` object by calling the `getShopAnalytics` utility. This function automatically collects the credentials required to send analytics events to Shopify. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="getshop" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="getshop" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> <Resources> - [getShopAnalytics](/docs/api/hydrogen/current/utilities/getshopanalytics) </Resources> </Substep> <Substep> Return the `consent` object with its required values. If you're using Shopify's cookie banner, then make sure `withPrivacyBanner` is set to `true`. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="consent" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="consent" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> <Substep> Update the root component to wrap your Hydrogen app with the Analytics provider component. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="provider" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="provider" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> <br/> At this point, your app is set up to send analytics events to Shopify, but there aren't any events configured. In the next step, we'll add events to your storefront routes. </Step> <Step> ## Update routes with analytics subcomponents To track page views, you need to add pageview components to each route you want to track. <Substep> In your product details page route, import the `Analytics` component from Hydrogen. <CodeRef extension="javascript" displayPath="/app/routes/products.$handle.jsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/routes/products.%24handle.jsx" /> <CodeRef extension="typescript" displayPath="/app/routes/products.$handle.tsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/routes/products.%24handle.tsx" /> <Resources> - [Analytics.Provider](/docs/api/hydrogen/current/components/analytics/analytics-provider) </Resources> </Substep> <Substep> Add the `Analytics.ProductView` component to your nested route. This component sends a pageview event to Shopify when the route is loaded. The `ProductView` subcomponent takes a `data` prop with the product data to send to Shopify. <CodeRef extension="javascript" displayPath="/app/routes/products.$handle.jsx" tag="component" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/routes/products.%24handle.jsx" /> <CodeRef extension="typescript" displayPath="/app/routes/products.$handle.tsx" tag="component" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/routes/products.%24handle.tsx" /> <Resources> - [Analytics.ProductView](/docs/api/hydrogen/current/components/analytics/analytics-productview) </Resources> </Substep> <Substep> Repeat this pattern for each route you want to track. Different routes have different preset analytics subcomponents, and require different data payloads. Follow the same pattern for collections routes... <CodeRef extension="javascript" displayPath="/app/routes/collections.$handle.jsx" tag="collections" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/routes/collections.%24handle.jsx" /> <CodeRef extension="typescript" displayPath="/app/routes/collections.$handle.tsx" tag="collections" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/routes/collections.%24handle.tsx" /> <Resources> - [Analytics.CollectionView](/docs/api/hydrogen/current/components/analytics/analytics-collectionview) </Resources> </Substep> <Substep> ...the search results route... <CodeRef extension="javascript" displayPath="/app/routes/search.jsx" tag="search" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/routes/search.jsx" /> <CodeRef extension="typescript" displayPath="/app/routes/search.tsx" tag="search" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/routes/search.tsx" /> <Resources> - [Analytics.SearchView](/docs/api/hydrogen/current/components/analytics/analytics-searchview) </Resources> </Substep> <Substep> ...and the cart route. <CodeRef extension="javascript" displayPath="/app/routes/cart.jsx" tag="cart" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/routes/cart.jsx" /> <CodeRef extension="typescript" displayPath="/app/routes/cart.tsx" tag="cart" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/routes/cart.tsx" /> <Resources> - [Analytics.CartView](/docs/api/hydrogen/current/components/analytics/analytics-cartview) </Resources> </Substep> <Substep> If your cart is a side panel, you can publish the `cart_viewed` event with `useAnalytics`. <CodeRef extension="javascript" displayPath="/app/components/Header.jsx" tag="cartview" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/Header.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/Header.tsx" tag="cartview" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/Header.tsx" /> </Substep> <Substep> If you get the following error message in your browser console, make sure your cart query includes the`updatedAt` field. ```[h2:error:CartAnalytics] Can't set up cart analytics events because the `cart.updatedAt` value is missing from your GraphQL cart query. In standard Hydrogen projects, the cart query is contained in `app/lib/fragments.js`. Make sure it includes `cart.updatedAt`.``` <CodeRef extension="javascript" displayPath="/app/lib/fragments.js" tag="query" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/lib/fragments.js" /> <CodeRef extension="typescript" displayPath="/app/lib/fragments.ts" tag="query" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/lib/fragments.ts" /> </Substep> </Step> <Step> ## Optional: Implement custom analytics with third-party services Using the Analytics provider component, you can create your own subcomponents to send events to third-party analytics services, in addition to Shopify. <Substep> In your custom component file, import the `useAnalytics` hook from Hydrogen. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="import" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> </Substep> <Substep> Export your custom component so it can be used in your Hydrogen routes. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="export" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="export" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> </Substep> <Substep> The `subscribe` function provided by `useAnalytics` listens for standard analytics events from your routes, and provides a callback function with the corresponding data. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="use" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="use" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> <Resources> - [Web Pixels API standard events](/docs/api/web-pixels-api/standard-events) </Resources> </Substep> <Substep> Register the analytics integration with `<Analytics.Provider>`. This will prevent any analytics events from being sent until this integration is ready. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="register" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="register" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> </Substep> <Substep> For each event you want to track in your custom analytics component, use the subscribe function to listen for the event and send the analytics data to your third-party analytics platform. This example just logs the event data to the console. It's up to you to replace this with your own custom analytics logic, depending on the platform you're using. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="subscribe" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="subscribe" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> </Substep> <Substep> Notify `<Analytics.Provider>` that this analytics integration is ready to receive events. <CodeRef extension="javascript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.jsx" tag="ready" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/components/ThirdPartyAnalyticsIntegration.jsx" /> <CodeRef extension="typescript" displayPath="/app/components/ThirdPartyAnalyticsIntegration.tsx" tag="ready" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/components/ThirdPartyAnalyticsIntegration.tsx" /> </Substep> <Substep> Once you've created your custom analytics component, import it into your root route. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="import-custom" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="import-custom" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> <Substep> Add your custom component to your app's root layout. Your component needs to be a child of the `Analytics.Provider` component in order to subscribe to events and receive analytics data. <CodeRef extension="javascript" displayPath="/app/root.jsx" tag="custom-component" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/js/app/root.jsx" /> <CodeRef extension="typescript" displayPath="/app/root.tsx" tag="custom-component" href="https://github.com/Shopify/hydrogen/blob/main/docs/shopify-dev/analytics-setup/ts/app/root.tsx" /> </Substep> </Step> </StepSection> <NextSteps> ### Next steps <CardGrid> <LinkCard href="/docs/storefronts/headless/hydrogen/analytics/validation"> #### Validate and troubleshoot Hydrogen analytics Test that your analytics are working and check for common errors </LinkCard> </CardGrid> </NextSteps>