App Modules

App modules provide modular functionality for different Glood features. Each module can be configured independently and registered with the Glood client.

Overview

The SDK includes three core app modules:

recommendations() - Product recommendations and personalization
search() - Search functionality and analytics
wishlist() - Wishlist management and tracking

Each module follows the same architecture:

Main Endpoint - API endpoint for app features and functionality
Pixel Endpoint - Separate endpoint for analytics tracking
Event Subscriptions - Shopify Analytics events the app listens to
Consent Requirements - Privacy consent types required for pixel tracking

recommendations()

Enables product recommendations and personalization features.

Signature

function recommendations(config?: RecommendationsAppConfig): GloodAppModule

Parameters

Parameter	Type	Required	Description
`config`	`RecommendationsAppConfig`	No	Custom configuration for the recommendations app

Default Configuration

{
  endpoint: 'https://storefront.glood.ai',
  pixel: {
    enabled: true,
    endpoint: 'https://events.glood.ai',
    consent: ['analytics', 'marketing'],
  },
  subscribedEvents: [
    'page_viewed',
    'product_viewed',
    'collection_viewed',
    'cart_viewed',
    'product_added_to_cart',
    'product_removed_from_cart',
    'search_submitted',
    'custom_promotion_viewed'
  ]
}

Basic Usage

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

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

Custom Configuration

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

const glood = createGlood(config)
  .use(recommendations({
    endpoint: 'https://custom-recommendations.glood.ai',
    pixel: {
      enabled: true,
      endpoint: 'https://custom-events.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS], // Only analytics consent
    },
    subscribedEvents: ['product_viewed', 'cart_viewed'], // Limited events
  }));

Tracked Events

The recommendations app tracks these events by default:

Event	Description	Pixel Data Sent
`page_viewed`	Any page navigation	Page URL, title, referrer
`product_viewed`	Product page views	Product details, variant info, pricing
`collection_viewed`	Collection page views	Collection details, product count
`cart_viewed`	Shopping cart views	Cart contents, total value, line items
`product_added_to_cart`	Items added to cart	Product details, quantity, price
`product_removed_from_cart`	Items removed from cart	Product details, previous quantity
`search_submitted`	Search queries	Search term, results count, product matches
`custom_promotion_viewed`	Promotional content	Promotion details, context

API Features

The recommendations endpoint provides:

Product Recommendations - Personalized product suggestions
Related Products - Products related to current viewing context
Cross-sell/Upsell - Strategic product recommendations
Trending Products - Popular and trending items
Customer Segments - Behavioral customer grouping

search()

Enables search functionality and search analytics.

Signature

function search(config?: SearchAppConfig): GloodAppModule

Parameters

Parameter	Type	Required	Description
`config`	`SearchAppConfig`	No	Custom configuration for the search app

Default Configuration

{
  endpoint: 'https://s-s.glood.ai',
  pixel: {
    enabled: true,
    endpoint: 'https://s-pixel.glood.ai',
    consent: ['analytics'],
  },
  subscribedEvents: [
    'page_viewed',
    'search_submitted',
    'product_viewed',
    'collection_viewed'
  ]
}

Basic Usage

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

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

Custom Configuration

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

const glood = createGlood(config)
  .use(search({
    endpoint: 'https://staging-search.glood.ai',
    pixel: {
      enabled: false, // Disable pixel tracking
      endpoint: 'https://s-pixel.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS],
    },
    subscribedEvents: ['search_submitted'], // Only search events
  }));

Tracked Events

The search app focuses on search-related events:

Event	Description	Pixel Data Sent
`search_submitted`	Search queries executed	Query text, results count, matched products
`product_viewed`	Products viewed from search	Product details, search context
`collection_viewed`	Collections viewed from search	Collection details, search origin
`page_viewed`	General page navigation	Page context for search analytics

API Features

The search endpoint provides:

Search Results - Intelligent product search
Autocomplete - Search suggestions and completions
Filters & Facets - Advanced search filtering
Search Analytics - Query performance and insights
Spell Correction - Automatic query correction

wishlist()

Enables wishlist management and wishlist analytics.

Signature

function wishlist(config?: WishlistAppConfig): GloodAppModule

Parameters

Parameter	Type	Required	Description
`config`	`WishlistAppConfig`	No	Custom configuration for the wishlist app

Default Configuration

