Quick start

Prerequisites

• Node.js version 20.x or 22.14+
• Yarn package manager
• Bloomreach Discovery account with API credentials

Overview

This guide will walk you through integrating Bloomreach Discovery into your Alokai storefront. The integration uses the official Bloomreach Discovery REST APIs for search, merchandising, and product recommendations.

Installation

From the root of your project run the following command:

npx @vsf-enterprise/storefront-cli add-module search-bloomreach -e sapcc

Follow the instructions in the command line to complete the installation. To make sure the installation is finished, go to the apps/storefront-middleware/sf-modules folder and check if there's a folder named search-bloomreach inside.

The module automatically:

• Installs the @vsf-enterprise/bloomreach-discovery-api middleware package
• Configures the middleware integration with the unified extension
• Sets up both SDK modules (bloomreach for the raw API and bloomreachUnified for normalized data)
• Copies necessary components into your storefront

Set up environment variables

Add the following environment variables to your .env file:

# Required: Your Bloomreach account ID
BLOOMREACH_DISCOVERY_ACCOUNT_ID=your_account_id

# Required: Your Bloomreach domain key
BLOOMREACH_DISCOVERY_DOMAIN_KEY=your_domain_key

# Optional: Authentication key (required for authenticated accounts)
BLOOMREACH_DISCOVERY_AUTH_KEY=your_auth_key

# Optional: API environment ("staging" or "production", defaults to "production")
BLOOMREACH_DISCOVERY_ENVIRONMENT=production

You can obtain these credentials from your Bloomreach representative.

Start the middleware

Your middleware is now ready. Start it with:

yarn dev

Usage Examples

Product Search

Search for products with filtering and faceting:

const sdk = getSdk();

const searchResults = await sdk.bloomreachDiscovery.productSearchApi({
  q: 'running shoes',
  rows: 20,
  start: 0,
  'facet.range': 'price',
  fl: 'pid,title,price,thumb_image',
  sort: 'price asc',
});

// Access typed results
const products = searchResults.data.response.docs;
const facets = searchResults.data.facet_counts;

Autosuggest

Provide real-time search suggestions:

const suggestions = await sdk.bloomreachDiscovery.autosuggest({
  q: 'lapt',
  catalogViews: 'store_view',
  requestType: 'suggest',
});

// Access suggestions
const querySuggestions = suggestions.data.suggestionGroups[0]?.querySuggestions;
const productSuggestions = suggestions.data.suggestionGroups[0]?.searchSuggestions;

Category Search

Search within a specific category:

const categoryResults = await sdk.bloomreachDiscovery.categorySearchApi({
  q: 'electronics',
  rows: 10,
  start: 0,
  'facet.version': '3.0',
});

Product Recommendations

Show personalized product recommendations:

// Item-based recommendations (e.g., "Frequently Bought Together")
const itemRecs = await sdk.bloomreachDiscovery.itemBasedRecommendationsApi({
  itemIds: 'product123',
  widgetId: 'widget_fbt',
  rows: 4,
});

// Personalized recommendations
const personalizedRecs = await sdk.bloomreachDiscovery.personalizedRecommendationsApi({
  widgetId: 'widget_personalized',
  rows: 10,
  userId: 'user@example.com',
});

Content Search

Search through content items:

const contentResults = await sdk.bloomreachDiscovery.contentSearchApi({
  q: 'holiday gift guide',
  catalogName: 'content_catalog',
  rows: 10,
  fl: 'title,description,url,image',
});

Bestseller Products

Get bestselling products:

const bestsellers = await sdk.bloomreachDiscovery.bestsellerApi({
  rows: 12,
  start: 0,
  query: 'category:"Electronics"',
});

API Parameters

Common Parameters

Most API methods require the following common parameters, all of which are automatically injected by the API client:

From middleware config:

• accountId - Your Bloomreach account ID
• authKey - Authentication key
• domainKey - Your domain key

From incoming HTTP request:

• brUid2 - Bloomreach tracking cookie (_br_uid_2), extracted from the cookie header
• url - Current page URL, reconstructed from request headers
• refUrl - Referrer URL, from the Referer header
• requestId - Auto-generated 13-digit random value for click tracking

You only need to provide request-specific parameters (e.g., q, rows, sort). All injected parameters can be overridden per call if needed.

Next steps

If you need to wire the integration manually without the module installer, see the Manual Setup guide.