Skip to main content

​
Client API

The client API provides the core functionality for creating and configuring your Glood SDK instance.

​
createGlood()

Creates a new Glood client instance with the specified configuration.

​
Signature

function createGlood(config: GloodConfig): GloodClient

​
Parameters

ParameterTypeRequiredDescription
configGloodConfigYesConfiguration object for the Glood client

​
Basic Usage

import { createGlood } from '@glood/hydrogen';

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

​
Advanced Usage

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://storefront.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://events.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.MARKETING],
      },
    },
    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: false,
        endpoint: 'https://w-pixel.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS, CONSENT_TYPES.PREFERENCES],
      },
    },
  },
  debug: process.env.NODE_ENV === 'development',
  settings: {
    customKey: 'customValue',
  },
});

​
Error Handling

The function throws errors for invalid configurations: 
// Throws: "Glood: apiKey is required and must be a non-empty string"
createGlood({ myShopifyDomain: 'store.myshopify.com' });

// Throws: "Glood: myShopifyDomain is required and must be a valid Shopify domain"
createGlood({ apiKey: 'key' });

// Warns: Domain format doesn't match typical Shopify format
createGlood({
  apiKey: 'key',
  myShopifyDomain: 'custom-domain.com'
});

​
GloodConfig Interface

Configuration object for creating a Glood client.

​
Properties

PropertyTypeRequiredDefaultDescription
apiKeystringYes-Your Glood API key for authentication
myShopifyDomainstringYes-Your Shopify domain (e.g., ‘store-name.myshopify.com’)
appsobjectNoAuto-generatedApp-specific configurations
debugbooleanNofalseEnable debug logging
settingsRecord<string, any>No{}Additional custom settings

​
App Configuration

The apps property allows per-app customization: 
interface GloodConfig {
  apps?: {
    recommendations?: RecommendationsAppConfig;
    search?: SearchAppConfig;
    wishlist?: WishlistAppConfig;
  };
}
Each app config has the same structure: 
interface AppConfig {
  endpoint: string;              // Main API endpoint
  pixel: {
    enabled: boolean;            // Enable/disable pixel tracking
    endpoint: string;            // Pixel tracking endpoint
    consent: ConsentType[];      // Required consent types
  };
  subscribedEvents?: EventType[]; // Events to subscribe to (optional)
}

​
Default App Configurations

When apps is not provided, these defaults are used: 
{
  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: true,
      endpoint: 'https://w-pixel.glood.ai',
      consent: ['analytics', 'preferences'],
    },
  },
}

​
GloodClient Interface

The client instance returned by createGlood().

​
Properties

PropertyTypeDescription
configGloodConfigThe configuration used to create this client
debugbooleanWhether debug mode is enabled
appsMap<AppName, GloodApp>Map of registered app instances

​
Methods

​
use()

Registers an app module with the client. 
use(appModuleOrFactory: GloodAppModule | ((config?: any) => GloodAppModule)): GloodClient
Parameters:
  • appModuleOrFactory: App module function or factory
Returns: The client instance (for method chaining) Usage: 
import { recommendations, search, wishlist } from '@glood/hydrogen';

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

​
getEnabledApps()

Returns all registered app instances. 
getEnabledApps(): GloodApp[]
Returns: Array of enabled app instances Usage: 
const apps = glood.getEnabledApps();
console.log('Enabled apps:', apps.map(app => app.name));

​
getApp()

Gets a specific app by name. 
getApp(name: AppName): GloodApp | undefined
Parameters:
  • name: App name (‘recommendations’, ‘search’, or ‘wishlist’)
Returns: App instance or undefined if not found Usage: 
const recommendationsApp = glood.getApp('recommendations');
if (recommendationsApp) {
  console.log('Recommendations endpoint:', recommendationsApp.endpoint);
}

​
Configuration Examples

​
Basic Setup

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

​
Environment-Specific Setup

Different configurations for different environments: 
const isDevelopment = process.env.NODE_ENV === 'development';
const isStaging = process.env.NODE_ENV === 'staging';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.SHOPIFY_DOMAIN!,
  apps: {
    recommendations: {
      endpoint: isDevelopment
        ? 'https://dev-storefront.glood.ai'
        : isStaging
        ? 'https://staging-storefront.glood.ai'
        : 'https://storefront.glood.ai',
      pixel: {
        enabled: !isDevelopment, // Disable pixels in development
        endpoint: 'https://events.glood.ai',
        consent: ['analytics', 'marketing'],
      },
    },
  },
  debug: isDevelopment,
})
  .use(recommendations())
  .use(search())
  .use(wishlist());

​
Selective App Usage

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

​
Custom Pixel Settings

Granular control over pixel tracking: 
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'], // Only analytics, no 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 wishlist pixel tracking
        endpoint: 'https://w-pixel.glood.ai',
        consent: ['analytics', 'preferences'],
      },
    },
  },
})
  .use(recommendations())
  .use(search())
  .use(wishlist());

​
Error Handling

The client provides comprehensive error handling:

​
Validation Errors

try {
  const glood = createGlood({
    apiKey: '', // Invalid: empty string
    myShopifyDomain: 'invalid-domain',
  });
} catch (error) {
  console.error('Configuration error:', error.message);
  // "Glood: apiKey must be a non-empty string"
}

​
Runtime Errors

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  debug: true, // Enable debug logging
});

// Errors will be logged with full details in debug mode

​
Domain Validation

// Valid Shopify domains
createGlood({
  apiKey: 'key',
  myShopifyDomain: 'store.myshopify.com', // ✅ Valid
});

createGlood({
  apiKey: 'key',
  myShopifyDomain: 'store.shopify.com', // ✅ Valid (Shopify Plus)
});

// Warning for non-standard domains
createGlood({
  apiKey: 'key',
  myShopifyDomain: 'custom-domain.com', // ⚠️ Warning logged
});

​
Best Practices

​
1. Environment Variables

Always use environment variables for sensitive data: 
// ✅ Good
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.SHOPIFY_DOMAIN!,
});

// ❌ Bad - hardcoded credentials
const glood = createGlood({
  apiKey: 'hardcoded_key',
  myShopifyDomain: 'hardcoded_domain.myshopify.com',
});

​
2. Debug Mode

Enable debug mode in development: 
const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: process.env.SHOPIFY_DOMAIN!,
  debug: process.env.NODE_ENV === 'development',
});

​
3. Error Handling

Wrap client creation in try-catch for production: 
try {
  const glood = createGlood({
    apiKey: process.env.GLOOD_API_KEY!,
    myShopifyDomain: process.env.SHOPIFY_DOMAIN!,
  });
} catch (error) {
  console.error('Failed to initialize Glood client:', error);
  // Handle gracefully or use fallback
}

​
4. Method Chaining

Use method chaining for cleaner code: 
const glood = createGlood(config)
  .use(recommendations())
  .use(search())
  .use(wishlist());

​
See Also