> ## 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() app module

# App Modules

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

## Overview

The SDK ships a single app module:

* **`recommendations()`** - Product recommendations and personalization

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' }],
});
```

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