> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glood.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Glood Hydrogen SDK

> Complete guide to integrating Glood with Shopify Hydrogen for e-commerce analytics and personalization

# 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

```bash theme={null}
npm install @glood/hydrogen
```

### 2. Basic Setup

Add your Glood API key to environment variables:

```bash theme={null}
# .env
GLOOD_API_KEY=your_glood_api_key_here
```

Configure the SDK in your root layout:

```tsx theme={null}
// 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:

```tsx theme={null}
// 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

### Basic Configuration (Recommended)

```tsx theme={null}
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

```tsx theme={null}
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:

### Default Consent Requirements

* **Recommendations**: `['analytics', 'marketing']` - Analytics and marketing consent
* **Search**: `['analytics']` - Only analytics consent required
* **Wishlist**: `['analytics', 'preferences']` - Analytics and preferences consent

### How Consent Works

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

### Search

* **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:

```javascript theme={null}
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:

```tsx theme={null}
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

* [Installation Guide](/for-developers/glood-hydrogen-sdk/installation) - Detailed setup instructions
* [Configuration](/for-developers/glood-hydrogen-sdk/configuration) - Basic and advanced configuration options
* [API Reference](/for-developers/glood-hydrogen-sdk/api-reference/client) - Complete API documentation
* [Examples](/for-developers/glood-hydrogen-sdk/examples/basic-setup) - Implementation examples and patterns
* [Content Security Policy](/for-developers/glood-hydrogen-sdk/content-security-policy) - CSP configuration guide

## Requirements

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

## Support

* 📖 [API Reference](/for-developers/glood-hydrogen-sdk/api-reference/client)
* 💬 [GitHub Discussions](https://github.com/LoopClub/glood-hydrogen/discussions)
* 🐛 [Issues](https://github.com/LoopClub/glood-hydrogen/issues)