React Components

The SDK provides React components and hooks for seamless integration with your Hydrogen application.

Lifecycle

On page load the SDK’s components and hooks fire in a fixed sequence. GloodProvider bootstraps the session first (v3 init), and useRecommendations waits for that to settle before fetching sections — so recommendations are always attributed to the init-issued visitor. Sequence of hooks:

GloodProvider mounts — subscribes to Shopify analytics and, for a v3 client, calls /v3/headless/init once. (v2 clients skip init.)
useGloodInit() — returns the init response once it resolves (null until then, and always null for v2). Also readable synchronously via client.getInitData().
useGloodInitReady() — flips to true when init settles (or immediately for v2 / no client). This is the gate the next step waits on.
useRecommendations(params) — holds in loading until useGloodInitReady() is true, then fetches /v3/headless/sections. The request carries the init-issued user_id.
useGloodAnalytics() + trackRender/View/Click/AddToCart — fire attribution events (through the recommendations app) to /v3/headless/events as the visitor interacts.

For a v2 client there is no init call: useGloodInitReady() is true immediately, so useRecommendations fetches without waiting. Events route to /api/storefront/event instead of /v3/headless/events.

GloodProvider

A React context provider that automatically subscribes to Shopify Analytics events, manages pixel tracking for the recommendations app, and — for v3 clients — fires the headless session init on mount.

Signature

function GloodProvider({
  client,
  loaderData,
  children
}: GloodProviderProps): React.ReactElement

Props

Prop	Type	Required	Description
`client`	`GloodClient`	Yes	Glood client instance created with `createGlood()`
`loaderData`	`unknown`	No	Route loader data forwarded to enabled apps
`children`	`React.ReactNode`	Yes	Child components to wrap

Basic Usage

import { Analytics } from '@shopify/hydrogen';
import { GloodProvider, createGlood, recommendations } from '@glood/hydrogen';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3, default 3
}).use(recommendations());

export default function App() {
  return (
    <Analytics>
      <GloodProvider client={glood} loaderData={data}>
        <Outlet />
      </GloodProvider>
    </Analytics>
  );
}

How It Works

The GloodProvider component:

Creates React Context - Provides the Glood client to all child components
Fires Headless Init - On mount, a v3 client calls POST /api/storefront/v3/headless/init once to bootstrap the session. The response is exposed via useGloodInit(). For a v2 client this is a no-op.
Subscribes to Analytics - Uses Hydrogen’s useAnalytics() hook to receive events
Distributes Events - Routes events to the recommendations app based on its subscriptions
Checks Consent - Verifies customer privacy permissions before sending pixels
Handles Errors - Provides comprehensive error handling and debug logging

The headless init runs exactly once per provider mount and only when the client is configured for API version 3 (the default). It replays a persisted visitor id, creates a per-visit id, and returns the shop config, storefront token, and visitor history. Init failures are logged but never block rendering.

Event Subscription Flow

Error Handling

The provider includes comprehensive error handling:

// Invalid client handling
<GloodProvider client={null}>
  <App />
</GloodProvider>
// Logs: "[Glood] GloodProvider: client is required"
// Renders children without Glood functionality

// Debug mode error logging
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: true, // Enable detailed error logging
});

<GloodProvider client={glood} loaderData={data}>
  <App />
</GloodProvider>

Server-Side Rendering

The provider automatically handles SSR — analytics subscriptions only run in the browser:

// Only runs on client-side
useEffect(() => {
  if (typeof window === 'undefined' || !analytics?.customerPrivacy) {
    if (debug) {
      console.log('[Glood Debug] Skipping analytics setup: not in browser');
    }
    return;
  }
  // Setup analytics subscriptions
}, [clientConfig, analytics]);

useGloodAnalytics

A React hook that provides access to the Glood client from context.

Signature

function useGloodAnalytics(): GloodClient | null

Returns

Type	Description
`GloodClient \| null`	The Glood client instance or `null` if used outside provider

Usage

import { useGloodAnalytics } from '@glood/hydrogen';

function MyComponent() {
  const glood = useGloodAnalytics();

  if (!glood) {
    // Component used outside GloodProvider
    return <div>Glood not available</div>;
  }

  // Access client properties
  const isDebugMode = glood.debug;
  const enabledApps = glood.getEnabledApps();

  return (
    <div>
      <p>Debug mode: {isDebugMode ? 'On' : 'Off'}</p>
      <p>Enabled apps: {enabledApps.map(app => app.name).join(', ')}</p>
    </div>
  );
}

useGloodInit

A React hook that returns the /v3/headless/init response fired by GloodProvider on mount.

Signature

function useGloodInit(): InitResponse | null

Returns

Type	Description
`InitResponse \| null`	The headless init response. `null` until init resolves, and always `null` for v2 clients (init is v3-only).

