> ## 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.

# Configuration Guide

> Comprehensive guide to configuring the Glood Hydrogen SDK for different use cases and environments

# Configuration Guide

The Glood Hydrogen SDK supports both basic and advanced configuration patterns to fit different use cases and environments.

## Configuration Overview

The SDK follows a **zero-configuration** principle with sensible defaults, while providing **full customization** options for advanced use cases.

### Configuration Hierarchy

1. **Basic Configuration** - Only API key and domain required
2. **Client-Level App Config** - Override recommendations settings in the `apps.recommendations` block of `createGlood(...)`
3. **Environment Variables** - External configuration management

## API Version

`createGlood` accepts an optional numeric `version` that selects the headless API version. It defaults to `3`.

* **`3` (default)** - The full headless suite: session init, sections, events, and all recommendation variants. Authenticates with an `Authorization: Bearer <apiKey>` header plus the shop header.
* **`2` (legacy)** - Recommendations only. Authenticates by shop header alone (no bearer token) and does not support session init or the events suite.

```typescript theme={null}
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
});
```

<Note>
  `createGlood` throws if `version` is anything other than `2` or `3`. Leave it unset (or `3`) unless you specifically need the legacy v2 behavior.
</Note>

## Basic Configuration

### Minimal Setup

The simplest configuration requires only your API key and Shopify domain:

```typescript theme={null}
import { createGlood, recommendations } from '@glood/hydrogen';

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

**What this provides:**

* ✅ Recommendations enabled with default endpoint
* ✅ Pixel tracking enabled
* ✅ Default consent requirements
* ✅ Automatic event subscriptions
* ✅ Production-ready configuration

### Basic with Debug Mode

Enable debug logging for development:

```typescript theme={null}
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  debug: process.env.NODE_ENV === 'development',
})
  .use(recommendations());
```

## Advanced Configuration

### Client-Level App Configuration

Override the recommendations app settings in the main client configuration:

```typescript theme={null}
import { createGlood, CONSENT_TYPES } from '@glood/hydrogen';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  apps: {
    recommendations: {
      endpoint: 'https://custom-storefront.glood.ai',
      pixel: {
        enabled: true,
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
      },
      subscribedEvents: ['product_viewed', 'cart_viewed'], // Limited events
    },
  },
  debug: true,
  settings: {
    customKey: 'customValue',
    trackingVersion: '2.0',
  },
})
  .use(recommendations());
```

<Note>
  The `recommendations()` module factory takes no arguments. Configure the app entirely through the `apps.recommendations` block of `createGlood(...)`, then register it with `.use(recommendations())`.
</Note>

## Where Events Are Sent

Analytics and attribution events are routed by the client's `version` off the app's main endpoint (default `https://storefront.glood.ai`) — there is no separate events host.

* **v3** → `POST {endpoint}/api/storefront/v3/headless/events`, with headers `Authorization: Bearer <apiKey>` and `x-shop`.
* **v2** → `POST {endpoint}/api/storefront/event`, with header `x-shop-myshopify-domain` (legacy payload).

<Note>
  You do not configure an events endpoint. It is derived automatically from the recommendations app's `endpoint` and the client `version`, so custom endpoints continue to route events to the correct versioned path.
</Note>

## Environment-Specific Configuration

### Multi-Environment Setup

Configure different settings for different environments:

```typescript theme={null}
const getGloodConfig = () => {
  const env = process.env.NODE_ENV;
  const isDev = env === 'development';
  const isStaging = env === 'staging';
  const isProd = env === 'production';

  return {
    apiKey: process.env.GLOOD_API_KEY!,
    myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
    version: 3, // 2 | 3 — 3 is the default
    debug: isDev || isStaging,
    apps: {
      recommendations: {
        endpoint: isDev
          ? 'https://dev-storefront.glood.ai'
          : isStaging
          ? 'https://staging-storefront.glood.ai'
          : 'https://storefront.glood.ai',
        pixel: {
          enabled: isProd || isStaging, // No pixels in dev
          consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
        },
      },
    },
  };
};

const glood = createGlood(getGloodConfig())
  .use(recommendations());
```

