Pular para o conteúdo

Guia de configuração Beta

Como usar o Footnote em uma vitrine Catalyst

Última atualização

Os rótulos do Footnote funcionam no Catalyst, a vitrine da BigCommerce feita em Next.js, a partir da versão 1.4. O suporte ao Catalyst está em beta. Testamos o script dos rótulos no Catalyst 1.12 original, mas ainda não na versão personalizada de uma loja, então, se algo nesta página não bater com o que você vê, avise a gente.

Confira a versão do Catalyst

Os rótulos exigem o Catalyst core 1.4 ou mais recente. Desde a versão 1.3, o Catalyst carrega os scripts do Script Manager pelo gerenciador de consentimento de cookies, e a 1.4 trouxe a inserção no head e no body de que o script do Footnote depende. A versão fica em core/package.json, com o nome @bigcommerce/catalyst-core.

Uma atualização do Catalyst lançada pela BigCommerce só chega à sua vitrine quando o desenvolvedor faz o merge dela na cópia de vocês, então uma vitrine mais antiga continua na versão antiga até alguém atualizar.

Mantenha o gerenciador de consentimento no layout raiz

O Catalyst carrega os scripts do Script Manager pelo componente <ConsentManager> em core/app/[locale]/layout.tsx. Se ele for removido ou substituído, o script do Footnote nunca carrega e nenhum rótulo aparece. O Footnote não consegue enxergar isso pela BigCommerce, então Configurações continua mostrando a vitrine como coberta.

Deixe o script como “Essential”

O Footnote adiciona um script ao Script Manager, chamado “Footnote AI image labels”, com a categoria de consentimento “Essential” (essencial). O banner de cookies do Catalyst trata scripts “Essential” como necessários, então o script carrega antes de o cliente escolher e também depois que ele recusa os cookies. O script não grava cookies e não coleta nada sobre os clientes.

Se alguém mudar a categoria para “Functional”, “Analytics” ou “Targeting” (funcional, análise ou segmentação), os clientes que recusam cookies param de ver os rótulos. Volte a categoria para “Essential” no Script Manager.

Mantenha as imagens de produto na CDN da BigCommerce

O Footnote encontra uma imagem rotulada pelo endereço dela na CDN da BigCommerce, que contém os números do produto e da imagem, por exemplo cdn11.bigcommerce.com/s-abc123/images/stencil/384w/products/157/551/. O Catalyst original renderiza as imagens de produto direto desse endereço, então funciona sem nenhuma mudança. Imagens que passam pela otimização de imagens do Next.js (/_next/image?url=...) também funcionam, porque o Footnote lê o endereço original que vem dentro delas.

Os rótulos somem quando o endereço de uma imagem deixa de conter o caminho da BigCommerce. Isso acontece com um loader de imagens personalizado que reescreve o endereço, com um proxy ou outro serviço de imagens na frente da CDN, ou com imagens inseridas pelo Makeswift.

Libere o Footnote em uma Content Security Policy personalizada

O Catalyst original não restringe de onde os scripts são carregados. Se o desenvolvedor adicionou regras script-src ou connect-src, libere https://footnote.pouchapps.com nas duas. O script dos rótulos é carregado desse endereço e busca as configurações dos seus rótulos nele.

Espere até uma hora pelas alterações

O Catalyst mantém em cache a lista de scripts do Script Manager por até uma hora. Depois que você instala o Footnote, ou muda qualquer coisa nos rótulos, a vitrine pode levar esse tempo para se atualizar. No Stencil, as mesmas alterações aparecem em cerca de um minuto.

O desenvolvedor pode fazer as alterações aparecerem antes de duas formas:

  • Fazer um novo deploy da vitrine. Um deploy novo busca a lista de scripts de novo. É a solução mais simples depois de instalar o Footnote.
  • Diminuir DEFAULT_REVALIDATE_TARGET. O valor é em segundos e o padrão é 3600. Ele controla por quanto tempo o Catalyst mantém em cache a maior parte dos dados da BigCommerce, não só os scripts, então um número menor significa mais requisições à BigCommerce. Diminua para testar, mas não deixe o valor baixo.

Confira se os rótulos aparecem

  1. No Footnote, abra Configurações e confira se a sua vitrine Catalyst aparece como coberta. O Essentials cobre só a sua vitrine padrão. O Pro cobre todas as vitrines.
  2. Marque uma imagem como Gerada por IA e ative Exibir rótulos em Configurações.
  3. Espere até uma hora, ou peça ao desenvolvedor um novo deploy.
  4. Abra essa página de produto em uma janela anônima do navegador. Se aparecer um banner de cookies, recuse. O rótulo deve ficar no canto que você escolheu na aba Selo. No Catalyst, ele aparece um instante depois da página, quando a página termina de carregar os scripts.

Para conferir pelo navegador, abra o console do desenvolvedor em qualquer página da vitrine e rode document.documentElement.dataset.footnote. Se o resultado for "1", o script do Footnote está rodando ali.

Resolva um rótulo que não aparece

Se a verificação no console não retornar "1", a vitrine não está rodando o script do Footnote. Confira estes itens na ordem:

  1. Espere a hora passar, ou faça um novo deploy.
  2. Configurações mostra a vitrine como coberta.
  3. O Catalyst core está na versão 1.4 ou mais recente.
  4. O <ConsentManager> continua em core/app/[locale]/layout.tsx.
  5. O script está como “Essential” no Script Manager.
  6. Toda Content Security Policy personalizada libera https://footnote.pouchapps.com.

Se retornar "1", mas a imagem estiver sem rótulo, o script está rodando e não reconheceu a imagem:

  • Confira se a imagem está marcada como Gerada por IA ou Editada com IA no Footnote.
  • Clique com o botão direito na imagem, copie o endereço e confira se ele contém /products/ seguido de dois números. Se não contiver, a imagem não vem da CDN da BigCommerce em um formato que o Footnote consiga reconhecer.
  • Na aba Selo, confira se a opção Resultados de categoria e de busca está ativada. As páginas do Catalyst não têm nenhuma marcação que diga ao Footnote que aquela é uma página de produto, então essa opção cobre também as páginas de produto do Catalyst.

Se o problema continuar, mande um e-mail para footnote@pouchapps.com com o endereço da sua vitrine, uma página de produto que deveria mostrar um rótulo, a versão do Catalyst e o resultado da verificação no console. A página de suporte lista os motivos pelos quais um rótulo pode sumir em qualquer vitrine.