The InitResponse carries the server-issued session identity and shop context: the echoed user_id, the per-visit visit_id, visitor history (browsed / cart / purchased), the shop config (currency, money format, storefront GraphQL version, integrations, analytics enabled), and the storefront token.

Usage

import { useGloodInit } from '@glood/hydrogen';

function CurrencyBadge() {
  const init = useGloodInit();

  // null until init resolves, and always null for v2 clients
  if (!init) return null;

  return <span>Currency: {init.config?.shop?.currency}</span>;
}

Outside React, read the same value synchronously with client.getInitData().

useGloodInitReady

A React hook that reports whether the page-load headless init has settled — resolved, failed, or skipped (v2 / no client). useRecommendations waits on this internally so the init call lands before the first sections request; you can use it to gate your own init-dependent calls.

Signature

function useGloodInitReady(): boolean

Returns

Type	Description
`boolean`	`false` while a v3 init is in flight; `true` once it settles (or immediately for v2 / no client, which have no init to wait for).

Usage

import { useGloodInitReady, useGloodAnalytics } from '@glood/hydrogen';

function useRecommendationsAfterInit(params) {
  const ready = useGloodInitReady();
  const client = useGloodAnalytics();

  useEffect(() => {
    if (!ready) return; // hold until init has run
    client?.getApp('recommendations')?.getRecommendations(params);
  }, [ready]);
}

useRecommendations

A React hook that fetches recommendation sections client-side (in the browser). Prefer this for client-side rendering; use fetchRecommendationSections(options, params) in SSR route loaders instead. Must be used within a GloodProvider whose client has the recommendations app registered.

Ordering: for a v3 client the hook waits for the page-load /v3/headless/init call to settle before fetching sections (it stays in the loading state until then). This guarantees init runs first and the sections request carries the init-issued visitor id. For v2 clients there is no init, so sections fetch immediately.

Full signature, parameters, and return fields are documented in the Recommendations API.

Usage

import { useRecommendations } from '@glood/hydrogen';

function ProductRecommendations({ productId }: { productId: string }) {
  const { sections, loading, error, trackClick } = useRecommendations({
    pageType: 'product_page',
    productId,
  });

  if (loading) return <div>Loading…</div>;
  if (error) return null;

  return (
    <>
      {sections.map(section => (
        <section key={section.id}>
          <h2>{section.title}</h2>
          {section.products.map(product => (
            <a
              key={product.product_id}
              href={`/products/${product.handle}`}
              onClick={() => trackClick({ section, product })}
            >
              {product.title}
            </a>
          ))}
        </section>
      ))}
    </>
  );
}

Provider Placement

Correct Placement

The GloodProvider must be placed correctly in your component tree:

// ✅ Correct - Inside Analytics, wrapping application routes
import { Analytics } from '@shopify/hydrogen';

export default function App() {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <Analytics>
          <GloodProvider client={glood} loaderData={data}>
            <Layout>
              <Outlet />
            </Layout>
          </GloodProvider>
        </Analytics>
        <Scripts />
      </body>
    </html>
  );
}

Incorrect Placement

// ❌ Incorrect - Outside Analytics component
export default function App() {
  return (
    <GloodProvider client={glood} loaderData={data}>
      <Analytics>
        <Outlet />
      </Analytics>
    </GloodProvider>
  );
}

// ❌ Incorrect - Inside individual routes
export default function ProductPage() {
  return (
    <GloodProvider client={glood} loaderData={data}>
      <ProductDetails />
    </GloodProvider>
  );
}

Debug Logging

Enable debug mode to see detailed component behavior:

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: process.env.NODE_ENV === 'development',
}).use(recommendations());

<GloodProvider client={glood} loaderData={data}>
  <App />
</GloodProvider>

Debug logs include:

[Glood Debug] Setting up event subscriptions for apps: ['recommendations']
[Glood Debug] Set analytics instance on recommendations app
[Glood Debug] App recommendations subscribes to events: ['page_viewed', 'product_viewed', ...]
[Glood Debug] All unique event types: ['page_viewed', 'product_viewed', ...]
[Glood Debug] Setting up centralized subscription for page_viewed
[Glood Debug] Received page_viewed event, distributing to interested apps
[Glood Debug] Apps interested in page_viewed: ['recommendations']
[Glood Debug] Processing page_viewed event for recommendations: { url: '/products/shirt', ... }
[Glood Debug] Consent granted for recommendations, processing event
[Glood Debug] Headless init complete: { user_id: '…', visit_id: '…', config: { … } }

Performance Considerations

Memoization

The provider uses React’s useMemo to prevent unnecessary re-renders:

const clientConfig = useMemo(() => ({
  debug: client.debug,
  enabledApps: client.getEnabledApps(),
  appsKeys: Array.from(client.apps.keys())
}), [client]);

