Skip to main content

​
Glood Hydrogen SDK

The Glood Hydrogen SDK is a TypeScript-first library designed specifically for seamless integration between Glood’s e-commerce platform and Shopify Hydrogen storefronts. It provides React components, hooks, and utilities optimized for the Hydrogen framework.

​
Key Features

🚀 Hydrogen-Optimized - Built specifically for Shopify Hydrogen with SSR support 🎯 TypeScript First - Complete type safety with excellent developer experience ⚡ Performance Focused - Tree-shakeable exports and optimized pixel tracking 🔧 Zero Configuration - Works out of the box with sensible defaults 🛡️ Privacy Compliant - GDPR/CCPA compliant with automatic consent handling 📦 Lightweight - Minimal bundle impact with selective imports

​
Quick Start

​
1. Installation

npm install @glood/hydrogen

​
2. Basic Setup

Add your Glood API key to environment variables: 
# .env
GLOOD_API_KEY=your_glood_api_key_here
Configure the SDK in your root layout: 
// app/root.tsx
import { Analytics } from '@shopify/hydrogen';
import { GloodProvider, createGlood } from '@glood/hydrogen';
import { recommendations, search, wishlist } from '@glood/hydrogen';
import { useLoaderData } from 'react-router';

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

export default function App() {
  const loaderData = useLoaderData();

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

​
3. That’s It! 🎉

No additional setup required. The SDK automatically:
  • ✅ Tracks user interactions via Shopify Analytics
  • ✅ Sends pixel events to Glood endpoints
  • ✅ Respects customer privacy settings
  • ✅ Provides debug logging in development

​
Why loaderData is Required

The loaderData prop is mandatory and enables Glood apps to:
  • Access route-specific data from Hydrogen loaders for enhanced context
  • Enhance analytics events with additional page-specific information
  • Provide personalized recommendations based on current page data
  • Optimize search results using page context and user behavior
Always pass the result of useLoaderData() to the GloodProvider component.

​
Architecture Overview

​
React Context Integration

The SDK uses React Context to provide the Glood client throughout your application: 
// GloodProvider creates a context with the client
function App() {
  const loaderData = useLoaderData();
  return (
    <GloodProvider client={glood} loaderData={loaderData}>
      <YourApp />
    </GloodProvider>
  );
}

// Access the client anywhere in your component tree
function MyComponent() {
  const client = useGloodAnalytics();
  // Use client for custom integrations
}

​
Event Flow

  1. Shopify Analytics → Automatically tracks user interactions
  2. GloodProvider → Subscribes to analytics events via useAnalytics()
  3. Event Transformation → Converts Shopify events to Glood pixel format
  4. Consent Checking → Verifies customer privacy permissions
  5. Pixel Transmission → Sends events to configured Glood endpoints

​
App Module System

The SDK follows a modular architecture with three core apps:
  • Recommendations (recommendations()) - Product recommendations and personalization
  • Search (search()) - Search functionality and analytics
  • Wishlist (wishlist()) - Wishlist management and tracking
Each app can be configured independently with custom endpoints and pixel settings.

​
Configuration Options

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: process.env.NODE_ENV === 'development', // Optional debug mode
});
Benefits:
  • Zero configuration beyond API key and domain
  • Automatic default endpoints for all apps
  • Pixel tracking enabled by default with appropriate consent requirements
  • Perfect for getting started quickly

​
Advanced Configuration

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://events.glood.ai',
        consent: ['analytics', 'marketing'],
      },
    },
    search: {
      endpoint: 'https://s-s.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://s-pixel.glood.ai',
        consent: ['analytics'],
      },
    },
    wishlist: {
      endpoint: 'https://w-s.glood.ai',
      pixel: {
        enabled: false, // Disable pixel tracking for wishlist
        endpoint: 'https://w-pixel.glood.ai',
        consent: ['analytics', 'preferences'],
      },
    },
  },
  debug: true,
});
Benefits:
  • Custom endpoint URLs for different environments
  • Granular pixel tracking control per app
  • Custom consent requirements for privacy compliance
  • Environment-specific configurations

​
Privacy & Compliance

The SDK provides automatic privacy compliance through Shopify’s Customer Privacy API:
  • Recommendations: ['analytics', 'marketing'] - Analytics and marketing consent
  • Search: ['analytics'] - Only analytics consent required
  • Wishlist: ['analytics', 'preferences'] - Analytics and preferences consent
  1. User visits site and sees Shopify privacy banner
  2. User grants specific consent types through the privacy interface
  3. Events are tracked by Shopify Analytics as usual
  4. For each event, Glood checks if user has granted all required consents for that app
  5. Only if all consents are granted, pixel data is sent to Glood
This ensures full GDPR/CCPA compliance without any manual implementation.

​
Default Endpoints

When using basic configuration, these endpoints are used automatically:

​
Recommendations

  • Main: https://storefront.glood.ai - Product recommendations API
  • Pixel: https://events.glood.ai - Analytics events tracking
  • Main: https://s-s.glood.ai - Search functionality API
  • Pixel: https://s-pixel.glood.ai - Search analytics tracking

​
Wishlist

  • Main: https://w-s.glood.ai - Wishlist management API
  • Pixel: https://w-pixel.glood.ai - Wishlist analytics tracking

​
Content Security Policy Setup

To enable pixel tracking, add Glood domains to your Content Security Policy: 
const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  shop: {
    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
  },
  connectSrc: [
    'https://cdn.shopify.com',
    'https://*.shopifycloud.com',
    'https://events.glood.ai',
    'https://s-pixel.glood.ai',
    'https://w-pixel.glood.ai'
  ],
});
This whitelists Glood’s pixel endpoints so events can be transmitted successfully.

​
Debug Mode

Enable debug mode to see detailed logging during development: 
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: process.env.NODE_ENV === 'development',
});
Debug logs show:
  • Event subscriptions setup
  • Received analytics events
  • Consent checking results
  • Pixel transmission status
  • Error details

​
Next Steps

​
Requirements

  • Node.js 18+
  • React 18+
  • Shopify Hydrogen 2024.10.1+
  • TypeScript 5.4+ (recommended)

​
Support