### Environment Variables

Use environment variables for external configuration:

```bash theme={null}
# .env.development
GLOOD_API_KEY=dev_api_key
GLOOD_DEBUG=true
GLOOD_PIXEL_ENABLED=false
GLOOD_RECOMMENDATIONS_ENDPOINT=https://dev-storefront.glood.ai

# .env.staging
GLOOD_API_KEY=staging_api_key
GLOOD_DEBUG=true
GLOOD_PIXEL_ENABLED=true
GLOOD_RECOMMENDATIONS_ENDPOINT=https://staging-storefront.glood.ai

# .env.production
GLOOD_API_KEY=production_api_key
GLOOD_DEBUG=false
GLOOD_PIXEL_ENABLED=true
GLOOD_RECOMMENDATIONS_ENDPOINT=https://storefront.glood.ai
```

```typescript theme={null}
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
  version: 3, // 2 | 3 — 3 is the default
  debug: process.env.GLOOD_DEBUG === 'true',
  apps: {
    recommendations: {
      endpoint: process.env.GLOOD_RECOMMENDATIONS_ENDPOINT!,
      pixel: {
        enabled: process.env.GLOOD_PIXEL_ENABLED === 'true',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
    },
  },
});
```

## Privacy & Consent Configuration

### Default Consent Requirements

The recommendations app requires both analytics and marketing consent by default, since personalization relies on marketing signals:

```typescript theme={null}
// Default consent for recommendations
const defaultConsent = ['analytics', 'marketing'];
```

### Custom Consent Configuration

Customize consent requirements for compliance:

```typescript theme={null}
import { CONSENT_TYPES } from '@glood/hydrogen';

// GDPR-compliant minimal consent
const minimalConsent = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
      },
    },
  },
});

// Strict privacy requirements
const strictConsent = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        consent: [
          CONSENT_TYPES.ANALYTICS,
          CONSENT_TYPES.MARKETING,
          CONSENT_TYPES.PREFERENCES,
          CONSENT_TYPES.SALE_OF_DATA, // All consents required
        ],
      },
    },
  },
});
```

### Consent Scenarios

Different configurations for different privacy requirements:

```typescript theme={null}
const getConsentConfig = (privacyLevel: 'minimal' | 'standard' | 'full') => {
  const consentMap = {
    minimal: [CONSENT_TYPES.ANALYTICS],
    standard: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.PREFERENCES],
    full: [
      CONSENT_TYPES.ANALYTICS,
      CONSENT_TYPES.MARKETING,
      CONSENT_TYPES.PREFERENCES,
      CONSENT_TYPES.SALE_OF_DATA,
    ],
  };

  return {
    apiKey: process.env.GLOOD_API_KEY!,
    myShopifyDomain: 'your-store.myshopify.com',
    version: 3, // 2 | 3 — 3 is the default
    apps: {
      recommendations: {
        endpoint: 'https://storefront.glood.ai',
        pixel: {
          enabled: true,
          consent: consentMap[privacyLevel],
        },
      },
    },
  };
};

// Usage based on user preference or region
const privacyLevel = getPrivacyLevel(); // 'minimal' | 'standard' | 'full'
const glood = createGlood(getConsentConfig(privacyLevel));
```

## Event Subscription Configuration

### Default Event Subscriptions

By default, the recommendations app subscribes to all relevant events:

```typescript theme={null}
const defaultSubscriptions = {
  recommendations: [
    'page_viewed',
    'product_viewed',
    'collection_viewed',
    'cart_viewed',
    'product_added_to_cart',
    'product_removed_from_cart',
    'search_submitted',
    'custom_promotion_viewed'
  ],
};
```

### Custom Event Subscriptions

Limit events by setting `subscribedEvents` in the `apps.recommendations` block:

```typescript theme={null}
// Product-focused recommendations
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  apps: {
    recommendations: {
      subscribedEvents: ['product_viewed', 'cart_viewed'],
    },
  },
})
  .use(recommendations());

// Minimal event tracking
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  apps: {
    recommendations: {
      subscribedEvents: ['product_viewed'], // Only product views
    },
  },
})
  .use(recommendations());
```

