Installation
This guide walks you through installing and configuring the Alokai Compass module in your Storefront project.
The installation process consists of two main parts:
- Installing the module: Use the Alokai CLI to install dependencies and copy module files to your project
- Enabling module features: Configure your Storefront to display the AI Assistant, Use Cases Manager, and AI-powered Search components
Installing the module
Use the Alokai CLI to automatically install Compass module dependencies and copy the necessary files to your Storefront project. This sets up the core infrastructure needed for AI-powered workflows.
1
Run @vsf-enterprise/storefront-cli
From the root of your Storefront project, run the following command:
npx @vsf-enterprise/storefront-cli add-module compass -e=sapcc
This command will:
- Copy module files into the
sf-modulesdirectory of yourstorefront-middlewareandstorefront-unified-nextjsapps - Install
@alokai/compassin yourstorefront-middlewareandstorefront-unified-nextjsapps
Enabling module features
The Alokai Compass module includes several pre-built components that enhance your Storefront with AI-powered features. Follow these steps to integrate them into your application.
1
Add AI feature: AI Assistant
Integrate the AI Assistant component into your application's root layout to enable conversational AI functionality throughout your Storefront.
Import the CompassProvider and AiAssistant components, then wrap your root layout's children with these components.
+ import AiAssistant from '@/sf-modules/compass/components/ai-assistant/ai-assistant';
+ import { CompassProvider } from '@/sf-modules/compass/contexts/compass-context';
export default async function RootLayout({ children, params: { locale } }: RootLayoutProps) {
return (
<html>
{/* */}
<body>
{/* */}
+ <CompassProvider>
+ <AiAssistant>
+ <RootLayoutContentWrapper>{children}</RootLayoutContentWrapper>
+ </AiAssistant>
+ </CompassProvider>
</body>
</html>
)
}
2
Add AI feature: Use Case Comparison
Enable the AI-powered Use Cases feature throughout your product catalog. This feature helps customers rate products according to their own criteria and make the best possible choice.
First, update the ProductCardVertical component to support use cases display by adding the necessary props and integrating the LatestUseCases component.
+ import LatestUseCases from '@sf-modules/compass/components/use-cases/latest-use-cases';
export interface ProductCardVerticalProps extends PropsWithStyle {
/** ...other properties */
+ /**
+ * Show use cases ratings
+ */
+ showUseCases?: boolean;
+ /**
+ * Product description
+ */
+ description?: string;
}
export default function ProductCardVertical({
description,
title,
id,
+ description = '',
+ showUseCases = false,
}: ProductCardVerticalProps) {
return (
<>
{/* Product Rating component */}
+ {showUseCases && (
+ <div className="mt-auto pb-2 pt-2">
+ <LatestUseCases
+ productToReview={{
+ description,
+ id,
+ name: title,
+ }}
+ />
+ </div>
+ )}
{/* Decorated Price component */}
</>
);
}
Next, in the Products List component where the ProductCardVertical component is used, pass the showUseCases and description props to enable use cases display.
export default async function ProductListPage() {
return products.map(({
+ $custom
}, index) => (
<ProductCardVertical
+ description={$custom?.description ?? ''}
+ showUseCases={true}
/>
));
}
Finally, import the UseCasesProvider and UseCasesManager components. Wrap the entire products listing page with the UseCasesProvider and place the UseCasesManager in the filters sidebar.
+ import UseCasesManager from '@/sf-modules/compass/components/use-cases/use-cases-manager';
+ import { UseCasesProvider } from '@/sf-modules/compass/contexts/use-cases-context';
export default function ProductsListingPage({
return (
+ <UseCasesProvider>
{/* */}
{!hideFilters && (
<NextIntlClientProvider>
<AccordionProvider active={['category-tree', ...facets.map((facet) => facet.name)]} allowMultipleOpen>
<FiltersContainer>
+ <FilterGroup title={'Use cases'}>
+ <UseCasesManager />
+ </FilterGroup>
{/* */}
</FiltersContainer>
</AccordionProvider>
</NextIntlClientProvider>
)}
{/* */}
+ </UseCasesProvider>
)
});
3
Add AI feature: Product Page messages
AI Assistant can detect when customers navigate to product pages and provide product details along with suggested next steps in the chat window.
To enable this feature, import the ProductMessage component and add it to the product page after the breadcrumbs component.
+ import ProductMessage from '@/sf-modules/compass/components/ai-assistant/product-message';
export default connectCmsPage(
async (props) => {
return (
<>
{/* Breadcrumbs Component */}
+ <ProductMessage product={product} />
</>
)
}
)
4
Add Unified API overrides
Some Alokai Compass features require additional data in Server Middleware responses or customized API method behavior. To support these requirements, register the custom fields and method overrides provided by the Alokai Compass module in the Unified API Extension for SAPCC.
+ import { compassCustomFields } from '@/sf-modules/compass/overrides/custom-fields';
+ import { searchProducts } from '@/sf-modules/compass/overrides/methods';
export const unifiedApiExtension = createUnifiedExtension({
// ...
+ methods: {
+ override: {
+ searchProducts,
+ },
+ },
normalizers: {
addCustomFields: [
+ compassCustomFields,
],
},
});
5
Configure request body parser
Configure the body parser to handle larger request payloads required by AI workflows.
+ import type bodyParserNamespace from 'body-parser';
+ const bodyParserConfig: CreateServerOptions['bodyParser'] = ({ functionName, integrationName }) => {
+ const optionsMap: Record<string, Record<string, bodyParserNamespace.OptionsJson>> = {
+ ai: {
+ invoke: {
+ limit: '40mb',
+ },
+ },
+ };
+
+ return (
+ optionsMap[integrationName]?.[functionName] || {
+ limit: '100kb',
+ }
+ );
+ };
async function runApp() {
const app = await createServer(config, {
+ bodyParser: bodyParserConfig,
});
}
What next?
With the Alokai Compass module installed in your Storefront, you're ready to build your first AI workflow!