JavaScript SDK

Overview

The Fredhopper SDK is designed as a lean API client for interacting with the Fredhopper Query API, through the Shopify App Proxy, focused on making it easy to query Fredhopper endpoints while letting developers build their own UI and rendering logic. It handles authentication, request formatting, and provides utilities for common Fredhopper operations.

To enable the SDK Theme Embed provided with the Shopify App, see the documentation

For more details on using the Fredhopper Query Language, used by both the SDK and the Query API, see the documentation.

Quick Start

Basic Setup

The SDK is automatically initialized when the script loads. Credentials are managed through the app and exposed via window.fredhopper.credentials.

// SDK is available globally
const collectionResults = await fredhopper.queryCatalog({category: "12345"});
const searchResults= await fredhopper.queryCatalog({term: "shoes", view: "search"});

Development Mode

Add ?fhr_debug=true to your URL to enable detailed console logging in the browser console.

API Reference

Core Methods

`queryCatalog(options)`

Stateless method to query a catalog with advanced options in Fredhopper.

// Example: Search for products with filters and sorting
const results = await fredhopper.queryCatalog({
  page: 1,
  limit: 24,
  sort: "price-asc",
  filters: {
    brand: ["nike", "adidas"],
    price: "10<price<100",
  },
  category: "12345",
  view: "search",
  term: "shoes",
});

// Example: Collection query with filters and sorting
const results = await fredhopper.queryCatalog({
  page: 1,
  limit: 36,
  sort: "price-desc",
  filters: {
    size: ["8", "9", "10"],
    color: ["red"],
  },
  category: "789",
});

Parameters:

options (object, optional): Configuration object

Options Properties:

page (number, optional): Page number. Default: 1
limit (number, optional): Results per page. Default: 24
sort (string, optional): Sort option. Default: "relevance"
- Available values: "relevance", "price-asc", "price-desc", or custom sort field
filters (object, optional): Filter object. Default: {}
- Single value: { brand: "nike" } or { brand: ["nike"] }
- Multiple values: { brand: ["nike", "adidas"] }
- Range values: { price: "10<price<100" }
catalog (string, optional): Catalog identifier. Default: "catalog01"
locale (string, optional): Locale in Fredhopper format (e.g., "en_GB"). Default: auto-detected with utils.detectLocale()
category (string, optional): Category identifier. Default: ''
- The category ID originates from Shopify's collection object using the Liquid variable {{ collection.id }} and is automatically available.
view (string, optional): Fredhopper view type. Default: "lister"
- It is recommended to use "search" for search queries.
term (string, optional): Search term. Default: ''
suppress (string, optional): Default: ''
- Fredhopper suppress parameter to suppress parts of the response (e.g., 'facets')

Returns: Promise<any> - Query results from Fredhopper API

Important Note:

The Fredhopper API requires two key parameters:

fh_view- Specifies Fredhopper view type. It defaults to 'lister' and can be set via the view option.
fh_location - Automatically built from your catalog, locale, search term, category, and filters using the SDK's location builder.

Following parameters are added automatically to the request payload based on the options provided:

fh_location - Built from catalog, locale, term, category, and filters
fh_view - Set from view
fh_view_size - Set from limit
fh_start_index - Calculated from page and limit
fh_sort_by - Omitted for sort=relevance which is the default
fh_suppress - Set from suppress
fh_session - Default: "shopify-app"
market - Default: auto-detected from locale
credentials - Hash containing API credentials
fh_session_id - Unique session identifier for tracking. Omitted if it does not exist.

`queryProduct(options)`

Stateless method to query a product with advanced options in Fredhopper.

// Example: a product
const results = await fredhopper.queryProduct({
  id: "0123456789"
});

// Example: a product and variant
const results = await fredhopper.queryProduct({
  id: "0123456789",
  id2: "9876543210"
});

// Example: product query with filters
const results = await fredhopper.queryProduct({
  id: "0123456789",
  filters: {
    size: ["8", "9", "10"],
    color: ["red"],
  },
  suppress: "facets"
});

Parameters:

options (object, optional): Configuration object

Options Properties:

