> ## 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 the recommendations() and search() app modules

# App Modules

App modules provide modular functionality for Glood features. Each module is registered with the Glood client via `.use()`.

## Overview

The SDK ships two app modules:

* **`recommendations()`** - Product recommendations and personalization (v3)
* **`search()`** - AI search & discovery (v1)

The module follows this 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(): GloodAppModule
```

### Default Configuration

```typescript theme={null}
{
  endpoint: 'https://storefront.glood.ai',
  pixel: {
    enabled: true,
    endpoint: 'https://storefront.glood.ai',
    consent: ['analytics', 'marketing'],
  },
}
```

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

Endpoints and pixel settings are customized at the client level via the
`apps.recommendations` config block:

```typescript theme={null}
import { createGlood, recommendations, CONSENT_TYPES } from '@glood/hydrogen';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  apps: {
    recommendations: {
      endpoint: 'https://custom-recommendations.glood.ai',
      pixel: {
        enabled: true,
        endpoint: 'https://custom-recommendations.glood.ai',
        consent: [CONSENT_TYPES.ANALYTICS], // Only analytics consent
      },
      subscribedEvents: ['product_viewed', 'cart_viewed'], // Limited events
    },
  },
}).use(recommendations());
```

### Tracked Events

The recommendations app subscribes to these Shopify Analytics 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 |

## RecommendationsApp Methods

Get the app instance from the client and call its methods to fetch
recommendations and record attribution.

```typescript theme={null}
const app = glood.getApp('recommendations');
```

<Note>
  Methods marked **v3** require a version-3 client (the default). Calling a v3-only
  method such as `getInit` on a `version: 2` client throws.
</Note>

### getSections()

Fetch recommendation sections (with full product data) for the current visitor. **v3.**

```typescript theme={null}
getSections(params: GetSectionsParams): Promise<SectionsResponse>
```

```typescript theme={null}
const { sections } = await app.getSections({
  pageType: 'product_page',
  productId: 123456789,
});
```

### getInit()

Bootstrap a headless session — server-issued ids, visitor history, shop config,
and storefront token. **v3 only** (throws for v2 clients).

```typescript theme={null}
getInit(params?: InitParams): Promise<InitResponse>
```

```typescript theme={null}
const init = await app.getInit({ pageType: 'home' });
console.log(init.visit_id, init.visitor.browsed_products);
```

### getRecommendations()

Fetch anchor-based recommendations. **Version-aware** — uses the client's
configured API version. v3 returns `RecommendationsResponse`; v2 returns the
legacy `V2RecommendationsResponse` shape.

```typescript theme={null}
getRecommendations(
  params: RecommendationsParams
): Promise<RecommendationsResponse | V2RecommendationsResponse>
```

```typescript theme={null}
const res = await app.getRecommendations({
  queries: [
    {
      id: 'pdp-similar',
      recommendationType: 'similar_products',
      productIds: [123456789],
      view: 'product_details',
    },
  ],
});
```

### getAutomaticRecommendations()

Fetch single-anchor, cursor-paginated similar-products recommendations. **v3.**

```typescript theme={null}
getAutomaticRecommendations(
  params: AutomaticRecommendationsParams
): Promise<AutomaticRecommendationsResponse>
```

```typescript theme={null}
const res = await app.getAutomaticRecommendations({
  productIds: [123456789],
  view: 'product_details',
  pagination: { limit: 12 },
});
```

### getTopRecommendations()

Fetch anchorless, strategy-ranked, faceted catalog recommendations. **v3.**

```typescript theme={null}
getTopRecommendations(
  params: TopRecommendationsParams
): Promise<TopRecommendationsResponse>
```

```typescript theme={null}
const res = await app.getTopRecommendations({
  strategy: 'BESTSELLERS', // 'BESTSELLERS' | 'NEW_ARRIVALS' (uppercase)
  view: 'product_details',
  facets: ['vendor', 'product_type'],
});
```

### sendEvent()

Send a single interaction event to the headless events endpoint. **v3.**

```typescript theme={null}
sendEvent(params: HeadlessEventParams): Promise<HeadlessEventResponse>
```

```typescript theme={null}
await app.sendEvent({
  event: {
    id: crypto.randomUUID(),
    name: 'product_viewed',
    type: 'standard',
    timestamp: new Date().toISOString(),
    data: { productId: '123456789' },
  },
});
```

### Attribution Tracking

The following helpers emit `glood:section:*` custom events to attribute
interactions back to a rendered section. Each takes a `SectionTrack` and returns
`void`.

```typescript theme={null}
trackRender(track: SectionTrack): void      // section rendered in the DOM
trackView(track: SectionTrack): void        // section entered the viewport
trackClick(track: SectionTrack): void       // click on a recommended product
trackAddToCart(track: SectionTrack): void   // add-to-cart of a recommended product
```

```typescript theme={null}
app.trackClick({
  section: '42',
  sectionServeId: section.section_serve_id,
  requestId: sectionsResponse.request_id,
  page: 'product',
  products: [{ productId: '123456789', variantId: '987654321' }],
});
```

## search()

Enables AI search & discovery — instant search, full search results, filters, and image
search. Search is a **v1** headless API on its own host, independent of the client's global
`version`.

### Signature

```typescript theme={null}
function search(options?: { events?: EventType[] }): GloodAppModule
```

`options.events` narrows which Shopify standard events are forwarded to the search backend
(default: **all** events).

### Default Configuration

```typescript theme={null}
{
  apiVersion: 1, // pinned — always v1, even on a v2/v3 client
  endpoint: 'https://search.glood.ai',
  pixel: {
    enabled: true,
    endpoint: 'https://search.glood.ai/api/storefront/event',
    consent: ['analytics'],
  },
}
```

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

// Narrow forwarded events:
const glood2 = createGlood({ apiKey, myShopifyDomain })
  .use(search({ events: ['search_submitted', 'product_added_to_cart'] }));
```

