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

1. Install the API Client Package

Install the Bloomreach Discovery API client in your middleware project:

yarn add @vsf-enterprise/bloomreach-discovery-api

This package provides:

✅ Fully typed API methods generated from OpenAPI specifications
✅ Product & Category Search API
✅ Autosuggest API
✅ Content Search API
✅ Bestseller API
✅ Recommendations and Pathways API
✅ Email Widget API

Middleware Configuration

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

You can obtain these credentials from your Bloomreach representative.

3. Create Integration Configuration

Create the integration configuration file:

// apps/storefront-middleware/integrations/bloomreach-discovery/config.ts
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
import type { MiddlewareConfig } from '@vsf-enterprise/bloomreach-discovery-api';

const {
  BLOOMREACH_DISCOVERY_ACCOUNT_ID,
  BLOOMREACH_DISCOVERY_AUTH_KEY,
  BLOOMREACH_DISCOVERY_DOMAIN_KEY,
} = process.env;

if (!BLOOMREACH_DISCOVERY_ACCOUNT_ID)
  throw new Error('Missing env var: BLOOMREACH_DISCOVERY_ACCOUNT_ID');
if (!BLOOMREACH_DISCOVERY_DOMAIN_KEY)
  throw new Error('Missing env var: BLOOMREACH_DISCOVERY_DOMAIN_KEY');

export const config = {
  configuration: {
    discoveryApi: {
      accountId: Number(BLOOMREACH_DISCOVERY_ACCOUNT_ID),
      authKey: BLOOMREACH_DISCOVERY_AUTH_KEY,
      domainKey: BLOOMREACH_DISCOVERY_DOMAIN_KEY,
      facetVersion: '3.0', // Enable unified facet ranking
    },
  },
  extensions: (existing: ApiClientExtension[]) => [...existing],
  location: '@vsf-enterprise/bloomreach-discovery-api/server',
} satisfies Integration<Config>;

export type Config = MiddlewareConfig;

4. Create Integration Index

Create an index file to export the configuration:

// apps/storefront-middleware/integrations/bloomreach-discovery/index.ts
export * from './config';

5. Create Integration Types

Create a types file to export the integration types:

// apps/storefront-middleware/integrations/bloomreach-discovery/types.ts
export type {
  Endpoints as BrDiscoveryEndpoints,
  IntegrationContext,
} from '@vsf-enterprise/bloomreach-discovery-api';

6. Register in Middleware Config

// apps/storefront-middleware/middleware.config.ts
import type { MiddlewareConfig } from '@alokai/connect/middleware';
import { config as brdConfig } from './integrations/bloomreach-discovery';

export const config = {
  integrations: {
    'bloomreach-discovery': brdConfig,
    // ... other integrations
  },
} satisfies MiddlewareConfig;

7. Start the Middleware

Your middleware is now ready. Start it with:

yarn dev

SDK Configuration

Key concept - SDK

The SDK provides type-safe methods to communicate with the middleware from your storefront application. Learn more in our Key concepts: SDK docs.

8. Create SDK Module

Create a dedicated module file for Bloomreach Discovery:

// storefront-unified-nextjs/sdk/modules/bloomreach-discovery.ts
import { defineSdkModule } from '@vue-storefront/next';
import type { BrDiscoveryEndpoints } from 'storefront-middleware/types';

/**
 * `sdk.bloomreachDiscovery` allows you to call the Bloomreach Discovery API endpoints.
 * It provides access to search, recommendations, autosuggest, and more.
 */
export const bloomreachDiscovery = defineSdkModule(({ buildModule, config, middlewareModule }) =>
  buildModule(middlewareModule<BrDiscoveryEndpoints>, {
    apiUrl: `${config.apiUrl}/bloomreach-discovery`,
    ssrApiUrl: `${config.ssrApiUrl}/bloomreach-discovery`,
  }),
);

9. Export from Modules Index

Add the export to your modules index file:

// storefront-unified-nextjs/sdk/modules/index.ts
export * from './bloomreach-discovery';
// ... other module exports

10. Use the SDK

The SDK module is now automatically included in your SDK configuration. Use it in your application:

import { getSdk } from '@/sdk';

const sdk = getSdk();

// Call Bloomreach Discovery API methods
const results = await sdk.bloomreachDiscovery.productSearchApi({
  q: 'running shoes',
  rows: 20,
});

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',
  url: 'https://example.com',
  refUrl: 'https://example.com',
  brUid2: 'uid%3D7797686432023%3Av%3D11.5',
  requestId: Date.now().toString(),
});

// 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,
  url: 'https://example.com/product/123',
  refUrl: 'https://example.com',
  brUid2: 'uid%3D7797686432023%3Av%3D11.5',
  requestId: Date.now().toString(),
});

// Personalized recommendations
const personalizedRecs = await sdk.bloomreachDiscovery.personalizedRecommendationsApi({
  widgetId: 'widget_personalized',
  rows: 10,
  userId: 'user@example.com',
  url: 'https://example.com',
  refUrl: 'https://example.com',
  brUid2: 'uid%3D7797686432023%3Av%3D11.5',
  requestId: Date.now().toString(),
});

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"',
  url: 'https://example.com/bestsellers',
  refUrl: 'https://example.com',
  brUid2: 'uid%3D7797686432023%3Av%3D11.5',
  requestId: Date.now().toString(),
});

API Parameters

Common Parameters

Most API methods require the following common parameters:

accountId - Your Bloomreach account ID (automatically injected)
authKey - Authentication key (automatically injected if configured)
domainKey - Your domain key (automatically injected)
url - Current page URL
refUrl - Referrer URL
brUid2 - Bloomreach user ID cookie value
requestId - Unique request identifier (e.g., timestamp)

These parameters are automatically injected by the API client for the base configuration (accountId, authKey, domainKey, facetVersion), so you only need to provide request-specific parameters.