Loading Recommendations

The SDK fetches the recommendation sections you configure in the Glood dashboard — complete with full product data (title, handle, prices, images, options, and variants) — so you can render them with your own React components. There are two ways to load recommendations:

Method	Where it runs	Best for
`useRecommendations()` hook	Browser (client-side)	Most storefronts — simplest integration
`fetchRecommendationSections()`	Server (Hydrogen route loaders)	SEO-critical pages that need recommendations in the initial HTML

Client-Side: useRecommendations Hook

Use the hook inside any component rendered under <GloodProvider>. The page URL, locale, and Glood client id are filled in automatically from the browser.

For a v3 client the hook waits for the page-load /v3/headless/init call to settle before fetching sections (staying in loading until then), so init runs first and the sections request carries the init-issued visitor id. No extra wiring needed — this ordering is automatic.

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

function ProductRecommendations({ productId }: { productId: string }) {
  const { sections, loading, error } = useRecommendations({
    pageType: 'product_page',
    productId, // numeric Shopify product id, e.g. '8977367564515'
  });

  if (loading || error) return null;

  return (
    <>
      {sections.map((section) => (
        <section key={section.section_serve_id}>
          <h2>{section.title}</h2>
          <div className="product-grid">
            {section.products.map((product) => (
              <a key={product.product_id} href={`/products/${product.handle}`}>
                <img src={product.image?.url} alt={product.title} />
                <span>{product.title}</span>
                <span>{product.price}</span>
              </a>
            ))}
          </div>
        </section>
      ))}
    </>
  );
}

Shopify product ids in Hydrogen are GIDs like gid://shopify/Product/8977367564515. Pass only the numeric part: product.id.split('/').pop().

Page Types

Every request declares which page the visitor is on. Glood returns the sections configured for that page type in the dashboard:

Page Type	Use On
`home`	Homepage
`product_page`	Product detail pages (pass `productId`)
`collection`	Collection pages (pass `collection` id)
`cart`	Cart page (pass `cartProductIds`)
`blog`	Blog and article pages
`order_confirm`	Order confirmation / thank-you page
`checkout`, `ajax_cart`, `returns`, `404`, `other`	Special pages

Hook Result

The hook returns everything needed to render and attribute recommendations:

const {
  sections,        // RecommendationSection[] — sections with products
  data,            // Full SectionsResponse (request_id, experience, ...)
  loading,         // true while fetching
  error,           // Error | null
  refetch,         // Re-run the request with the same params
  trackRender,     // Attribution helpers (see below)
  trackView,
  trackClick,
  trackAddToCart,
} = useRecommendations({ pageType: 'product_page', productId });

Deferring the Request

Pass { skip: true } as the second argument to wait until required params are ready:

const { sections } = useRecommendations(
  { pageType: 'product_page', productId },
  { skip: !productId },
);

Server-Side: fetchRecommendationSections

For SSR, fetch recommendations inside a Hydrogen route loader. Pass pageUrl and locale explicitly — there is no browser context on the server:

import { fetchRecommendationSections } from '@glood/hydrogen';
import { useLoaderData } from 'react-router';

export async function loader({ request, params, context }) {
  const recommendations = await fetchRecommendationSections(
    {
      apiKey: context.env.GLOOD_API_KEY,
      myShopifyDomain: 'your-store.myshopify.com',
    },
    {
      pageType: 'product_page',
      pageUrl: request.url,
      locale: 'en-US',
      productId: params.productId,
    },
  ).catch(() => null); // Never let recommendations break the page

  return { recommendations };
}

export default function ProductPage() {
  const { recommendations } = useLoaderData();

  return (
    <>
      {recommendations?.sections.map((section) => (
        <section key={section.section_serve_id}>
          <h2>{section.title}</h2>
          {/* render section.products */}
        </section>
      ))}
    </>
  );
}

Always wrap the call in a .catch() (or try/catch) inside loaders. A recommendations outage should degrade gracefully, not 500 your page.

Rendering SSR sections with attribution

The loader only fetches the data — you still render and track it in a client component. Because you are not using the useRecommendations hook here, the hook’s trackRender/trackView/trackClick/trackAddToCart helpers aren’t available; instead get the recommendations app from useGloodAnalytics() and call its attribution methods directly. Two SSR-specific details are handled below:

Persist the assigned experience to localStorage yourself. fetchRecommendationSections only persists it in the browser, and the loader runs on the server — so pixel/attribution events won’t carry it unless you save it client-side.
Fire trackRender once the component mounts in the browser (the data is already in the SSR HTML, but attribution events are always sent client-side).

import { useEffect, useRef } from 'react';
import { useGloodAnalytics } from '@glood/hydrogen';

