PWA Kit demo and starter code

​

Integration with PWA Kit

​

Before you begin

• Algolia Search & Discovery cartridge version 25.3.0 or later.
• Salesforce’s storefrontdata sample data. The storefrontdata repository requires authenticated access.
• The default Variation product record model.
• Node.js version 18 or later.
• npm 9 or later.
• If you intend to use Recommend components that require a trained model, train the corresponding model.

​

Installation

​

Run the Algolia demo application

1. Set up API access to your Salesforce B2C Commerce instance.
2. In Salesforce Business Manager, go to Merchant Tools > Algolia > Algolia. In Additional Product Attributes, enter color, size, colorVariations, masterID, lsImage, short_description, long_description, pricebooks, brand, name, and in_stock. These attributes determine which additional product fields the cartridge sends to Algolia. For more information, see Custom preferences. If you’re using other datasets or a custom indexing approach, adjust the attribute list for your implementation.
3. Index your products and content from your Salesforce B2C Commerce instance into Algolia.
4. Configure your indices in the Algolia dashboard:
   • Create a Query Suggestions index.
   • Configure facets for categories, brands, colors, and sizes for the primary product .
   • Create replicas for sorting options.
   • Create a rule for the primary product index to enable the rendering of product previews in the autocomplete section.
5. Import the following rule configuration using Enhanced > Rules > Import/Export.
   JSON

   {
     "conditions": [
       {
         "anchoring": "is",
         "pattern": "",
         "alternatives": false,
         "context": "quickAccess"
       }
     ],
     "consequence": {
       "userData": {
         "items": [
           {
             "href": "/category/womens-outfits",
             "image": "https://res.cloudinary.com/hilnmyskv/image/upload/v1645453369/sales_banner_y1hsr8.jpg",
             "subtitle": "Women",
             "template": "sales-banner",
             "title": "Outfits"
           },
           {
             "date": "Till March 25th",
             "href": "/category/womens",
             "image": "https://res.cloudinary.com/hilnmyskv/image/upload/v1645453422/sales_code_vuatep.jpg",
             "subtitle": "with the code CODE_ALGOLIA",
             "template": "sales-code",
             "title": "Sale on Women Top"
           },
           {
             "href": "/category/top-seller",
             "image": "https://res.cloudinary.com/hilnmyskv/image/upload/v1645453466/new_collection_nloeb6.jpg",
             "subtitle": "spring / summer 2024",
             "template": "new-collection",
             "title": "Top sellers"
           },
           {
             "href": "/category/womens-jewelry",
             "links": [
               {
                 "href": "/category/womens-jewelry",
                 "text": "Track my order"
               },
               {
                 "href": "/category/womens-jewelry",
                 "text": "Delivery & Returns"
               },
               {
                 "href": "/category/womens-jewelry",
                 "text": "FAQ"
               }
             ],
             "template": "help",
             "title": "how can we help?"
           }
         ]
       },
       "filterPromotes": true
     },
     "enabled": true,
     "description": "Autocomplete quick access on empty query state"
   }
   

   See all 60 lines
6. Clone the Algolia PWA Kit demo repository from GitHub and go to the cloned repository:
   Command line

   git clone https://github.com/algolia/algolia-pwa-demo.git
   
   Command line

   cd algolia-pwa-demo
   
7. Install the dependencies:
   Command line

   npm install
   
8. Copy the example file to config/algolia-config.json. Update the Algolia credentials and index names.
9. Copy the example file to config/commerce-api-config.json. Update the Salesforce B2C Commerce API credentials.
10. Set the PWA_KIT_SLAS_CLIENT_SECRET in your environment variables. To learn more about creating Shopper Login and API Access Service (SLAS) credentials, see Build Your Site in the PWA Kit documentation.
11. Start the development server:
    Command line

    npm run start
    

​

Integrate Algolia into your existing PWA Kit project

1. Index your products using the Algolia indexing jobs in Salesforce B2C Commerce.
2. Create an algolia-config.json file in your root folder or use and rename the example file.
3. Adjust your Commerce API and PWA Kit configuration as needed. For more information, see Configuration files.
4. Install the necessary dependencies to use Algolia styles in your PWA application:
   Command line

   npm install autoprefixer css-loader postcss-loader style-loader --save-dev
   
   Copy the babel.config.js and postcss.config.js files from the demo repository to your project’s root directory.
5. Copy the overrides/app/components/algolia directory from the demo repository to your project.
6. Update your overrides/app/routes.jsx file to include the Algolia product list and detail pages:
   JavaScript

   const ProductList = loadable(() => import("./pages/algolia-product-list"), {
     fallback,
   });
   
   const ProductDetail = loadable(() => import("./pages/algolia-product-detail"), {
     fallback,
   });
   
   const routes = [
     // ...
     {
       path: "/search",
       component: ProductList,
     },
     {
       path: "/category/:categoryId",
       component: ProductList,
     },
     {
       path: "/product/:productId",
       component: ProductDetail,
     },
     // ...
   ];
   

   See all 24 lines
   If you don’t need recommendation widgets on product detail pages, omit the ProductDetail route override.

