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 app settings in main config
App-Level Config - Individual app module configuration
Environment Variables - External configuration management

Basic Configuration

Minimal Setup

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

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

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

What this provides:

✅ All apps enabled with default endpoints
✅ Pixel tracking enabled for all apps
✅ Default consent requirements per app
✅ 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',
  debug: process.env.NODE_ENV === 'development',
});

Selective App Usage

Enable only specific apps to reduce bundle size:

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

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

Advanced Configuration

Client-Level App Configuration

Override 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',
  apps: {
    recommendations: {
      endpoint: 'https://custom-storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://custom-events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
      },
      subscribedEvents: ['product_viewed', 'cart_viewed'], // Limited events
    },
    search: {
      endpoint: 'https://s-s.glood.ai',
      pixel: {
        enabled: false, // Disable search pixels
        endpoint: 'https://s-pixel.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS],
      },
    },
    wishlist: {
      endpoint: 'https://w-s.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://w-pixel.glood.ai',
        consent: [
          CONSENT_TYPES.ANALYTICS,
          CONSENT_TYPES.PREFERENCES,
          CONSENT_TYPES.MARKETING
        ], // Require all three
      },
    },
  },
  debug: true,
  settings: {
    customKey: 'customValue',
    trackingVersion: '2.0',
  },
})
  .use(recommendations())
  .use(search())
  .use(wishlist());

App-Level Configuration

Configure individual apps with custom settings:

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

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
})
  .use(recommendations({
    endpoint: 'https://custom-recommendations.glood.ai',
    pixel: {
      enabled: true,
      endpoint: 'https://custom-pixel.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
    },
    subscribedEvents: ['product_viewed', 'collection_viewed'],
  }))
  .use(search({
    endpoint: 'https://search-api.glood.ai',
    pixel: {
      enabled: true,
      endpoint: 'https://search-pixel.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS],
    },
  }))
  .use(wishlist()); // Use defaults

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!,
    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
          endpoint: isDev
            ? 'https://dev-events.glood.ai'
            : isStaging
            ? 'https://staging-events.glood.ai'
            : 'https://events.glood.ai',
          consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
        },
      },
      search: {
        endpoint: isDev
          ? 'https://dev-search.glood.ai'
          : isStaging
          ? 'https://staging-search.glood.ai'
          : 'https://s-s.glood.ai',
        pixel: {
          enabled: isProd || isStaging,
          endpoint: isDev
            ? 'https://dev-s-pixel.glood.ai'
            : isStaging
            ? 'https://staging-s-pixel.glood.ai'
            : 'https://s-pixel.glood.ai',
          consent: [CONSENT_TYPES.ANALYTICS],
        },
      },
      wishlist: {
        endpoint: isDev
          ? 'https://dev-wishlist.glood.ai'
          : isStaging
          ? 'https://staging-wishlist.glood.ai'
          : 'https://w-s.glood.ai',
        pixel: {
          enabled: isProd, // Only in production
          endpoint: 'https://w-pixel.glood.ai',
          consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.PREFERENCES],
        },
      },
    },
  };
};

const glood = createGlood(getGloodConfig())
  .use(recommendations())
  .use(search())
  .use(wishlist());

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!,
  debug: process.env.GLOOD_DEBUG === 'true',
  apps: {
    recommendations: {
      endpoint: process.env.GLOOD_RECOMMENDATIONS_ENDPOINT!,
      pixel: {
        enabled: process.env.GLOOD_PIXEL_ENABLED === 'true',
        endpoint: process.env.GLOOD_RECOMMENDATIONS_PIXEL_ENDPOINT!,
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
    },
  },
});

Each app has different default consent requirements:

// Default consent per app
const defaultConsent = {
  recommendations: ['analytics', 'marketing'],  // Personalization needs marketing
  search: ['analytics'],                        // Only needs analytics
  wishlist: ['analytics', 'preferences'],       // Needs user preferences
};

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',
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
      },
    },
    search: {
      endpoint: 'https://s-s.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://s-pixel.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
      },
    },
    wishlist: {
      endpoint: 'https://w-s.glood.ai',
      pixel: {
        enabled: false, // No tracking for wishlist
        endpoint: 'https://w-pixel.glood.ai',
        consent: [],
      },
    },
  },
});

