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

function recommendations(): GloodAppModule

Default Configuration

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

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

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

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.

const app = glood.getApp('recommendations');

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

getSections()

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

getSections(params: GetSectionsParams): Promise<SectionsResponse>

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

getInit(params?: InitParams): Promise<InitResponse>

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.

getRecommendations(
  params: RecommendationsParams
): Promise<RecommendationsResponse | V2RecommendationsResponse>

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.

getAutomaticRecommendations(
  params: AutomaticRecommendationsParams
): Promise<AutomaticRecommendationsResponse>

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

getTopRecommendations()

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

getTopRecommendations(
  params: TopRecommendationsParams
): Promise<TopRecommendationsResponse>

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.

sendEvent(params: HeadlessEventParams): Promise<HeadlessEventResponse>

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.

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

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

function search(options?: { events?: EventType[] }): GloodAppModule

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

Default Configuration

{
  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

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:

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 full details.

App Configuration Interface

The recommendations app config structure:

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[];
}

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';

Client Override Configuration

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

Best Practices

1. Privacy Compliance

Set appropriate consent requirements:

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:

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

For Developers

App Modules

App Modules

Overview

recommendations()

Signature

Default Configuration

Basic Usage

Custom Configuration

Tracked Events

RecommendationsApp Methods

getSections()

getInit()

getRecommendations()

getAutomaticRecommendations()

getTopRecommendations()

sendEvent()

Attribution Tracking

search()

Signature

Default Configuration

Basic Usage

SearchApp Methods

App Configuration Interface

Event Types

Client Override Configuration

Accessing Apps at Runtime

Best Practices

1. Privacy Compliance

2. Performance Optimization

See Also

​App Modules

​Overview

​recommendations()

​Signature

​Default Configuration

​Basic Usage

​Custom Configuration

​Tracked Events

​RecommendationsApp Methods

​getSections()

​getInit()

​getRecommendations()

​getAutomaticRecommendations()

​getTopRecommendations()

​sendEvent()

​Attribution Tracking

​search()

​Signature

​Default Configuration

​Basic Usage

​SearchApp Methods

​App Configuration Interface

​Consent Types

​Event Types

​Client Override Configuration

​Accessing Apps at Runtime

​Best Practices

​1. Privacy Compliance

​2. Performance Optimization

​See Also

App Modules

Overview

recommendations()

Signature

Default Configuration

Basic Usage

Custom Configuration

Tracked Events

RecommendationsApp Methods

getSections()

getInit()

getRecommendations()

getAutomaticRecommendations()

getTopRecommendations()

sendEvent()

Attribution Tracking

search()

Signature

Default Configuration

Basic Usage

SearchApp Methods

App Configuration Interface

Consent Types

Event Types

Client Override Configuration

Accessing Apps at Runtime

Best Practices

1. Privacy Compliance

2. Performance Optimization

See Also