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

Basic Configuration - Only API key and domain required
Client-Level App Config - Override recommendations settings in the apps.recommendations block of createGlood(...)
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.

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

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

Basic Configuration

Minimal Setup

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

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:

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:

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());

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

Search App Configuration

The search app is a v1 headless API on its own host (https://search.glood.ai), independent of the client’s global version. Register it with .use(search()) and configure it through the apps.search block:

import { createGlood, search, CONSENT_TYPES } from '@glood/hydrogen';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  apps: {
    search: {
      endpoint: 'https://search.glood.ai',        // search API host (default)
      controlEndpoint: 'https://search.glood.ai',  // non-edge host for image search + events (default)
      pixel: {
        enabled: true,
        endpoint: 'https://search.glood.ai/api/storefront/event', // search pixel (default)
        consent: [CONSENT_TYPES.ANALYTICS], // search default: analytics only
      },
    },
  },
})
  .use(search());

Defaults for the search app:

Setting	Default
`apiVersion`	`1` (pinned — always v1, even on a v2/v3 client)
`endpoint`	`https://search.glood.ai`
`controlEndpoint`	`https://search.glood.ai` (falls back to the non-edge host)
`pixel.endpoint`	`https://search.glood.ai/api/storefront/event`
`pixel.consent`	`['analytics']`
Subscribed events	all standard Shopify events

Search’s default consent is analytics only (unlike recommendations, which also requires marketing). Search’s apiVersion is fixed at 1 and is not affected by the client’s version — so you can run recommendations (v3) and search (v1) on the same client.

Edge vs. non-edge routing (`controlEndpoint`)

The search app talks to two hosts. endpoint is the main host — used for init, config, instantSearch, filters, filter aggregations, and search. controlEndpoint is the non-edge (control-plane) host — used only for image search and event ingestion, which cannot be served by a regional edge (image search needs the vision/embedding pipeline; events are ingested centrally). controlEndpoint defaults to the non-edge host, so if you point endpoint at a regional edge, image search and events automatically stay on the control plane — you only override one field:

const glood = createGlood({ apiKey, myShopifyDomain })
  .use(search());

// Serve the fast path from an edge, keep image search + events on the control plane:
createGlood({
  apiKey,
  myShopifyDomain,
  apps: {
    search: {
      endpoint: 'https://edge-eu.glood.ai',      // init/config/instant/filters/search → edge
      // controlEndpoint omitted → image search + events stay on the default non-edge host
    },
  },
}).use(search());

Call	Routed to
`init`, `config`, `instantSearch`, `filters`, filter aggregations, `search`	`endpoint`
`imageSearch`	`controlEndpoint`
events (standard + `glood:*` attribution)	`controlEndpoint`

Set controlEndpoint explicitly only when your control plane isn’t the default host (e.g. a local or self-hosted deployment). In production, leave it unset and it resolves to the non-edge host.

Narrowing search events

The search() factory optionally narrows which Shopify standard events are forwarded to the search backend (default: all events):

const glood = createGlood({ apiKey, myShopifyDomain })
  .use(search({ events: ['search_submitted', 'product_added_to_cart'] }));

Where Events Are Sent

Analytics and attribution events are routed by the app’s API version off the app’s events endpoint — there is no separate events host.

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

You do not configure an events endpoint directly. For recommendations it is derived from the app’s endpoint; for search it is derived from controlEndpoint (the non-edge host), so events keep flowing to the control plane even when endpoint points at a regional edge.

Environment-Specific Configuration

Multi-Environment Setup

Configure different settings for different environments:

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:

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

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],
      },
    },
  },
});

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

// Default consent for recommendations
const defaultConsent = ['analytics', 'marketing'];

Customize consent requirements for compliance:

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
        ],
      },
    },
  },
});

Different configurations for different privacy requirements:

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:

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:

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

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:

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:

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:

// ✅ 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:

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

// ✅ 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:

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 - Simple configuration
Recommendations - Fetching and displaying recommendation sections

For Developers

Configuration Guide

Configuration Guide

Configuration Overview

Configuration Hierarchy

API Version

Basic Configuration

Minimal Setup

Basic with Debug Mode

Advanced Configuration

Client-Level App Configuration

Search App Configuration

Edge vs. non-edge routing (`controlEndpoint`)

Narrowing search events

Where Events Are Sent

Environment-Specific Configuration

Multi-Environment Setup

Environment Variables

Event Subscription Configuration

Default Event Subscriptions

Custom Event Subscriptions

Performance Configuration

Development Optimization

Production Optimization

Testing Configuration

Configuration Validation

Best Practices

1. Environment-Based Configuration

2. Gradual Rollout

3. Privacy-First Configuration

4. Configuration Documentation

Configuration Examples

See Also

​Configuration Guide

​Configuration Overview

​Configuration Hierarchy

​API Version

​Basic Configuration

​Minimal Setup

​Basic with Debug Mode

​Advanced Configuration

​Client-Level App Configuration

​Search App Configuration

​Edge vs. non-edge routing (controlEndpoint)

​Narrowing search events

​Where Events Are Sent

​Environment-Specific Configuration

​Multi-Environment Setup

​Environment Variables

​Privacy & Consent Configuration

​Default Consent Requirements

​Custom Consent Configuration

​Consent Scenarios

​Event Subscription Configuration

​Default Event Subscriptions

​Custom Event Subscriptions

​Performance Configuration

​Development Optimization

​Production Optimization

​Testing Configuration

​Configuration Validation

​Best Practices

​1. Environment-Based Configuration

​2. Gradual Rollout

​3. Privacy-First Configuration

​4. Configuration Documentation

​Configuration Examples

​See Also

Configuration Guide

Configuration Overview

Configuration Hierarchy

API Version

Basic Configuration

Minimal Setup

Basic with Debug Mode

Advanced Configuration

Client-Level App Configuration

Search App Configuration

Edge vs. non-edge routing (`controlEndpoint`)

Narrowing search events

Where Events Are Sent

Environment-Specific Configuration

Multi-Environment Setup

Environment Variables

Privacy & Consent Configuration

Default Consent Requirements

Custom Consent Configuration

Consent Scenarios

Event Subscription Configuration

Default Event Subscriptions

Custom Event Subscriptions

Performance Configuration

Development Optimization

Production Optimization

Testing Configuration

Configuration Validation

Best Practices

1. Environment-Based Configuration

2. Gradual Rollout

3. Privacy-First Configuration

4. Configuration Documentation

Configuration Examples

See Also