Guides

BigCommerce Install Instructions: Custom Frontend Widgets/Theme

Suggest Edits

Congratulations on installing Spresso!

You’re almost ready to get started! Now that you’ve installed Spresso’s BigCommerce App, you have to make only a few small tweaks to your theme to ensure our AI-generated pricing is displayed on your site.

At a high level - you will be replacing the static prices from your BigCommerce catalog with placeholders that help Spresso’s technology determine the right price for each item. NOTE: Spresso will not work without these changes.

If you have any questions or concerns about this process, don’t hesitate to reach out to us at [email protected] - our team of BigCommerce experts will gladly assist you with any issues you may have.

If you have a Cornerstone theme without JavaScript customization please follow section I. Cornerstone to ensure Spresso’s prices are displayed throughout your system. If you have customized the default Cornerstone JavaScript please see section II.

II. Custom Frontend Widgets/Theme

If you have custom widgets where pricing is displayed, you have to REMOVE the actual prices from those widgets and have them return an empty HTML element with markers telling Spresso what to do. Our system monitors your HTML (using a MutationObserver), finds those markers whenever they appear and populates the empty element with the AI-generated price from Spresso’s servers. We do this with minimum additional latency (our P90 is 7.5ms) and also prefetch data intelligently to ensure the user experience on your website is pristine.

NOTE: These instructions are designed for someone with prior experience with JS, especially async / await operations. Please reach out to [email protected] if you have any technical questions.

1. Initialize the SDK:

In app.js, initialize the Spresso SDK, setting the customTheme flag. When this flag is set, our system will still inject Spresso prices into your DOM, but WILL not handle adding items to the cart - this must now be done by your code.

window.Spresso.initialize({ customTheme: true });

2. Inform Spresso whenever an item is added to cart:

Anywhere you have an CTA allowing a user to add a variant to their cart, you must inform the Spresso SDK. Our SDK will ensure that the price of each item in the cart matches exactly the price that was displayed to the user while they were browsing. It is important to notify us in each CTA so that Spresso can maintain consistent pricing across your system.

TIP: If you use BigCommerce’s stencil-utils you need to find every usage of api.cart.itemAdd in your code and modify it.

// cartData is the same shape as the input data used for stencil's itemAdd call
const cartData = new FormData(event.target);
cartData.set('action', 'add');
cartData.set('product_id',<productId>);
cartData.set('variant_id',<variantId>);
cartData.set('qty[]', <quantity>);


/* NOTE - you MUST await this API call
 * It makes a request to BigCommerce to ensure the price of the item in the cart matches the display price
 */
await window.SpressoCartSdk.handleAddToCart({
  cartId: response.data.cart_id,
  cartItemId: response.data.cart_item.id,
  variantSku: <sku>,
  cartData,
});

3. Inform Spresso whenever a cart item is updated to a different variant

As above, anywhere you have an CTA allowing a user to switch product variants in their cart, you must inform Spresso. We will ensure the changed variant has the correct price just as we did when originally adding items to the cart.

// cartData is the same shape as the input data used for stencil's itemAdd call
const cartData = new FormData(event.target);
cartData.set('action', 'add');
cartData.set('product_id',<productId>);
cartData.set('variant_id',<variantId>);
cartData.set('qty[]', <quantity>);

await window.SpressoCartSdk.handleCartVariantChange({
  cartId: response.data.cart_id,
  cartItemId: response.data.cart_item.id,
  variantSku: <sku>,
  cartData,
});

4. Switch your HTML to be Spresso-compatible

Original HTML:
<span class="price-display">{price}</span>

Spresso-compatible HTML
<span
class="price-display"
data-spresso-item-id=”SKU-123”
data-spresso-id-type=”ProductSku”
data-spresso-pricing-display=”range”
data-spresso-fallback-id=”987123”
>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span>

NOTE: The reason we use multiple spaces (  ) above is to ensure that when the price is injected by Spresso’s system, the DOM element retains its width and does not get resized.

Description of DOM markers:
data-spresso-item-id: The identifier Spresso uses to determine which item’s price to inject. Variant SKU and Product SKU are typically used, but contact us if you prefer to use some other primary key in your system.

data-spresso-id-type: The type of the identifier provided, available options are VariantSku (default), ProductSku, VariantId (the variant primary key in your system), ProductId (the product primary key in your system).

data-spresso-pricing-display: If the identifier type above is ProductSku or ProductId, the display attribute must be provided. This allows Spresso to determine how to display pricing for the product. The available options are min, max and range. Min will display the price of the lowest-cost variant of this product, Max displays the price of the highest-cost variant and range displays both min and max prices, separated by “ - ”

data-spresso-fallback-id: The primary key for this item in BigCommerce. This is used in scenarios where a price from Spresso’s API is unavailable for any reason. Since you are removing all prices from your HTML, if Spresso’s API cannot return a price for this item, we use the fallback identifier to fetch the catalog price via your BigCommerce’s API and display that instead.

data-spresso-price-context: Indicates to the Spresso AI system the part of your site on which the price is being displayed. Available options are gallery (default) and pdp. Any location where the product is displayed as part of a list, i.e. ad-hoc carousel, personalized gallery etc should all use gallery or not add this attribute, pdp should be used only for the main item on a PDP page.

Updated 8 months ago