Fast Simon Analytics Integration for BigCommerce Catalyst

This guide outlines how to integrate Fast Simon Analytics into your Catalyst storefront. By following these steps, you'll be able to track user behavior and gain valuable insights into your shoppers' journey by leveraging Fast Simon's extended analytics capabilities alongside your existing analytics tools.

Note: The Catalyst SDK does not include pre-built UI components. Instead, it provides dependency-free APIs and utilities to fetch, transform, and report analytics data so you can integrate them with your custom components.

Core Concepts

Catalyst provides a flexible environment where you can integrate Fast Simon Analytics to capture additional context around key storefront events (e.g. product views, collection views, search interactions, and recommendations). Fast Simon’s utilities allow you to:

Capture how users navigate through your site (e.g. from search, autocomplete, or recommendations).
Enrich default events with custom data such as applied filters, sort orders, and widget positions.
Report granular data on product clicks and impressions, enabling more advanced personalization and insights.

Step-by-Step Implementation

1. Create a Fast Simon Product Tracking API Route

This API route serves as the backend endpoint for fetching and updating personalization data.

Navigate to the API Directory:
In your Catalyst project, go to core/app/api and create a new directory named fast-simon-product-tracking.

Create the Route File:
Inside the new directory, create a file named route.ts and add the following code:

import { fastSimonTrackingUtils } from '@fast-simon/storefront-sdk';
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { getFsSessionForRequest } from '~/lib/get-fast-simon';

const PersonalizationDataSchema = z.object({
  productId: z.string().optional(),
  userSession: z.number().optional(),
  sessionToken: z.string().optional(),
});

export async function GET() {
  const session = await getFsSessionForRequest();
  const data = fastSimonTrackingUtils.getViewedProducts(session);
  return NextResponse.json(data);
}

export async function POST(request: NextRequest) {
  const session = await getFsSessionForRequest();
  const data = PersonalizationDataSchema.parse(await request.json());
  const result = await fastSimonTrackingUtils.setPersonalizationData(session, data);

  const response = NextResponse.json({ success: true });
  if (result.updatedCookie) {
    response.headers.set('Set-Cookie', result.updatedCookie);
  }
  return response;
}

2. Initialize Analytics in Your Application

Set up Fast Simon Analytics in your client-side providers so that events can be captured across your Catalyst storefront.

Open the Providers File:
Navigate to core/app/providers.ts.

Import and Configure Fast Simon Analytics:
Add the following code to import the necessary modules and initialize the analytics component:

'use client';

import { PropsWithChildren } from 'react';
import { analyticsManager, FastSimonAnalytics } from '@fast-simon/sdk-react';

export function Providers({ children }: PropsWithChildren) {
  return (
    <>
      {/* Other provider components */}
      <FastSimonAnalytics
        storeId={process.env.NEXT_PUBLIC_FAST_SIMON_STORE_ID}
        uuid={process.env.NEXT_PUBLIC_FAST_SIMON_UUID}
        analyticsContextValue={analyticsManager}
        collectionPersonalization={true}
        searchPersonalization={true}
        storeDomain="Your Store Domain"
      />
      {children}
    </>
  );
}

Replace "Your Store Domain" with your actual store domain and ensure the environment variables are correctly configured.

3. Implement Fast Simon Reporting

Integrate Fast Simon Reporting in key areas of your storefront to capture detailed analytics events.

3.1. Category Page Analytics

Enhance Data Fetching:
In the category page file at core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx, add a helper function to retrieve the full Fast Simon response:
```
async function getFastSimonFullResponse(props: Props) {
  const search = await getSearch(props);
  return search.fullFastSimonResponse;
}
```

Update the Category Page Loader:
Use a Stream block to wait for category, product, and Fast Simon data simultaneously:

<Stream value={Promise.all([getCategory(props), getProducts(props), getFastSimonFullResponse(props)])}>
  {([category, products, fastSimonData]) => (
    <CategoryViewed
      category={category}
      categoryId={category.entityId}
      products={products}
      fastSimonData={fastSimonData as SmartCollectionResponse}
    />
  )}
</Stream>

Update the CategoryViewed Component:
In CategoryViewed.tsx, update the props and add an analytics event inside a useEffect:

import { useEffect } from 'react';
import { analyticsManager } from '@fast-simon/storefront-sdk';

interface Props {
  categoryId: number;
  category: Category;
  products: productSearchItem[];
  fastSimonData: SmartCollectionResponse;
}

export const CategoryViewed = ({ categoryId, category, products, fastSimonData }: Props) => {
  useEffect(() => {
    // Existing reporting logic
    bodl.navigation.categoryViewed({
      category_id: categoryId,
      category_name: category?.name ?? '',
      line_items: products.map((p) => productItemTransform(p, category)),
    });
    // Emit custom analytics event with Fast Simon data
    analyticsManager.emit('collection_viewed', { fastSimonData });
  }, [category, categoryId, products, fastSimonData]);

  return null;
};

3.2. Search Results Analytics

Create a Search Analytics Component:
In core/app/[locale]/(default)/(faceted)/search, create a file named search-viewed.tsx and add:

