Discovery Web SDK
SDK Reference
The detailed TSDoc and reference for the SDK are available here.
The Bloomreach Discovery Web SDK is a TypeScript SDK designed to interact with the
Bloomreach Discovery APIs. This SDK provides a convenient way to integrate and use the Discovery data in your website or applications.
The SDK provides an interface to implement the following Bloomreach Discovery APIs:
- Autosuggest API
- Product and Category Search API
- Content Search API
- Recommendations and Pathways APIs
- Bestseller API
The Discovery Web SDK is fully Open-Sourced and open to contributions.
Getting Started
Requirements
The SDK currently requires:
Installation
npm add @bloomreach/discovery-web-sdk
pnpm add @bloomreach/discovery-web-sdk
yarn add @bloomreach/discovery-web-sdk
Debug logging
Adding debug: true
to the Configuration
you pass into the API calls will enable some minor debug logging with [BR]
as a prefix for your convenience.
Usage
Below are some usage examples that demonstrate how to call and use various Discovery APIs in your website or application using the SDK.
Autosuggest API
import type { Configuration, AutosuggestOptions } from '@bloomreach/discovery-web-sdk';
import { autosuggest } from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: AutosuggestOptions = {
catalog_views: 'product:store1,store2|recipe:premium|articles',
q: 'Roses',
url: 'http://example.com',
_br_uid_2: 'someCookieId',
};
// Retrieve the suggestions with a search using the provided search parameters
const data = await autosuggest(config, searchOptions);
Product and Category Search API
Product Search
import type { Configuration, ProductSearchOptions } from '@bloomreach/discovery-web-sdk';
import { productSearch } from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: ProductSearchOptions = {
q: 'Generic Metal Pants',
fl: 'pid,title,description,brand,price,thumb_image',
start: 0,
rows: 10,
url: 'http://example.com',
_br_uid_2: 'someCookieId',
};
// Retrieve the product data with a search using the provided search parameters
const data = await productSearch(config, searchOptions);
Category Search
import type { Configuration, CategorySearchOptions } from '@bloomreach/discovery-web-sdk';
import { categorySearch } from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: CategorySearchOptions = {
q: 'cat92082',
fl: 'pid,title,description,brand,price,thumb_image',
start: 0,
rows: 10,
url: 'http://example.com',
_br_uid_2: 'someCookieId',
};
// Retrieve the product data with a search using the provided search parameters
const data = await categorySearch(config, searchOptions);
Content Search API
import type { Configuration, ContentSearchOptions } from '@bloomreach/discovery-web-sdk';
import { contentSearch } from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: ContentSearchOptions = {
catalog_name: 'Flowers',
q: 'Roses',
fl: 'pid,title,description,brand,price,thumb_image',
start: 0,
rows: 10,
url: 'http://example.com',
_br_uid_2: 'someCookieId',
};
// Retrieve the Content data with a search using the provided search parameters
const data = await contentSearch(config, searchOptions);
Recommendations and Pathways APIs
import {
CategoryWidgetOptions,
Configuration,
WidgetResponse,
getCategoryWidget,
} from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: CategoryWidgetOptions = {
cat_id: 'cat123959',
start: 0,
rows: 10,
url: 'http://example.com',
ref_url: 'http://google.com',
request_id: 1234,
_br_uid_2: 'test',
};
const widgetId = 'my_widget_id';
// Retrieve the widget using the widgetId and parameters
const widget = getCategoryWidget(widgetId, config, searchOptions);
Similar functions and types are exposed for all widget types:
getGlobalWidget
getKeywordWidget
getCategoryWidget
getItemWidget
getPersonalizedWidget
getRecentlyViewedWidget
Bestseller API
import type { Configuration, BestsellerOptions } from '@bloomreach/discovery-web-sdk';
import { bestseller } from '@bloomreach/discovery-web-sdk';
// Set the account and catalog configuration
const config: Configuration = {
account_id: 1234,
domain_key: 'example_com',
};
// Set up the search parameters
const searchOptions: BestsellerOptions = {
q: 'Bolts',
fl: 'pid,title,description,brand,price,thumb_image',
start: 0,
rows: 10,
url: 'http://example.com',
_br_uid_2: 'someCookieId',
};
// Retrieve the product data with a search using the provided search parameters
const data = await bestseller(config, searchOptions);
Contribution & Development
The Bloomreach Discovery SDK is Open-Source, and we welcome outside contributions. See our Contribution Guide.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Updated 5 days ago