The Browse module provides methods to browse product catalogs by filters, item IDs, groups, and facets.
Getting Started
The browse module is available on your Constructor.io client instance:
const ConstructorioClient = require('@constructor-io/constructorio-client-javascript');
const constructorio = new ConstructorioClient({
apiKey: 'YOUR_API_KEY',
});
// Access the browse module
constructorio.browse.getBrowseResults('group_id', 't-shirts');
Methods
getBrowseResults
Retrieve browse results by filter name and value.
constructorio.browse.getBrowseResults('group_id', 't-shirts')
.then((response) => {
console.log(response.response.results);
});
Parameters
The filter name to browse by (e.g., ‘group_id’, ‘category’)
The filter value to display results from
Additional parameters to refine the result set
The page number of the results (Can’t be used together with offset)
The number of results to skip from the beginning (Can’t be used together with page)
The number of results per page to return
Key/value mapping of filters used to refine results
sortBy
string
default:"relevance"
The sort method for results
sortOrder
string
default:"descending"
The sort order for results
The section name for results
Format options used to refine result groups
Faceting expression to scope browse results
Hidden metadata fields to return
The variations map object to aggregate variations
Specify whether results must match all, any or none of a given filter
getBrowseResultsForItemIds
Retrieve browse results for specific item IDs.
constructorio.browse.getBrowseResultsForItemIds(
['shirt-123', 'shirt-456', 'shirt-789']
).then((response) => {
console.log(response.response.results);
});
Parameters
Array of item IDs to fetch
Additional parameters to refine the result set
The page number of the results (Can’t be used together with offset)
The number of results to skip from the beginning
The number of results per page to return
Filters used to refine results
The section name for results
Format options used to refine result groups
Specify whether results must match all, any or none of a given filter
getBrowseGroups
Retrieve browse groups from the API.
constructorio.browse.getBrowseGroups()
.then((response) => {
console.log(response.response.groups);
});
Parameters
Additional parameters to refine the result set
Filters used to refine results
The section name for results
Format options used to refine result groups. Use groups_max_depth to control hierarchy depth.
getBrowseFacets
Retrieve all available facets for browsing.
constructorio.browse.getBrowseFacets()
.then((response) => {
console.log(response.response.facets);
});
Parameters
Additional parameters to refine the result set
The page number of the results
The number of results to skip from the beginning
The number of results per page to return
The section name for results
Format options used to refine result groups
getBrowseFacetOptions
Retrieve options for a specific facet.
constructorio.browse.getBrowseFacetOptions('price')
.then((response) => {
console.log(response.response.facets);
});
Parameters
Name of the facet whose options to return
Additional parameters
The section name for results
Format options used to refine result groups
Response Structure
{
"response": {
"results": [
{
"matched_terms": ["t-shirt"],
"data": {
"id": "shirt-123",
"title": "Blue T-Shirt",
"url": "/products/shirt-123"
},
"result_id": "abc123-xyz789"
}
],
"facets": [...],
"groups": [...],
"total_num_results": 150
},
"result_id": "abc123-xyz789",
"request": {...}
}
Each result item includes a result_id field that should be used when tracking user interactions.
Events
The browse module dispatches custom events on the browser window when requests complete:
window.addEventListener('cio.client.browse.getBrowseResults.completed', (event) => {
console.log(event.detail);
}, false);
window.addEventListener('cio.client.browse.getBrowseResultsForItemIds.completed', (event) => {
console.log(event.detail);
}, false);
window.addEventListener('cio.client.browse.getBrowseGroups.completed', (event) => {
console.log(event.detail);
}, false);
window.addEventListener('cio.client.browse.getBrowseFacets.completed', (event) => {
console.log(event.detail);
}, false);
window.addEventListener('cio.client.browse.getBrowseFacetOptions.completed', (event) => {
console.log(event.detail);
}, false);
Common Use Cases
Category Navigation
Use getBrowseResults to display products in a category:constructorio.browse.getBrowseResults('category', 'mens-clothing', {
resultsPerPage: 24,
page: 1
});
Faceted Search
Combine getBrowseResults with getBrowseFacets for filtering:// Get facets
const facetsResponse = await constructorio.browse.getBrowseFacets();
// Apply user-selected filters
const results = await constructorio.browse.getBrowseResults('category', 'shoes', {
filters: {
size: '10',
color: 'black'
}
});
Related Products
Use getBrowseResultsForItemIds to show related items:constructorio.browse.getBrowseResultsForItemIds(['item-1', 'item-2']);
