@fast-simon/storefront-kit

@fast-simon/storefront-kit is a versatile library for e-commerce platforms, providing easy integration of Fast Simon features like Visual Similarity and other complex functionalities into your online stores. Written in TSX, it offers a suite of fetcher functions for pulling data from Fast Simon servers and components for rendering, streamlining the integration process.

Features

• Visual similarity: Enhance product discovery by showing visually similar products.
• Customizable components: Tailored to fit the design and functionality of your store.
• Flexible fetcher functions: Retrieve data effectively with minimal setup.
• Easy integration with Shopify, especially designed for use with Shopify Hydrogen.

Installation

Install the package in your project:

npm install @fast-simon/storefront-kit

Usage

Adding Fast Simon fetcher function to the root loader

• import getVisualSimilarityProducts from @fast-simon/storefront-kit into the product page root file
• Invoke getVisualSimilarityProducts in your root loader function, passing the product id as a prop
• Pass down the result to the product page component, you can either await to the promise to resolved (which could have a negative performance impact) or just pass the promise down as a stream.

import {getVisualSimilarityProducts} from '@fast-simon/storefront-kit';

export async function loader({params, request, context}: LoaderFunctionArgs) {
  // ... other code
  const visualSimilarityProducts = getVisualSimilarityProducts({
    UUID: 'Your store UUID here, you can find it in the Fast Simon dashboard',
    productId: product.id,
    storeId: 'Your store ID here, you can find it in the Fast Simon dashboard',
  });
  return defer({otherparam, visualSimilarityProducts});

Using Fast Simon components

After fetching data using the getVisualSimilarityProducts function, you can display the results using components from the @fast-simon/storefront-kit. Here's an example of how to use the FastSimonWidget component along with retrieving the data using the useLoaderData:

import { FastSimonWidget } from '@fast-simon/storefront-kit';

function ProductPage() {

  const {product, visualSimilarityProducts} = useLoaderData<typeof loader>();

  // ... other component logic

  return (
          <div>

            {/* ... other parts of your product page */}

            <FastSimonWidget title={'Similar Products'}
                             products={visualSimilarityProducts}/>

          </div>
  );
}

This component will render the visual similarity results in a visually appealing and interactive format.

Configuration

getVisualSimilarityProducts function

To customize the behavior of the getVisualSimilarityProducts function, you can pass the specs parameter to control aspects like:

• maxSuggestions - Max number of similar products to fetch
• sources - sources of the results, for example:
  • similar_products - products sharing category, tags or keyword similarity with the viewed product
  • similar_products_by_attributes - products sharing categories and chosen attributes (requires choosing relevant attributes in Fast Simon dashboard)
  • similar_products_lookalike - visually similar products (requires enabling Look-a-like Visually Similar Recommendations in Fast Simon dashboard)
  • related_top_products - popular products in the store

Refer to the API documentation for a full list of configurable parameters. https://docs.fastsimon.com/api#operation/productRecommendations

FastSimonWidget component

You can customize the FastSimonWidget component with various props to match your store's design and layout requirements.

renderProduct - a function that receives a product object and returns a React element. This allows you to customize the product card that is rendered for each product in the widget. For example:

  <FastSimonWidget title={'Similar Products'}
                   products={visualSimilarityProducts}
                   renderProduct={(product, pos) => <MyProductCard key={product.id} product={product} />}/>

title - The title of the widget, for example Similar Products or You may also like breakpoints - An object of breakpoints to control the number of products displayed in each device. For example:

  <FastSimonWidget title={'Similar Products'}
                   products={visualSimilarityProducts}
                   breakpoints={{
                     mobile: 2,
                     tablet: 3,
                     desktop: 4,
                   }}/>

carouselGap - The gap between products in the carousel in pixel, default value is 16. For example:

  <FastSimonWidget title={'Similar Products'}
                   products={visualSimilarityProducts}
                   carouselGap={16}/>

RightArrowIcon - A JSX element to use as the right arrow icon in the carousel. For example:

  <FastSimonWidget title={'Similar Products'}
                   products={visualSimilarityProducts}
                   RightArrowIcon={<MyRightArrowIcon/>}/>

Don't worry about the left icon, we are rotating the icon automatically.

imageAspectRatio - The aspect ratio of the product image, default value is "2/3". For example:

  <FastSimonWidget title={'Similar Products'}
                   products={visualSimilarityProducts}
                   imageAspectRatio={"2/3"}/>

Consult the component documentation for more details on customization options.

For any issues, questions, or suggestions, please refer to the GitHub repository of @fast-simon/storefront-kit or contact our support team.