​

algolia-config.json file

algolia: {
  appId: 'ALGOLIA_APPLICATION_ID',
  apiKey: 'ALGOLIA_SEARCH_API_KEY',
  indices: {
    querySuggestions: 'pwa__products__en_GB_query_suggestions',
    contents: 'pwa__contents__en_GB',
    faq: 'pwa__contents__en_GB',
    categories: 'pwa__categories__en_GB',
    primary: {
      label: 'Sort By: Best Matches',
      value: 'pwa__products__en_GB'
    },
    replicas: [
      {
        label: 'Sort By: Price Low to High',
        value: 'pwa__products__en_GB_price_asc'
      },
      {
        label: 'Sort By: Price High to Low',
        value: 'pwa__products__en_GB_price_desc'
      }
    ]
  }
},

• appId: your Algolia application ID, which you can find in the Algolia dashboard
• apiKey: your Algolia API key, which you can find in the Algolia dashboard
• indices.querySuggestions: the Query Suggestions index name
• indices.primary.label: the label for the default sorting option
• indices.primary.value: the primary product index name
• indices.replicas: a sorting options array and their corresponding index names
• indices.contents: the content index name
• indices.faq: the index containing FAQ records. The demo uses the content index. To search a separate FAQ index, update this value.
• indices.categories: the categories index name

​

InstantSearch implementation

• react-instantsearch
• algoliasearch

• Search results
• Category listings
• Filters for category, color, size, price, and brand
• Pagination
• Sorting by relevance or price
• Content search in a separate tab
• Color swatches on product listings

const filterEls = (
  <>
    <Accordion allowMultiple>
      <AlgoliaHierarchicalRefinements
        attributes={hierarchicalCategoryAttributes}
        title="Category"
      />
      <AlgoliaColorRefinements attribute="color" title="Color" />
      <AlgoliaCheckboxRefinements attribute="size" title="Size" />
      <AlgoliaRangeRefinements attribute="price.USD" title="Price" />
      <AlgoliaCheckboxRefinements attribute="collection" title="Collections" />
    </Accordion>
  </>
);

const filterEls = (
  <>
    <Accordion allowMultiple>
      <AlgoliaHierarchicalRefinements
        attributes={hierarchicalCategoryAttributes}
        title="Category"
      />
      <AlgoliaColorRefinements attribute="color" title="Color" />
      <AlgoliaCheckboxRefinements attribute="size" title="Size" />
      <AlgoliaRangeRefinements attribute="price.USD" title="Price" />
      <AlgoliaCheckboxRefinements attribute="brand" title="Brand" />
      <AlgoliaCheckboxRefinements attribute="material" title="Material" />
    </Accordion>
  </>
);

• For implementation details, see the product listing page and its partial components.
• For library documentation, see React InstantSearch.

​

Autocomplete implementation

​

recentSearchesPlugin

​

querySuggestionsPlugin

​

categoriesPlugin

​

brandsPlugin

​

faqPlugin

​

popularPlugin

​

popularCategoriesPlugin

​

productPlugin

​

Customization and extensibility

​

Recommend implementation

• Frequently bought together: displays products frequently bought with the current product
• Looking similar: shows products that look like the current product
• Related products: displays products with similar attributes as the current product
• Trending items: displays trending items, based on a specific facet name and facet values
• Trending facets: shows trending facet values for a facet name

• Frequently bought together:
  JavaScript

  <FrequentlyBoughtTogether product={currentProduct} />;
  
• Looking similar:
  JavaScript

  <LookingSimilar product={currentProduct} />;
  
• RelatedProducts:
  JavaScript

  <RelatedProducts product={currentProduct} />;
  
• TrendingItems:
  JavaScript

  <TrendingItems facetName="brand" facetValue="Example Brand" />;
  
• TrendingFacets:
  JavaScript

  <TrendingFacets facetName="category" />;
  

• product represents the current product object for displaying recommendations. It matches the context-object in Einstein Recommendation isslots.
• facetName and facetValue specify the facet name and value for fetching trending items.

• recommendClient to specify the Algolia Recommend client
• indexName to specify the index to fetch recommendations from
• headerComponent and itemComponent for rendering custom headers and items.

1. Import the desired Recommend component from the overrides/app/components/algolia/recommend directory.
2. Configure the necessary props, such as the current product, click event handlers, and any extra customization options.
3. Place the Recommend component in the appropriate location within your product detail page or any other relevant page.

​

Next steps

• Integrate conversion events
• Customize the image logic in popularCategoriesPlugin.tsx
• Add localization and multi-site support
• Adjust the FAQ plugin configuration to use a specific index

​

Common issues