# Integrate Shopify Hydrogen with Croct

Automatically track events and ptimize your Shopify headless storefront.

This integration connects your [Shopify](https://www.shopify.com) store to Croct. Once set up, it renders dynamic content, automatically tracks your storefront's e-commerce events, and enriches user profiles with your customers' data, so you can build audiences, run AB tests, and personalize the shopping experience.

> **Headless storefronts**
>
> This integration targets stores built with [Shopify Hydrogen](https://hydrogen.shopify.dev), Shopify's headless React framework. If your store runs on a classic [Liquid](https://shopify.dev/docs/storefronts/themes/liquid) theme (the Online Store), you should use the [JavaScript SDK](/reference/sdk/javascript/integration) for dynamic content rendering and, when your theme already uses **GTM or GA4**, the [Google Tag Manager integration](/immersion/integrations/analytics/google-tag-manager) for automatic event tracking.

## How it works

The [Hydrogen SDK](https://github.com/croct-tech/plug-hydrogen) plugs into your storefront's server-side rendering and its analytics pipeline:

- **Dynamic content rendering:** You [fetch a slot](/reference/sdk/hydrogen/content-rendering) in a route loader and render it directly from the loader data, so the dynamic content markup ships with the initial server response.
- **Automatic event tracking:** Once the provider sits inside Shopify's [`<Analytics.Provider>`](https://shopify.dev/docs/api/hydrogen/latest/components/analytics/analytics-provider), the SDK subscribes to Shopify's storefront analytics and forwards each event to Croct. No manual instrumentation is required for the standard storefront events.
- **User identification:** When your storefront uses [Shopify customer accounts](https://shopify.dev/docs/api/customer-accounts), the logged-in customer is [identified on every request](/reference/sdk/hydrogen/data-collection#user-identity) out of the box, so their experience stays consistent across devices and sessions.

The SDK works with both **[React Router 7](https://reactrouter.com)** and **[Remix](https://remix.run)** Hydrogen apps, and the CLI wires up whichever one your storefront uses.

> **Dynamic content with no flicker**
>
> Because Hydrogen renders on the server, Croct resolves content in your loaders and the page arrives with dynamic content already applied. There's no client-side flash of default content before the personalized or experiment variant version loads.

## Event mapping

The SDK maps Shopify's [storefront analytics events](https://shopify.dev/docs/api/hydrogen/latest/utilities/analytics) to Croct's [e-commerce and engagement events](/reference/event/overview):

| Shopify analytics event    | Croct event                                                         |
| -------------------------- | ------------------------------------------------------------------- |
| Product view               | [`productViewed`](/reference/event/types/ecommerce/product-viewed)  |
| Cart view                  | [`cartViewed`](/reference/event/types/ecommerce/cart-viewed)        |
| Cart update                | [`cartModified`](/reference/event/types/ecommerce/cart-modified)    |
| Collection and search view | [`interestShown`](/reference/event/types/engagement/interest-shown) |

For events beyond the standard storefront set, you can [track custom events](/reference/sdk/hydrogen/event-tracking#custom-events) using the SDK instance.

> **Consent-aware by default**
>
> With the default `auto` mode, the SDK never tracks events until Shopify's [Customer Privacy API](https://shopify.dev/docs/api/customer-privacy) reports that tracking is allowed, so your storefront stays compliant out of the box. See [event tracking](/reference/sdk/hydrogen/event-tracking#consent) for the details.

## Prerequisites

Before you start, make sure you have:

- A Croct account with a workspace and application set up.
- A Shopify storefront built with [Hydrogen](https://hydrogen.shopify.dev) on [React Router 7](https://reactrouter.com) or [Remix](https://remix.run).
- Shopify's [standard analytics components](https://shopify.dev/docs/api/hydrogen/latest/components/analytics/analytics-provider) in place, so the SDK can forward storefront events.

## Set up the integration

The fastest way to connect your storefront is through the [Croct CLI](/reference/cli/installation).

1. **Initialize the SDK**

   From your Hydrogen project, run the CLI. It detects your setup, installs the SDK, and wires the provider and request context for you.

   **Command to initialize your project**

   ```sh
   croct init
   ```

2. **Add your first slot**

   Generate the types and a working example for a [slot](/explanation/slot) you can adapt to your storefront.

   **Command to add a slot to your project**

   ```sh
   croct@latest add slot --example
   ```

3. **Render personalized content**

   [Fetch the slot](/reference/sdk/hydrogen/content-rendering) in a route loader and render it from the loader data.

For a manual, step-by-step walkthrough instead, follow the [manual installation guide](/reference/sdk/hydrogen/manual-installation).

## Verify the integration

Once the SDK is running, confirm that content, events, and customer data flow into Croct.

1. **Browse your store**

   Open your storefront and view a product, add it to the cart, and start a checkout. Sign in so customer data is available.

2. **Check the events**

   Open the [dashboard page](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/dashboard/conversion) in the admin app and confirm that events are arriving.

3. **Check the profile**

   Open the [user profiles page](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/profiles), open a profile, and confirm it reflects the identified customer.

With content, store events, and customer data flowing into Croct, you can now personalize your storefront, run AB tests, and create audiences from shopping behavior.

## Explore

- [Hydrogen SDK](/reference/sdk/hydrogen/integration): Dive into the full SDK reference for Shopify Hydrogen.
- [Croct Hydrogen demo](https://github.com/croct-tech/croct-hydrogen-project): Check out the Croct Hydrogen demo project on GitHub.