// Strict privacy requirements
const strictConsent = 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: [
          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',
    apps: {
      recommendations: {
        endpoint: 'https://storefront.glood.ai',
        pixel: {
          enabled: true,
          endpoint: 'https://events.glood.ai',
          consent: consentMap[privacyLevel],
        },
      },
      // ... other apps
    },
  };
};

// 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, each 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'
  ],
  search: [
    'page_viewed',
    'search_submitted',
    'product_viewed',
    'collection_viewed'
  ],
  wishlist: [
    'page_viewed',
    'product_viewed',
    'cart_viewed',
    'product_added_to_cart'
  ]
};

Custom Event Subscriptions

Limit events for specific use cases:

// Product-focused recommendations
const glood = createGlood(config)
  .use(recommendations({
    subscribedEvents: ['product_viewed', 'cart_viewed'],
  }))
  .use(search({
    subscribedEvents: ['search_submitted'], // Only search events
  }))
  .use(wishlist({
    subscribedEvents: ['product_viewed'], // Only product views
  }));

// Minimal event tracking
const glood = createGlood(config)
  .use(recommendations({
    subscribedEvents: ['product_viewed'], // Only product views
  }))
  .use(search({
    subscribedEvents: ['search_submitted'], // Only searches
  }));
  // No wishlist tracking

Performance Configuration

Development Optimization

Optimize for development experience:

const developmentConfig = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: true, // Detailed logging
  apps: {
    recommendations: {
      endpoint: 'https://dev-storefront.glood.ai',
      pixel: {
        enabled: false, // No network requests
        endpoint: '',
        consent: [],
      },
      subscribedEvents: ['product_viewed'], // Minimal events
    },
    search: {
      endpoint: 'https://dev-search.glood.ai',
      pixel: {
        enabled: false,
        endpoint: '',
        consent: [],
      },
      subscribedEvents: ['search_submitted'],
    },
    // No wishlist in development
  },
};

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

Production Optimization

Optimize for production performance:

const productionConfig = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
  debug: false, // No debug logging
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
      // Use default event subscriptions (all events)
    },
    search: {
      endpoint: 'https://s-s.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://s-pixel.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS],
      },
    },
    wishlist: {
      endpoint: 'https://w-s.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://w-pixel.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.PREFERENCES],
      },
    },
  },
};

Testing Configuration

Test Environment Setup

Configuration for testing environments:

const testConfig = {
  apiKey: 'test_api_key',
  myShopifyDomain: 'test-store.myshopify.com',
  debug: true,
  apps: {
    recommendations: {
      endpoint: 'https://test-storefront.glood.ai',
      pixel: {
        enabled: false, // No external requests in tests
        endpoint: 'https://test-events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS],
      },
    },
  },
};

// For unit tests
const mockConfig = {
  apiKey: 'mock_api_key',
  myShopifyDomain: 'mock-store.myshopify.com',
  debug: false, // No console output in tests
  apps: {
    recommendations: {
      endpoint: 'http://localhost:3001/mock-api',
      pixel: {
        enabled: false,
        endpoint: '',
        consent: [],
      },
    },
  },
};

Mock Configuration

For testing with mocked services:

// jest.config.js
module.exports = {
  setupFilesAfterEnv: ['<rootDir>/src/test/setup.ts'],
};

// src/test/setup.ts
import { createGlood } from '@glood/hydrogen';

// Mock Glood client for tests
jest.mock('@glood/hydrogen', () => ({
  createGlood: jest.fn().mockReturnValue({
    config: {},
    debug: false,
    apps: new Map(),
    getEnabledApps: jest.fn().mockReturnValue([]),
    getApp: jest.fn().mockReturnValue(undefined),
    use: jest.fn().mockReturnThis(),
  }),
  recommendations: jest.fn(),
  search: jest.fn(),
  wishlist: jest.fn(),
}));

