Create the client once and register the recommendations app. The apiKey is a
public storefront token (gl_sf_*), so it is safe to ship to the browser.
// app/lib/glood.tsimport { createGlood, recommendations } from '@glood/hydrogen';export const glood = createGlood({ apiKey: process.env.GLOOD_API_KEY!, myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!, // Headless API version (2 | 3). 3 is the default and the full suite // (init, sections, events, recommendations variants); set explicitly here // for clarity. v2 is legacy and only supports recommendations. version: 3, debug: process.env.NODE_ENV === 'development',}).use(recommendations());
3. Root Layout (app/root.tsx)
Wrap your app with GloodProvider inside Shopify’s Analytics.Provider and
pass the root loader data. GloodProvider subscribes to Shopify’s analytics
events and, on a v3 client, automatically fires POST /v3/headless/init
on mount to bootstrap the session (see below).
GloodProvider must render inside Shopify’s Analytics.Provider so it can
subscribe to the storefront’s analytics events.
What This Setup Provides
✅ Automatic Session Init (v3)
On page load, a v3 client automatically calls
POST /api/storefront/v3/headless/init via GloodProvider. This bootstrap:
replays a persisted visitor id and returns/echoes user_id (stored in the
_glood_user_id cookie so returning visitors are recognized),
creates a per-visit visit_id (_glood_visit_id, a session cookie),
returns the visitor’s browsed / cart / purchased history, shop config
(currency, money format, GraphQL version, integrations, analytics flag) and a
storefront token.
The init response is available anywhere via the useGloodInit() hook. For a
v2 client, init is a no-op (the endpoint is v3-only) and useGloodInit()
returns null.
✅ Automatic Event Tracking
Once wrapped, GloodProvider automatically tracks Shopify analytics events
(page views, product views, collection views, cart views, add/remove from
cart) and forwards them to the recommendations app.
✅ Default Endpoint
Recommendations: https://storefront.glood.ai — the v3 headless suite
(init, sections, events, recommendations) lives under this endpoint.
✅ Debug Logging
In development mode (debug: true), you’ll see console logs like:
[Glood Debug] Registered recommendations app[Glood Debug] Running headless init: https://storefront.glood.ai/api/storefront/v3/headless/init[Glood Debug] Setting up centralized subscription for page_viewed[Glood Debug] Received product_viewed event, distributing to interested apps[Glood Debug] Consent granted for recommendations, processing event
Testing the Setup
1. Verify Installation
Check that the SDK is working by looking for debug logs in the browser console.
2. Verify Session Init
On first load, confirm a POST /api/storefront/v3/headless/init request
succeeds, and that the _glood_user_id and _glood_visit_id cookies are set.
3. Test Event Tracking
Navigate to a product page – should see product_viewed events
Add item to cart – should see product_added_to_cart events