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

# App Modules

> Complete reference for recommendations(), search(), and wishlist() app modules

# 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

```typescript theme={null}
function recommendations(config?: RecommendationsAppConfig): GloodAppModule
```

### Parameters

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

### Default Configuration

```typescript theme={null}
{
  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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
function search(config?: SearchAppConfig): GloodAppModule
```

### Parameters

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

### Default Configuration

```typescript theme={null}
{
  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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
function wishlist(config?: WishlistAppConfig): GloodAppModule
```

### Parameters

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

### Default Configuration

```typescript theme={null}
{
  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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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[];
}
```

### Consent Types

Available consent types for pixel tracking:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
const glood = createGlood(config)
  .use(recommendations())
  .use(search())
  .use(wishlist());
```

### Selective Apps

Enable only specific apps to reduce bundle size:

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// ✅ Recommended - Complete functionality
const glood = createGlood(config)
  .use(recommendations())
  .use(search())
  .use(wishlist());
```

### 2. Environment Configuration

Configure apps based on environment:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
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 }
  }));
```

## See Also

* [Client API](/for-developers/glood-hydrogen-sdk/api-reference/client) - createGlood() and GloodClient
* [Event System](/for-developers/glood-hydrogen-sdk/api-reference/event-system) - Event tracking and transformation
* [Types Reference](/for-developers/glood-hydrogen-sdk/api-reference/types) - TypeScript interfaces
* [Configuration Guide](/for-developers/glood-hydrogen-sdk/configuration) - Detailed configuration options