{
  endpoint: 'https://w-s.glood.ai',
  pixel: {
    enabled: true,
    endpoint: 'https://w-pixel.glood.ai',
    consent: ['analytics', 'preferences'],
  },
  subscribedEvents: [
    'page_viewed',
    'product_viewed',
    'cart_viewed',
    'product_added_to_cart'
  ]
}

Basic Usage

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

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

Custom Configuration

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

const glood = createGlood(config)
  .use(wishlist({
    endpoint: 'https://custom-wishlist.glood.ai',
    pixel: {
      enabled: true,
      endpoint: 'https://w-pixel.glood.ai',
      consent: [
        CONSENT_TYPES.ANALYTICS,
        CONSENT_TYPES.PREFERENCES,
        CONSENT_TYPES.MARKETING
      ], // Require marketing consent
    },
  }));

Tracked Events

The wishlist app tracks customer preference events:

Event	Description	Pixel Data Sent
`product_viewed`	Product page views	Product details, viewing behavior
`cart_viewed`	Shopping cart interaction	Cart contents, wishlist comparison
`product_added_to_cart`	Cart additions	Product details, conversion context
`page_viewed`	General navigation	Page context for wishlist analytics

API Features

The wishlist endpoint provides:

Wishlist Management - Create, update, delete wishlists
Product Tracking - Track wished vs purchased products
Recommendations - Wishlist-based recommendations
Sharing - Wishlist sharing functionality
Analytics - Wishlist performance insights

App Configuration Interface

All apps share the same configuration structure:

interface AppConfig {
  /** Main API endpoint for app features */
  endpoint: string;

  /** Pixel tracking configuration */
  pixel: {
    /** Enable/disable pixel tracking */
    enabled: boolean;
    /** Pixel tracking endpoint */
    endpoint: string;
    /** Required consent types */
    consent: ConsentType[];
  };

  /** Events this app should subscribe to (optional) */
  subscribedEvents?: EventType[];
}

Available consent types for pixel tracking:

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

CONSENT_TYPES.ANALYTICS        // 'analytics' - Basic analytics
CONSENT_TYPES.MARKETING        // 'marketing' - Marketing and ads
CONSENT_TYPES.PREFERENCES      // 'preferences' - Personalization
CONSENT_TYPES.SALE_OF_DATA     // 'sale_of_data' - Data selling

Event Types

Available event types for subscriptions:

type EventType =
  | 'page_viewed'
  | 'product_viewed'
  | 'collection_viewed'
  | 'cart_viewed'
  | 'search_submitted'
  | 'product_added_to_cart'
  | 'product_removed_from_cart'
  | 'custom_promotion_viewed';

Usage Patterns

All Apps (Recommended)

Enable all apps for complete functionality:

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

Selective Apps

Enable only specific apps to reduce bundle size:

// Only recommendations and search
const glood = createGlood(config)
  .use(recommendations())
  .use(search());

// Only recommendations
const glood = createGlood(config)
  .use(recommendations());

Environment-Specific Configuration

Different configurations for different environments:

const isDevelopment = process.env.NODE_ENV === 'development';

const glood = createGlood(config)
  .use(recommendations({
    endpoint: isDevelopment
      ? 'https://dev-storefront.glood.ai'
      : 'https://storefront.glood.ai',
    pixel: {
      enabled: !isDevelopment, // Disable pixels in development
      endpoint: 'https://events.glood.ai',
      consent: ['analytics', 'marketing'],
    },
  }))
  .use(search())
  .use(wishlist());

Custom Event Subscriptions

Limit events for specific use cases:

// Recommendations only for product pages
const glood = createGlood(config)
  .use(recommendations({
    subscribedEvents: ['product_viewed', 'cart_viewed'],
  }))
  .use(search({
    subscribedEvents: ['search_submitted'],
  }));

Privacy-Focused Configuration

Minimal consent requirements:

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

const glood = createGlood(config)
  .use(recommendations({
    pixel: {
      enabled: true,
      endpoint: 'https://events.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
    },
  }))
  .use(search({
    pixel: {
      enabled: true,
      endpoint: 'https://s-pixel.glood.ai',
      consent: [CONSENT_TYPES.ANALYTICS], // Only analytics
    },
  }))
  .use(wishlist({
    pixel: {
      enabled: false, // No pixel tracking
      endpoint: 'https://w-pixel.glood.ai',
      consent: [],
    },
  }));

Client Override Configuration