id (string): product id
id2 (string): variant id
filters (object, optional): Filter object. Default: {}
- Single value: { brand: "nike" } or { brand: ["nike"] }
- Multiple values: { brand: ["nike", "adidas"] }
- Range values: { price: "10<price<100" }
catalog (string, optional): Catalog identifier. Default: "catalog01"
locale (string, optional): Locale in Fredhopper format (e.g., "en_GB"). Default: auto-detected with utils.detectLocale()
category (string, optional): Category identifier. Default: ''
- The category ID originates from Shopify's collection object using the Liquid variable {{ collection.id }} and is automatically available.
view (string, optional): Fredhopper view type. Default: "detail"
term (string, optional): Search term. Default: ''
suppress (string, optional): Default: ''
- Fredhopper suppress parameter to suppress parts of the response (e.g., 'facets')

Returns: Promise<any> - Query results from Fredhopper API

Important Note:

The Fredhopper API requires two key parameters:

fh_view- Specifies Fredhopper view type. It defaults to 'detail' and can be set via the view option.
fh_location - Automatically built from your catalog, locale, search term, category, and filters using the SDK's location builder.

Following parameters are added automatically to the request payload based on the options provided:

fh_location - Built from catalog, locale, term, category, and filters
fh_secondid - Set from id
fh_secondid2 - Set from id2
fh_view - Set from view
fh_suppress - Set from suppress
fh_session - Default: "shopify-app"
market - Default: auto-detected from locale
credentials - Hash containing API credentials
fh_session_id - Unique session identifier for tracking. Omitted if it does not exist.

Raw API Access

`rawRequest(params)`

Direct API request with full control over all Fredhopper parameters:

const results = await fredhopper.rawRequest({
  fh_location: "//catalog01/en_GB/categories<{shoes}/brand=nike",
  fh_view: "lister",
  fh_view_size: 48,
  fh_start_index: 0,
  fh_sort_by: "-price",
  market: "GB",
  custom_param: "value",
});

Parameters:

params (object, required): Direct Fredhopper API parameters

Required Parameters:

fh_location (string): Fredhopper location string
fh_view (string): Fredhopper view type

Optional Parameters:

fh_view_size (number): Number of results
fh_start_index (number): Starting index for pagination
fh_sort_by (string): Sort field
fh_session (string): Session identifier
fh_session_id (string): Unique session ID
market (string): Market code

Returns: Promise<any> - Raw API response

Important Note: Credentials are automatically added to all requests.

Utilities

Location Building

`utils.buildLocation(options)`

Build Fredhopper location strings programmatically.

const location = fredhopper.utils.buildLocation({
  catalog: "catalog01",
  locale: "en_GB",
  searchTerm: "shoes",
  category: "catalog01_12345",
  filters: {
    brand: ["nike"],
    price: "50<price<200",
  },
  facetMultiMap: {
    brand: true,
  },
  view: "search",
});

// Result: "//catalog01/en_GB/categories<{catalog01_12345}/$s=shoes/brand>{nike}/50<price<200"

Parameters:

options (object, optional): Location building configuration

Options Properties:

catalog (string, optional): Catalog identifier. Default: "catalog01"
locale (string, optional): Locale. Default: auto-detected using utils.detectLocale()
searchTerm (string, optional): Search term. Default: ''
category (string, optional): Category identifier. Default: ''
filters (object, optional): Filter object. Default: {}
facetMultiMap (object, optional): Defines which facets allow multiple selections. Default: {}
Format: { facetName: true/false }
true = multi-select, false = single-select
view (string, optional): Fredhopper view type. Default: "lister"

Returns: string - Formatted Fredhopper location string

Encoding Utilities

`utils.encodeFHUnicodeValue(value)`

Encode filter values for Fredhopper Unicode format.

const encoded = fredhopper.utils.encodeFHUnicodeValue("special chars!");

// Result: "special\\u0020chars\\u0021"

Parameters:

value (string, required): Value to encode

Returns: string - Encoded value

`utils.formatSearchTerm(term)`

Format search terms for Fredhopper by converting special characters to Unicode escape sequences.

const formatted = fredhopper.utils.formatSearchTerm("running shoes");

// Result: "running\\u0020shoes"

Parameters:

term (string, required): Search term to format
view (string, optional): Fredhopper view type. Default: "lister"