### SearchApp Methods

Get the app instance and call its methods:

```typescript theme={null}
const app = glood.getApp('search'); // SearchApp
```

| Method | Signature |
| - | - |
| `config` | `(params?: SearchConfigParams) => Promise<SearchConfigResponse>` |
| `instantSearch` | `(params: InstantSearchParams) => Promise<InstantSearchResponse>` |
| `filters` | `(params?: FiltersParams) => Promise<FiltersResponse>` |
| `search` | `(params?: SearchParams) => Promise<SearchResponse>` |
| `imageSearch` | `(params: ImageSearchParams) => Promise<ImageSearchResponse>` |

Plus the attribution helpers `trackSearch`, `trackResultView`, `trackResultClick`,
`trackAddToCart`, `trackFilter` — each takes a `SearchTrack` and emits a `glood:search:*`
custom event. See the [Search API Reference](/for-developers/glood-hydrogen-sdk/api-reference/search-api#searchapp)
for full details.

## App Configuration Interface

The recommendations app config structure:

```typescript theme={null}
interface RecommendationsAppConfig {
  /** 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';
```

## Client Override Configuration

The recommendations app configuration 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://custom-storefront.glood.ai',
        consent: ['analytics'],
      },
    },
  },
}).use(recommendations()); // Will use overridden 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,
  });
});
```

## Best Practices

### 1. Privacy Compliance

Set appropriate consent requirements:

```typescript theme={null}
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://storefront.glood.ai',
        consent: ['analytics', 'marketing'],
      },
    },
  },
}).use(recommendations());
```

### 2. Performance Optimization

Disable pixel tracking in development:

```typescript theme={null}
const isDev = process.env.NODE_ENV === 'development';

const glood = createGlood({
  apiKey: process.env.GLOOD_API_KEY!,
  myShopifyDomain: 'your-store.myshopify.com',
  apps: {
    recommendations: {
      endpoint: 'https://storefront.glood.ai',
      pixel: {
        enabled: !isDev,
        endpoint: 'https://storefront.glood.ai',
        consent: ['analytics'],
      },
    },
  },
}).use(recommendations());
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.