Configuration Validation

Runtime Validation

Add validation for production deployments:

function validateConfig(config: any): void {
  if (!config.apiKey) {
    throw new Error('GLOOD_API_KEY environment variable is required');
  }

  if (!config.myShopifyDomain) {
    throw new Error('PUBLIC_STORE_DOMAIN environment variable is required');
  }

  if (!config.myShopifyDomain.includes('.myshopify.com')) {
    console.warn('Warning: Domain does not appear to be a Shopify domain');
  }

  // Validate app configurations
  if (config.apps) {
    Object.entries(config.apps).forEach(([appName, appConfig]: [string, any]) => {
      if (!appConfig.endpoint) {
        throw new Error(`Missing endpoint for ${appName} app`);
      }

      if (appConfig.pixel?.enabled && !appConfig.pixel.endpoint) {
        throw new Error(`Missing pixel endpoint for ${appName} app`);
      }
    });
  }
}

// Usage
const config = {
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
  // ... other config
};

validateConfig(config);
const glood = createGlood(config);

TypeScript Configuration Validation

Use TypeScript for compile-time validation:

// Strict configuration type
interface StrictGloodConfig {
  apiKey: string;
  myShopifyDomain: string;
  debug: boolean;
  apps: {
    recommendations: Required<RecommendationsAppConfig>;
    search: Required<SearchAppConfig>;
    wishlist: Required<WishlistAppConfig>;
  };
}

function createStrictGlood(config: StrictGloodConfig) {
  return createGlood(config);
}

// Usage - TypeScript will enforce all required fields
const strictGlood = createStrictGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.PUBLIC_STORE_DOMAIN!,
  debug: false,
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
      subscribedEvents: ['product_viewed', 'cart_viewed'],
    },
    // ... must define search and wishlist too
  },
});

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

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

// Phase 2: Add search
const glood = createGlood({ apiKey, myShopifyDomain })
  .use(recommendations())
  .use(search());

// Phase 3: Full setup with custom config
const glood = createGlood({
  apiKey,
  myShopifyDomain,
  apps: { /* custom settings */ }
})
  .use(recommendations())
  .use(search())
  .use(wishlist());

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!,

  // 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,
        endpoint: 'https://events.glood.ai',
        // 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())
  .use(search())
  .use(wishlist());

Configuration Examples

See the Examples section for complete configuration examples:

Basic Setup - Simple configuration
Advanced Configuration - Custom endpoints and settings
Privacy Configuration - GDPR/CCPA compliance
Environment Configuration - Multi-environment setup

For Developers

Configuration Guide

Configuration Guide

Configuration Overview

Configuration Hierarchy

Basic Configuration

Minimal Setup

Basic with Debug Mode

Selective App Usage

Advanced Configuration

Client-Level App Configuration

App-Level Configuration

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

Test Environment Setup

Mock Configuration

Configuration Validation

Runtime Validation

TypeScript Configuration Validation

Best Practices

1. Environment-Based Configuration

2. Gradual Rollout

3. Privacy-First Configuration

4. Configuration Documentation

Configuration Examples

See Also

For Developers

​Configuration Guide

​Configuration Overview

​Configuration Hierarchy

​Basic Configuration

​Minimal Setup

​Basic with Debug Mode

​Selective App Usage

​Advanced Configuration

​Client-Level App Configuration

​App-Level Configuration

​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

​Test Environment Setup

​Mock Configuration

​Configuration Validation

​Runtime Validation

​TypeScript 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

Basic Configuration

Minimal Setup

Basic with Debug Mode

Selective App Usage

Advanced Configuration

Client-Level App Configuration

App-Level Configuration

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

Test Environment Setup

Mock Configuration

Configuration Validation

Runtime Validation

TypeScript Configuration Validation

Best Practices

1. Environment-Based Configuration

2. Gradual Rollout

3. Privacy-First Configuration

4. Configuration Documentation

Configuration Examples

See Also