Returns: string - Formatted search term

Other Utilities

`utils.debounce(func, delay)`

Debounce function for optimizing search inputs and preventing excessive API calls.

const debouncedSearch = fredhopper.utils.debounce(async (term) => {
  if (term.length > 2) {
    const results = await fredhopper.queryCatalog({
      page: 1,
      limit: 24,
      term: term,
      view: "search",
    });
    updateSearchResults(results);
  }
}, 300);

Parameters:

func (function, required): Function to debounce
wait (number, required): Delay in milliseconds

Returns: function - Debounced function

`utils.detectLocale()`

Auto-detect Shopify locale and convert it to Fredhopper format.

const locale = fredhopper.utils.detectLocale();

// Result: "en_GB" (based on window.Shopify.locale/country)

Parameters: None

Returns: string - Fredhopper locale string

`utils.formatPrice(price, currency)`

Format prices using Intl.NumberFormat.

const formatted = fredhopper.utils.formatPrice(29.99, "USD");

// Result: "$29.99"

Parameters:

price (number, optional): Price to format. Default: 0
currency (string, optional): Currency code. Default: "USD"

Returns: `string - Formatted price string

Configuration & Initialization

Basic Initialization

Initialize or reconfigure the SDK. The SDK auto-initializes on load, but you can reconfigure it.

await fredhopper.init({
  debug: true,
  development: false,
});

Parameters:

options (object, optional): Configuration object

Options Properties:

debug (boolean, optional): Enable debug logging
development (boolean, optional): Enable development mode

Returns: Promise<void>

Event Handling

`onReady(callback)`

Execute callback when SDK is fully initialized.

fredhopper.onReady(() => {
  console.log("SDK ready!");
  
  // Perform initial search/collection load
});

Parameters:

callback (function, required): Function to execute when ready

Returns: void

Event System

Subscribe to SDK events.

fredhopper.events.on("filtersChanged", (filters) => {
  console.log("Filters updated:", filters);
});

fredhopper.events.emit("customEvent", data);

Parameters:

event (string, required): Event name
callback (function, required): Event handler function

Returns: void

Examples

Basic Product Search

async function searchProducts(term, view) {
  try {
    const results = await fredhopper.queryCatalog({
      limit: 24,
      sort: "relevance",
      locale: fredhopper.utils.detectLocale(),
      term: term,
      view: view || "search",
    });

    displayProducts(results);
  } catch (error) {
    console.error("Search failed:", error);
  }
}

Advanced Collection with Filters

async function loadFilteredCollection(categoryId, userFilters = {}) {
  const results = await fredhopper.queryCatalog({
    category: categoryId,
    page: 1,
    limit: 36,
    sort: "price-asc",
    filters: userFilters,
  });

  return results;
}

// Usage
const products = await loadFilteredCollection("12345", {
  brand: ["nike", "adidas"],
  size: ["8", "9", "10"],
  price: "20<price<150"
});

Debounced Search Input

const searchInput = document.getElementById("search");
const debouncedSearch = fredhopper.utils.debounce(async (term) => {
  if (term.length > 2) {
    const results = await fredhopper.queryCatalog({limit: 10, term: term, view: "search"});
    updateSearchResults(results);
  }
}, 300);

searchInput.addEventListener("input", (e) => {
  debouncedSearch(e.target.value);
});

Error Handling

The SDK throws errors for failed requests. Always wrap API calls in try-catch blocks:

try {
  const results = await fredhopper.queryCatalog({term: "shoes", view: "search"});
  // Handle successful response
} catch (error) {
  if (error.message.includes("API request failed")) {
    // Handle API errors
    console.error("Fredhopper API error:", error);
  } else {
    // Handle other errors
    console.error("Unexpected error:", error);
  }
}

Best Practices

1. Handle Localization

Use utils.detectLocale() to automatically handle different markets:

const results = await fredhopper.queryCatalog({
  locale: fredhopper.utils.detectLocale(), // Auto-detects from Shopify
  term: "shoes",
  view: "search",
});

3. Debounce User Input

Always debounce search inputs to avoid excessive API calls:

const debouncedSearch = fredhopper.utils.debounce(searchFunction, 300);

4. Use Location Builder for Complex Queries

For complex filtering scenarios, use the location builder utility:

const location = fredhopper.utils.buildLocation({
  // ... complex filter logic
});

const results = await fredhopper.rawRequest({
  fh_location: location,
  fh_view: "search",
});

5. Handle Loading States

Track loading states in your UI:

// Example: Using CSS classes for loading state
const container = document.querySelector('.products-container');
container.classList.add('is-loading');
try {
  const results = await fredhopper.queryCatalog({ term: "shoes", view: "search" });
  displayResults(results);
} finally {
  container.classList.remove('is-loading');
}

Troubleshooting

Debug Mode

Enable debug mode to see detailed request/response logging:

https://yourstore.com/collections/shoes?fhr_debug=true

Common Issues

Credentials Missing: Ensure the app is properly installed and credentials are set
CORS Errors: The SDK uses Shopify proxies to avoid CORS issues
Invalid Location Strings: Use the location builder utility to ensure proper formatting
Rate Limiting: Implement debouncing for user input

TypeScript Support

While the SDK is written in JavaScript, it includes JSDoc type annotations for better IDE support. For full TypeScript support, you can create type definitions:

declare global {
  interface Window {
    fredhopper: {
      queryCatalog(
        options: AdvancedSearchOptions
      ): Promise<any>;
      rawRequest(params: Record<string, any>): Promise<any>;
      utils: {
        buildLocation(options: LocationOptions): string;
        encodeFHUnicodeValue(value: string): string;
        formatSearchTerm(term: string): string;
        debounce(func: Function, delay: number): Function;
        detectLocale(): string;
        formatPrice(price: number, currency: string): string;
      };
    };
  }
}

Support

For issues specific to this SDK implementation, check:

Console logs with ?fhr_debug=true
Network tab for API request/response details
Verify credentials are properly set in the app

For Fredhopper API documentation and support, consult the official Fredhopper documentation.

PreviousUser Guide NextWeb-Pixel Integration

Last updated 2 months ago

hashtagOverview

hashtagQuick Start

hashtagBasic Setup

hashtagDevelopment Mode

hashtagAPI Reference

hashtagCore Methods

hashtagqueryCatalog(options)

hashtagqueryProduct(options)

hashtagRaw API Access

hashtagrawRequest(params)

hashtagUtilities

hashtagLocation Building

hashtagutils.buildLocation(options)

hashtagEncoding Utilities

hashtagutils.encodeFHUnicodeValue(value)

hashtagutils.formatSearchTerm(term)

hashtagOther Utilities

hashtagutils.debounce(func, delay)

hashtagutils.detectLocale()

hashtagutils.formatPrice(price, currency)

hashtagConfiguration & Initialization

hashtagBasic Initialization

hashtagEvent Handling

hashtagonReady(callback)

hashtagEvent System

hashtagExamples

hashtagBasic Product Search

hashtagAdvanced Collection with Filters

hashtagDebounced Search Input

hashtagError Handling

hashtagBest Practices

hashtag1. Handle Localization

hashtag3. Debounce User Input

hashtag4. Use Location Builder for Complex Queries

hashtag5. Handle Loading States

hashtagTroubleshooting

hashtagDebug Mode

hashtagCommon Issues

hashtagTypeScript Support

hashtagSupport

Overview

Quick Start

Basic Setup

Development Mode

API Reference

Core Methods

`queryCatalog(options)`

`queryProduct(options)`

Raw API Access

`rawRequest(params)`

Utilities

Location Building

`utils.buildLocation(options)`

Encoding Utilities

`utils.encodeFHUnicodeValue(value)`

`utils.formatSearchTerm(term)`

Other Utilities

`utils.debounce(func, delay)`

`utils.detectLocale()`

`utils.formatPrice(price, currency)`

Configuration & Initialization

Basic Initialization

Event Handling

`onReady(callback)`

Event System

Examples

Basic Product Search

Advanced Collection with Filters

Debounced Search Input

Error Handling

Best Practices

1. Handle Localization

3. Debounce User Input

4. Use Location Builder for Complex Queries

5. Handle Loading States

Troubleshooting

Debug Mode

Common Issues

TypeScript Support

Support