App configurations can be overridden at the client level:

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  apps: {
    recommendations: {
      endpoint: 'https://custom-storefront.glood.ai',
      pixel: {
        enabled: false,
        endpoint: 'https://events.glood.ai',
        consent: ['analytics'],
      },
    },
  },
})
  .use(recommendations()) // Will use overridden configuration
  .use(search())          // Will use default configuration
  .use(wishlist());       // Will use default configuration

Accessing Apps at Runtime

Get app instances from the client:

// Get specific app
const recommendationsApp = glood.getApp('recommendations');
if (recommendationsApp) {
  console.log('Recommendations endpoint:', recommendationsApp.endpoint);
  console.log('Pixel enabled:', recommendationsApp.pixel.enabled);
}

// Get all enabled apps
const enabledApps = glood.getEnabledApps();
console.log('Enabled apps:', enabledApps.map(app => app.name));

// Check app configuration
enabledApps.forEach(app => {
  console.log(`${app.name}:`, {
    endpoint: app.endpoint,
    pixelEnabled: app.pixel.enabled,
    events: app.subscribedEvents,
  });
});

Error Handling

Apps provide error handling for various scenarios:

// Invalid app configuration
try {
  const glood = createGlood(config)
    .use(recommendations({
      endpoint: '', // Invalid: empty endpoint
    }));
} catch (error) {
  console.error('App configuration error:', error);
}

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

Best Practices

1. Use All Apps

Enable all apps unless you have specific requirements:

// ✅ Recommended - Complete functionality
const glood = createGlood(config)
  .use(recommendations())
  .use(search())
  .use(wishlist());

2. Environment Configuration

Configure apps based on environment:

const getAppConfig = (appName: string) => ({
  endpoint: process.env[`GLOOD_${appName.toUpperCase()}_ENDPOINT`],
  pixel: {
    enabled: process.env.NODE_ENV === 'production',
    endpoint: process.env[`GLOOD_${appName.toUpperCase()}_PIXEL_ENDPOINT`],
    consent: ['analytics'],
  },
});

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

3. Privacy Compliance

Set appropriate consent requirements:

// E-commerce store with marketing
const glood = createGlood(config)
  .use(recommendations({
    pixel: { consent: ['analytics', 'marketing'] }
  }))
  .use(search({
    pixel: { consent: ['analytics'] }
  }))
  .use(wishlist({
    pixel: { consent: ['analytics', 'preferences'] }
  }));

4. Performance Optimization

Disable unnecessary features in development:

const isDev = process.env.NODE_ENV === 'development';

const glood = createGlood(config)
  .use(recommendations({
    pixel: { enabled: !isDev }
  }))
  .use(search({
    pixel: { enabled: !isDev }
  }))
  .use(wishlist({
    pixel: { enabled: !isDev }
  }));

For Developers

​App Modules

​Overview

​recommendations()

​Signature

​Parameters

​Default Configuration

​Basic Usage

​Custom Configuration

​Tracked Events

​API Features

​search()

​Signature

​Parameters

​Default Configuration

​Basic Usage

​Custom Configuration

​Tracked Events

​API Features

​wishlist()

​Signature

​Parameters

​Default Configuration

​Basic Usage

​Custom Configuration

​Tracked Events

​API Features

​App Configuration Interface

​Consent Types

​Event Types

​Usage Patterns

​All Apps (Recommended)

​Selective Apps

​Environment-Specific Configuration

​Custom Event Subscriptions

​Privacy-Focused Configuration

​Client Override Configuration

​Accessing Apps at Runtime

​Error Handling

​Best Practices

​1. Use All Apps

​2. Environment Configuration

​3. Privacy Compliance

​4. Performance Optimization

​See Also

App Modules

Overview

recommendations()

Signature

Parameters

Default Configuration

Basic Usage

Custom Configuration

Tracked Events

API Features

search()

Signature

Parameters

Default Configuration

Basic Usage

Custom Configuration

Tracked Events

API Features

wishlist()

Signature

Parameters

Default Configuration

Basic Usage

Custom Configuration

Tracked Events

API Features

App Configuration Interface

Consent Types

Event Types

Usage Patterns

All Apps (Recommended)

Selective Apps

Environment-Specific Configuration

Custom Event Subscriptions

Privacy-Focused Configuration

Client Override Configuration

Accessing Apps at Runtime

Error Handling

Best Practices

1. Use All Apps

2. Environment Configuration

3. Privacy Compliance

4. Performance Optimization

See Also