Event Deduplication

Events are subscribed to only once per event type, regardless of how many apps are interested:

// Subscribe once per event type
allEventTypes.forEach((eventType: EventType) => {
  subscribe(eventType, (eventData: any) => {
    // Distribute to all interested apps
    const interestedApps = enabledAppsWithPixel.filter(app =>
      app.subscribedEvents.includes(eventType)
    );

    interestedApps.forEach(app => {
      app.handleEvent(eventType, eventData, client);
    });
  });
});

Lazy Loading

Analytics setup is deferred to prevent blocking:

useEffect(() => {
  const timer = setTimeout(() => {
    // Setup analytics subscriptions
  }, 0);

  return () => clearTimeout(timer);
}, [clientConfig, analytics]);

Error Scenarios

Missing Analytics

// Hydrogen analytics not available
if (!analytics?.customerPrivacy) {
  if (debug) {
    console.log('[Glood Debug] Skipping analytics setup: analytics not available');
  }
  return;
}

Network Errors

// Pixel transmission errors are handled gracefully
try {
  app.handleEvent(eventType, eventData, client);
} catch (error) {
  console.error('[Glood] Error processing event:', error);
  if (debug) {
    console.error('[Glood Debug] Event data:', eventData);
  }
}

// Events are not processed if consent is not granted
if (checkConsent(app.pixel.consent, canTrack, analytics)) {
  app.handleEvent(eventType, eventData, client);
} else {
  if (debug) {
    console.log(`[Glood Debug] Consent not granted for ${app.name}, skipping event`);
  }
}

Best Practices

1. Single Provider Instance

Use only one GloodProvider at the root of your application:

// ✅ Good - Single provider at root
<GloodProvider client={glood} loaderData={data}>
  <App />
</GloodProvider>

// ❌ Bad - Multiple providers
<GloodProvider client={glood1}>
  <Header />
</GloodProvider>
<GloodProvider client={glood2}>
  <Main />
</GloodProvider>

2. Client Stability

Create the client outside of the component to prevent recreating:

// ✅ Good - Client created once
const glood = createGlood(config).use(recommendations());

export default function App() {
  return (
    <GloodProvider client={glood} loaderData={data}>
      <Outlet />
    </GloodProvider>
  );
}

// ❌ Bad - Client recreated on every render
export default function App() {
  const glood = createGlood(config).use(recommendations());

  return (
    <GloodProvider client={glood} loaderData={data}>
      <Outlet />
    </GloodProvider>
  );
}

3. Conditional Hook Usage

Always check for null when using the hook:

function MyComponent() {
  const glood = useGloodAnalytics();

  // ✅ Good - Check for null
  if (!glood) {
    return <FallbackComponent />;
  }

  // Use glood safely
  const apps = glood.getEnabledApps();
}

4. Error Boundaries

Wrap the provider in error boundaries for production:

import { ErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error }) {
  return (
    <div>
      <h2>Glood Error</h2>
      <pre>{error.message}</pre>
    </div>
  );
}

export default function App() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <Analytics>
        <GloodProvider client={glood} loaderData={data}>
          <Outlet />
        </GloodProvider>
      </Analytics>
    </ErrorBoundary>
  );
}

​React Components

​Lifecycle

​GloodProvider

​Signature

​Props

​Basic Usage

​How It Works

​Event Subscription Flow

​Error Handling

​Server-Side Rendering

​useGloodAnalytics

​Signature

​Returns

​Usage

​useGloodInit

​Signature

​Returns

​Usage

​useGloodInitReady

​Signature

​Returns

​Usage

​useRecommendations

​Usage

​Provider Placement

​Correct Placement

​Incorrect Placement

​Debug Logging

​Performance Considerations

​Memoization

​Event Deduplication

​Lazy Loading

​Error Scenarios

​Missing Analytics

​Network Errors

​Consent Denial

​Best Practices

​1. Single Provider Instance

​2. Client Stability

​3. Conditional Hook Usage

​4. Error Boundaries

​See Also

React Components

Lifecycle

GloodProvider

Signature

Props

Basic Usage

How It Works

Event Subscription Flow

Error Handling

Server-Side Rendering

useGloodAnalytics

Signature

Returns

Usage

useGloodInit

Signature

Returns

Usage

useGloodInitReady

Signature

Returns

Usage

useRecommendations

Usage

Provider Placement

Correct Placement

Incorrect Placement

Debug Logging

Performance Considerations

Memoization

Event Deduplication

Lazy Loading

Error Scenarios

Missing Analytics

Network Errors

Consent Denial

Best Practices

1. Single Provider Instance

2. Client Stability

3. Conditional Hook Usage

4. Error Boundaries

See Also