## Performance Configuration

### Development Optimization

Optimize for development experience:

```typescript theme={null}
const developmentConfig = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  version: 3, // 2 | 3 — 3 is the default
  debug: true, // Detailed logging
  apps: {
    recommendations: {
      endpoint: 'https://dev-storefront.glood.ai',
      pixel: {
        enabled: false, // No network requests
        consent: [],
      },
      subscribedEvents: ['product_viewed'], // Minimal events
    },
  },
};

const glood = createGlood(developmentConfig)
  .use(recommendations());
```

### Production Optimization

Optimize for production performance:

```typescript theme={null}
const productionConfig = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
  version: 3, // 2 | 3 — 3 is the default
  debug: false, // No debug logging
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
      // Use default event subscriptions (all events)
    },
  },
};
```

## Testing Configuration

In tests, point the recommendations `endpoint` at a mock server and set `pixel.enabled: false` so no external requests are made:

```typescript theme={null}
const glood = createGlood({
  apiKey: 'test_api_key',
  myShopifyDomain: 'test-store.myshopify.com',
  apps: {
    recommendations: {
      endpoint: 'http://localhost:3001/mock-api',
      pixel: { enabled: false, consent: [] },
    },
  },
})
  .use(recommendations());
```

## Configuration Validation

`createGlood` validates `apiKey`, `myShopifyDomain` and `version` (must be `2` or `3`) and throws on invalid input, so no separate validation step is needed.

## Best Practices

### 1. Environment-Based Configuration

Use different configurations for different environments:

```typescript theme={null}
// ✅ Good - Environment-specific config
const config = getConfigForEnvironment(process.env.NODE_ENV);

// ❌ Avoid - Hardcoded production config everywhere
const config = { /* production settings */ };
```

### 2. Gradual Rollout

Start with minimal configuration and gradually add custom settings:

```typescript theme={null}
// Phase 1: Basic setup
const glood = createGlood({ apiKey, myShopifyDomain })
  .use(recommendations());

// Phase 2: Custom endpoint and events
const glood = createGlood({
  apiKey,
  myShopifyDomain,
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      subscribedEvents: ['product_viewed', 'cart_viewed'],
    },
  },
})
  .use(recommendations());
```

### 3. Privacy-First Configuration

Design configurations with privacy in mind:

```typescript theme={null}
// ✅ Good - Minimal consent by default
const baseConsent = [CONSENT_TYPES.ANALYTICS];

// ✅ Good - Explicit consent requirements
const marketingConsent = [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING];

// ❌ Avoid - Requiring all consents by default
const consent = Object.values(CONSENT_TYPES);
```

### 4. Configuration Documentation

Document your configuration choices:

```typescript theme={null}
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,

  // Headless API version (3 is the default full suite)
  version: 3,

  // Enable debug logging in non-production environments
  debug: process.env.NODE_ENV !== 'production',

  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        // Enable pixel tracking for personalization
        enabled: true,
        // Require both analytics and marketing consent for personalization
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
      // Track key e-commerce events for recommendations
      subscribedEvents: [
        'product_viewed',
        'cart_viewed',
        'product_added_to_cart'
      ],
    },
  },
})
  .use(recommendations());
```

## Configuration Examples

See the Examples section for complete configuration examples:

* [Basic Setup](/for-developers/glood-hydrogen-sdk/examples/basic-setup) - Simple configuration
* [Recommendations](/for-developers/glood-hydrogen-sdk/examples/recommendations) - Fetching and displaying recommendation sections

## See Also

* [Installation Guide](/for-developers/glood-hydrogen-sdk/installation) - Getting started
* [API Reference](/for-developers/glood-hydrogen-sdk/api-reference/client) - Complete API documentation
* [Content Security Policy](/for-developers/glood-hydrogen-sdk/content-security-policy) - CSP configuration
* [Types Reference](/for-developers/glood-hydrogen-sdk/api-reference/types) - TypeScript interfaces