BigCommerce Catalyst Integration Guide

Reference codebase: https://github.com/SiteVibes/catalyst

Enterprise API Key Setup

SiteVibes integration with BigCommerce Catalyst is facilitated through the SiteVibes Enterprise API.  To get started, copy the enterprise API keys to the Catalyst app .env file.  On the SiteVibes app, go to Settings > Account > API & pixel keys > API Implementation and copy the the enterprise token:

Paste the token on the Catalyst app .env file.

Set the following environment variables:

SV_API_HOST: SiteVibes api endpoint domain name and parent path.

SV_API_TOKEN: enterprise api token from SiteVibes app.

Product View Tracking

Product data can be pushed to SiteVibes as customers view product details pages using the https://api.sitevibes.com/v1/product-view endpoint.  On the storefront Catalyst codebase, under core/components/sitevibes/api, create a ts code file and implement the code that calls the SiteVibes product-view endpoint.  On the reference codebase, this example is from core/components/sitevibes/api/analytics.ts.

export async function svProductViewed(productId: number): Promise<SvResponse<any>> {
  const data = await client.fetch({
    document: ProductInfoQuery,
    variables: { productId },
  });

  const product = data.data.site.product!;

  let image_url = '';
  if (product.images?.edges?.length) {
    image_url = product.images.edges[0]?.node.urlOriginal!;
  }

  const svProductViewRq: SvProductViewRq = {
    app_id: uuid(),
    user_session_id: uuid(),
    id: product.id,
    name: product.name,
    description: product.description,
    url: SV_STOREFRONT_URL + product.path,
    image_url,
    price: product.prices?.basePrice?.value,
    price_sale: product.prices?.salePrice?.value,
    quantity: product.inventory.aggregated?.availableToSell,
  };

  const url = `https://${SV_API_HOST}/product-view`;
  const rs = await fetch(url, {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer ${SV_API_TOKEN}`,
    },
    body: JSON.stringify(svProductViewRq),
  });

  const rsData = (await rs.json()) as SvResponse<any>;

  return rsData;
}

On the product detail page code, core/app/[locale]/(default)/product/[slug]/page.tsx, invoke the svProductViewed function by passing to it the product ID.

export default async function Product(props: Props) {
  const searchParams = await props.searchParams;
  const params = await props.params;
  const currencyCode = await getPreferredCurrencyCode();

  const { locale, slug } = params;

  setRequestLocale(locale);

  const t = await getTranslations('Product');

  const productId = Number(slug);

  const optionValueIds = getOptionValueIds({ searchParams });

  const productPromise = getProductData({
    entityId: productId,
    optionValueIds,
    useDefaultOptionSelections: true,
    currencyCode,
  });

  const svRs = await svProductViewed(productId);
  if (!svRs.status) {
    console.error(svRs.message);
  }

Once product tracking is setup, open a few product detail pages on the Catalyst storefront.  Viewing the product detail pages sends product data to SiteVibes and these can be viewable on the SiteVibes main app dashboard, under Data > Products.

Example: Product Reviews Integration Steps

For product reviews, use the following enterprise API endpoints:

SiteVibes Endpoint Components

Implement the calls to the SiteVibes Enterprise API under core/components/sitevibes/api/reviews.ts.

'use server';

import {
  SvCreateProductReviewRq,
  SvProductReviewsRs,
  SvProductsSummaryRs,
  SvResponse,
} from '../types';
import { v4 as uuid } from 'uuid';

const { SV_API_HOST, SV_API_TOKEN } = process.env;

export async function svRetrieveProductReviewsSummary(
  productId: number,
): Promise<SvResponse<SvProductsSummaryRs>> {
  const app_id = uuid();
  const url = `https://${SV_API_HOST}/product-summary?app_id=${app_id}&product_id=${productId}`;
  const rs = await fetch(url, {
    method: 'get',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer ${SV_API_TOKEN}`,
    },
  });

  const rsData = (await rs.json()) as SvResponse<SvProductsSummaryRs>;

  return rsData;
}

export async function svRetrieveProductReviews(
  productId: number,
  page?: number
): Promise<SvResponse<SvProductReviewsRs>> {
  const app_id = uuid();
  let url = `https://${SV_API_HOST}/product-reviews?app_id=${app_id}&product=${productId}`;
  if (page) {
    url += `&page=${page}`
  }
  const rs = await fetch(url, {
    method: 'get',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer ${SV_API_TOKEN}`,
    },
  });

  const rsData = (await rs.json()) as SvResponse<SvProductReviewsRs>;

  return rsData;
}

export async function svCreateProductReview(
  review: SvCreateProductReviewRq,
): Promise<SvResponse<any>> {
  review.app_id = uuid();
  review.user_session_id = uuid();
  const url = `https://${SV_API_HOST}/product-reviews`;
  const rs = await fetch(url, {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer ${SV_API_TOKEN}`,
    },
    body: JSON.stringify(review),
  });

  const rsData = (await rs.json()) as SvResponse<any>;

  return rsData;
}

Create the Route for the endpoint calls

Implement the following API routes:

Loyalty Integration

To integrate loyalty features to your Catalyst site, create components that connect to the SiteVibes enterprise API and implement the routes for each endpoint.  Please see this guide for more information: https://developers.sitevibes.com/docs/comprehensive-guide-to-implementing-a-full-loyalty-program-using-sitevibes-api

API documentation: https://developers.sitevibes.com/reference/getloyaltycustomer