export function GloodRecommendations({ data, pageType, productId }) {
  const client = useGloodAnalytics();
  const app = client?.getApp('recommendations');
  const rendered = useRef(new Set());

  const sections = data?.sections ?? [];

  const buildTrack = (section, products) => ({
    section: String(section.id),
    sectionServeId: section.section_serve_id, // from the API response
    requestId: data?.request_id,
    page: pageType,
    parent: productId ? { productId } : undefined,
    ...(products ? { products } : {}),
  });

  // Persist the SSR-assigned experience so pixel events carry it
  useEffect(() => {
    if (!data?.experience) return;
    try {
      window.localStorage.setItem('gai_s_e', String(data.experience));
    } catch {
      // ignore storage errors
    }
  }, [data]);

  // glood:section:render — once per section
  useEffect(() => {
    if (!app) return;
    sections.forEach((section) => {
      if (rendered.current.has(section.section_serve_id)) return;
      rendered.current.add(section.section_serve_id);
      app.trackRender(buildTrack(section));
    });
  }, [app, sections]);

  return (
    <>
      {sections.map((section) => (
        <section key={section.section_serve_id}>
          <h2>{section.title}</h2>
          <div className="product-grid">
            {section.products.map((product) => {
              const track = buildTrack(section, [
                { productId: String(product.product_id), quantity: 1 },
              ]);
              return (
                <a
                  key={product.product_id}
                  href={`/products/${product.handle}`}
                  onClick={() => app?.trackClick(track)}
                >
                  <img src={product.image?.url} alt={product.title} />
                  <span>{product.title}</span>
                  <span>{product.price}</span>
                </a>
              );
            })}
          </div>
        </section>
      ))}
    </>
  );
}

Render it with the loader data (it’s already in the initial HTML — no client fetch, no layout shift):

export default function ProductPage() {
  const { recommendations } = useLoaderData();
  return (
    <GloodRecommendations
      data={recommendations}
      pageType="product_page"
      productId={/* numeric product id, e.g. product.id.split('/').pop() */}
    />
  );
}

Unlike the client-side hook, an SSR loader does not run /v3/headless/init and cannot read the browser’s _glood_user_id cookie. To attribute SSR requests to a returning visitor, parse the id from the incoming request cookies and pass it explicitly as userId (and clientId) to fetchRecommendationSections.

Attribution Tracking

To attribute recommendation performance (views, clicks, and add-to-carts tied back to revenue in Glood analytics), fire the attribution helpers at the right moments. Each takes a SectionTrack object that links the interaction to the exact section render via sectionServeId:

function ProductRecommendations({ productId }) {
  const { sections, data, trackRender, trackClick, trackAddToCart } =
    useRecommendations({ pageType: 'product_page', productId });

  return sections.map((section) => {
    const baseTrack = {
      section: String(section.id),
      sectionServeId: section.section_serve_id, // from the API response
      requestId: data?.request_id,
      page: 'product_page',
      parent: { productId },
    };

    return (
      <section
        key={section.section_serve_id}
        ref={() => trackRender(baseTrack)}
      >
        <h2>{section.title}</h2>
        {section.products.map((product) => (
          <a
            key={product.product_id}
            href={`/products/${product.handle}`}
            onClick={() =>
              trackClick({
                ...baseTrack,
                products: [{ productId: String(product.product_id) }],
              })
            }
          >
            {product.title}
          </a>
        ))}
      </section>
    );
  });
}

Helper	Event Sent	When to Call
`trackRender(track)`	`glood:section:render`	Section is rendered in the DOM
`trackView(track)`	`glood:section:view`	Section scrolls into the viewport
`trackClick(track)`	`glood:section:click`	Visitor clicks a recommended product
`trackAddToCart(track)`	`glood:section:add_to_cart`	Visitor adds a recommended product to cart

Standard events (page_viewed, product_added_to_cart, etc.) are sent automatically by GloodProvider — you never emit those manually. Attribution helpers are the only events you call yourself, because only your UI knows when a recommendation is clicked.

Experience Persistence

The sections API assigns each visitor an A/B experience. The SDK automatically persists the assigned experience id to localStorage (key gai_s_e) after every fetch, and every pixel event carries it — so all analytics segment correctly by experience without any work on your side.

Error Handling

Failed requests throw (or surface via the hook’s error) a GloodApiError carrying the HTTP status and response body:

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

try {
  await fetchRecommendationSections(options, params);
} catch (error) {
  if (error instanceof GloodApiError) {
    console.error(error.status, error.body); // e.g. 401, { error: 'Invalid authentication' }
  }
}

Common failures:

Status	Cause
`401`	Wrong `apiKey`, or the key doesn’t match `myShopifyDomain`
`400`	Invalid params (bad `pageType`, missing `pageUrl`/`locale`), or shop plan not set up
CSP error in console	`https://storefront.glood.ai` missing from your `connect-src` — see Content Security Policy

Empty sections: [] with a 200 is not an error — it means no sections are enabled for that page type in the Glood dashboard (or targeting rules excluded them).

For Developers

Loading Recommendations

Loading Recommendations

Client-Side: useRecommendations Hook

Page Types

Hook Result

Deferring the Request

Server-Side: fetchRecommendationSections

Rendering SSR sections with attribution

Attribution Tracking

Experience Persistence

Error Handling

See Also

​Loading Recommendations

​Client-Side: useRecommendations Hook

​Page Types

​Hook Result

​Deferring the Request

​Server-Side: fetchRecommendationSections

​Rendering SSR sections with attribution

​Attribution Tracking

​Experience Persistence

​Error Handling

​See Also

Loading Recommendations

Client-Side: useRecommendations Hook

Page Types

Hook Result

Deferring the Request

Server-Side: fetchRecommendationSections

Rendering SSR sections with attribution

Attribution Tracking

Experience Persistence

Error Handling

See Also