Skip to content

Setup guide Beta

Use Footnote on a Catalyst storefront

Last updated

Footnote labels work on Catalyst, the BigCommerce storefront built on Next.js, from version 1.4. Catalyst support is in beta. We have tested the label script on stock Catalyst 1.12, but not yet on a store’s own Catalyst build, so if something on this page does not match what you see, tell us.

Check your Catalyst version

Labels need Catalyst core 1.4 or later. Catalyst loads Script Manager scripts through its cookie consent manager from version 1.3, and 1.4 added the head and body placement Footnote’s script relies on. The version is in core/package.json, under the name @bigcommerce/catalyst-core.

A Catalyst update from BigCommerce only reaches your storefront when your developer merges it into your copy, so an older storefront stays on its old version until someone updates it.

Catalyst loads Script Manager scripts through the <ConsentManager> component in core/app/[locale]/layout.tsx. If it is removed or replaced, Footnote’s script never loads and no labels show. Footnote cannot see this from BigCommerce, so Settings still shows the storefront as covered.

Leave the script set to Essential

Footnote adds one script to Script Manager, called Footnote AI image labels, with the consent category Essential. Catalyst’s cookie banner treats Essential scripts as necessary, so the script loads before a shopper chooses and after they decline cookies. It sets no cookies and collects nothing about shoppers.

If someone changes the category to Functional, Analytics or Targeting, shoppers who decline cookies stop seeing labels. Set it back to Essential in Script Manager.

Keep product images on the BigCommerce CDN

Footnote finds a labelled image by its BigCommerce CDN address, which contains the product and image numbers, for example cdn11.bigcommerce.com/s-abc123/images/stencil/384w/products/157/551/. Stock Catalyst renders product images straight from that address, so this works with no changes. Images passed through Next.js image optimisation (/_next/image?url=...) also work, because Footnote reads the original address inside them.

Labels go missing when an image address no longer contains the BigCommerce path. That happens with a custom image loader that rewrites the address, an image proxy or another image service in front of the CDN, or images placed with Makeswift.

Allow Footnote in a custom Content Security Policy

Stock Catalyst does not restrict where scripts load from. If your developer has added script-src or connect-src rules, allow https://footnote.pouchapps.com in both. The label script loads from there and fetches your label settings from there.

Allow up to an hour for changes

Catalyst caches the list of Script Manager scripts for up to an hour. After you install Footnote, or change anything about your labels, the storefront can take that long to catch up. On Stencil the same changes show within about a minute.

A developer can make changes show sooner in two ways:

  • Redeploy the storefront. A fresh deploy fetches the script list again. This is the simplest fix after installing Footnote.
  • Lower DEFAULT_REVALIDATE_TARGET. The setting is in seconds and defaults to 3600. It controls how long Catalyst caches most of its BigCommerce data, not only scripts, so a lower number means more requests to BigCommerce. Lower it for testing rather than leaving it low.

Check that labels show

  1. In Footnote, open Settings and check that your Catalyst storefront is listed as covered. Essentials covers your default storefront only. Pro covers every storefront.
  2. Mark one image as AI-generated, and switch on Show labels in Settings.
  3. Wait up to an hour, or ask your developer to redeploy.
  4. Open that product page in a private browser window. If a cookie banner appears, decline. The label should sit in the corner you chose on the Badge tab. On Catalyst it appears a moment after the page, once the page has finished loading its scripts.

To check from the browser, open the developer console on any page of the storefront and run document.documentElement.dataset.footnote. If it returns "1", Footnote’s script is running there.

Fix a missing label

If the console check does not return "1", the storefront is not running Footnote’s script. Check these in order:

  1. Wait for the hour to pass, or redeploy.
  2. Settings lists the storefront as covered.
  3. Catalyst core is version 1.4 or later.
  4. <ConsentManager> is still in core/app/[locale]/layout.tsx.
  5. The script is set to Essential in Script Manager.
  6. Any custom Content Security Policy allows https://footnote.pouchapps.com.

If it returns "1" but the image has no label, the script is running and has not matched the image:

  • Check the image is marked AI-generated or AI-edited in Footnote.
  • Right-click the image, copy its address, and check it contains /products/ followed by two numbers. If it does not, the image is not coming from the BigCommerce CDN in a form Footnote can match.
  • On the Badge tab, check Category and search results is switched on. Catalyst pages carry no marker that tells Footnote a page is a product page, so that switch covers Catalyst product pages too.

If you are still stuck, email footnote@pouchapps.com with your storefront’s address, a product page that should show a label, your Catalyst version and the result of the console check. The support page lists the reasons a label can go missing on any storefront.