'use client';

import { useEffect } from 'react';
import { analyticsManager } from '@fast-simon/storefront-sdk';
import { SmartCollectionResponse } from '@fast-simon/types';

interface Props {
  fastSimonData: SmartCollectionResponse | SearchResponse;
}

export const SearchViewed = ({ fastSimonData }: Props) => {
  useEffect(() => {
    analyticsManager.emit('search_viewed', fastSimonData);
  }, [fastSimonData]);
  return null;
};

Integrate in the Search Page:
In your search page file (e.g. core/app/[locale]/(default)/(faceted)/search/page.tsx), add a Stream block to retrieve Fast Simon data and render the analytics component:

export default async function Search(props: Props) {
  return (
    <>
      {/* Render your search results components */}
      <ProductsListSection
        /* ...other props... */
      />
      <Stream value={Promise.all([getFastSimonData(props)])}>
        {([fastSimonData]) => <SearchViewed fastSimonData={fastSimonData} />}
      </Stream>
    </>
  );
}

3.3. Product Viewed Analytics

On product pages, ensure that product views are tracked with enriched data:

Update the Product Viewed Component:
In core/app/[locale]/(default)/product/[slug]/_components/product-viewed/index.tsx, add the following within a useEffect:
```
useEffect(() => {
  analyticsManager.emit('product_viewed', transformedProduct);
}, [transformedProduct]);
```

3.4. Track Product Clicks from Various Sources

From Autocomplete:
In core/vibes/soul/primitives/navigation/index.tsx, within your SearchResults function, add click callbacks:

const onAutocompleteProductClicked = useCallback(
  (productId: string) => {
    FastSimonReporting.prepareProductSeenFromAutocompleteData({ query, productId });
  },
  [query],
);

const onAutocompleteCategoryClicked = useCallback(() => {
  FastSimonReporting.prepareCollectionSeenFromAutocompleteData({ query });
}, [query]);

From SERP and Category:
In core/vibes/soul/primitives/product-card/index.tsx, add 'use client'; at the top and include the following:

const reportProductClick = () => {
  FastSimonReporting.productClicked(id);
};

Then update the Link element to include the click handler:

<Link
  aria-label={title}
  className="group flex cursor-pointer flex-col gap-2 rounded-[var(--product-card-border-radius,1rem)] ring-[var(--product-card-focus,hsl(var(--primary)))] ring-offset-4 focus-visible:outline-0 focus-visible:ring-2"
  href={href}
  id={id}
  onClick={reportProductClick}
>
  {/* Link content */}
</Link>

Create a Widget Viewed Component:
Create a new component (e.g., FastSimonWidgetViewed.tsx) with the following code:

'use client';

import { useEffect } from 'react';
import { analyticsManager } from '@fast-simon/storefront-sdk';
import { RecommendationsResponse } from '@fast-simon/types';

export const FastSimonWidgetViewed = ({
  recommendationsResponse,
}: {
  recommendationsResponse: RecommendationsResponse;
}) => {
  useEffect(() => {
    recommendationsResponse.widget_responses.forEach((widgetData) => {
      analyticsManager.emit('recommendations_products_seen', widgetData);
    });
  }, [recommendationsResponse]);

  return null;
};

Integrate in the Product Page:
In your product page file at core/app/[locale]/(default)/product/[slug]/page.tsx, update the section rendering related products. For example, replace your existing FeaturedProductsCarousel block with:

<>
  <FeaturedProductsCarousel
    cta={{ label: t('RelatedProducts.cta'), href: '/shop-all' }}
    emptyStateSubtitle={t('RelatedProducts.browseCatalog')}
    emptyStateTitle={t('RelatedProducts.noRelatedProducts')}
    nextLabel={t('RelatedProducts.nextProducts')}
    previousLabel={t('RelatedProducts.previousProducts')}
    products={getRelatedProducts(props)}
    scrollbarLabel={t('RelatedProducts.scrollbar')}
    title={t('RelatedProducts.title')}
  />
  <Stream fallback={null} value={getFastSimonRelatedResponse(props)}>
    {(response) => <FastSimonWidgetViewed recommendationsResponse={response} />}
  </Stream>
</>

Conclusion

By following this guide, you have integrated Fast Simon Analytics into your BigCommerce Catalyst storefront. This implementation enables you to capture enriched data on product views, collection interactions, search behavior, and recommendation engagement. The flexibility of Catalyst combined with Fast Simon's SDK allows you to tailor your analytics reporting for improved insights and enhanced personalization.

Feel free to adjust and extend these integrations as needed to match your storefront’s design and user experience requirements.

Fast Simon Analytics Integration for BigCommerce Catalyst

Core Concepts​

Step-by-Step Implementation​

1. Create a Fast Simon Product Tracking API Route​

2. Initialize Analytics in Your Application​

3. Implement Fast Simon Reporting​

3.1. Category Page Analytics​

3.2. Search Results Analytics​

3.3. Product Viewed Analytics​

3.4. Track Product Clicks from Various Sources​

3.5. Upsell Widget Products Viewed​

Conclusion​