Usar o Footnote numa loja Catalyst

As etiquetas do Footnote funcionam no Catalyst, a loja online da BigCommerce construída em Next.js, a partir da versão 1.4. O suporte ao Catalyst está em beta. Testámos o script das etiquetas no Catalyst 1.12 original, mas ainda não na versão própria de uma loja, por isso, se algo nesta página não corresponder ao que vê, diga-nos.

Verifique a versão do Catalyst

As etiquetas precisam do Catalyst core 1.4 ou posterior. A partir da versão 1.3, o Catalyst carrega os scripts do Script Manager através do gestor de consentimento de cookies, e a 1.4 acrescentou a colocação no head e no body de que o script do Footnote depende. A versão está em core/package.json, com o nome @bigcommerce/catalyst-core.

Uma atualização do Catalyst publicada pela BigCommerce só chega à sua loja online quando o programador a integra na vossa cópia, por isso uma loja mais antiga fica na versão antiga até alguém a atualizar.

Mantenha o gestor de consentimento no layout principal

O Catalyst carrega os scripts do Script Manager através do componente <ConsentManager> em core/app/[locale]/layout.tsx. Se for removido ou substituído, o script do Footnote nunca carrega e não aparece nenhuma etiqueta. O Footnote não consegue detetar isto a partir da BigCommerce, por isso as Definições continuam a mostrar a loja online como abrangida.

Deixe o script definido como «Essential»

O Footnote adiciona um script ao Script Manager, chamado «Footnote AI image labels», com a categoria de consentimento «Essential» (essencial). O aviso de cookies do Catalyst trata os scripts «Essential» como necessários, por isso o script carrega antes de o cliente escolher e depois de recusar os cookies. Não define cookies nem recolhe 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 deixam de ver as etiquetas. Volte a defini-la como «Essential» no Script Manager.

Mantenha as imagens de produto na CDN da BigCommerce

O Footnote encontra uma imagem etiquetada pelo endereço 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 apresenta as imagens de produto diretamente a partir desse endereço, por isso funciona sem alterações. As 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 está lá dentro.

As etiquetas desaparecem quando o endereço de uma imagem deixa de conter o caminho da BigCommerce. Isso acontece com um carregador de imagens personalizado que reescreve o endereço, com um proxy de imagens ou outro serviço de imagens à frente da CDN, ou com imagens colocadas com o Makeswift.

Autorize o Footnote numa Content Security Policy personalizada

O Catalyst original não restringe a origem dos scripts. Se o programador tiver acrescentado regras script-src ou connect-src, autorize https://footnote.pouchapps.com em ambas. O script das etiquetas é carregado a partir daí e vai lá buscar as definições das suas etiquetas.

Conte com até uma hora para as alterações

O Catalyst guarda em cache a lista de scripts do Script Manager durante até uma hora. Depois de instalar o Footnote, ou de alterar alguma coisa nas etiquetas, a loja online pode demorar esse tempo a atualizar-se. No Stencil, as mesmas alterações aparecem em cerca de um minuto.

Um programador pode fazer as alterações aparecer mais cedo de duas formas:

Voltar a implementar a loja online. Uma nova implementação vai buscar outra vez a lista de scripts. É a solução mais simples depois de instalar o Footnote.
Reduzir DEFAULT_REVALIDATE_TARGET. O valor está em segundos e, por predefinição, é 3600. Controla durante quanto tempo o Catalyst guarda em cache a maior parte dos dados da BigCommerce, não só os scripts, por isso um número mais baixo significa mais pedidos à BigCommerce. Reduza-o para testes, em vez de o deixar baixo.

Verifique se as etiquetas aparecem

No Footnote, abra as Definições e confirme que a sua loja Catalyst aparece como abrangida. O Essentials abrange apenas a sua loja online predefinida. O Pro abrange todas as lojas online.
Marque uma imagem como Gerada por IA e ative Mostrar etiquetas nas Definições.
Aguarde até uma hora, ou peça ao programador que volte a implementar a loja.
Abra essa página de produto numa janela privada do navegador. Se aparecer um aviso de cookies, recuse. A etiqueta deve estar no canto que escolheu no separador Distintivo. No Catalyst, aparece um instante depois da página, quando a página acaba de carregar os scripts.

Para verificar a partir do navegador, abra a consola de programador em qualquer página da loja online e execute document.documentElement.dataset.footnote. Se devolver "1", o script do Footnote está a ser executado nessa loja.

Resolva uma etiqueta em falta

Se a verificação na consola não devolver "1", a loja online não está a executar o script do Footnote. Verifique estes pontos por ordem:

Aguarde que passe a hora, ou volte a implementar a loja.
As Definições mostram a loja online como abrangida.
O Catalyst core está na versão 1.4 ou posterior.
O <ConsentManager> continua em core/app/[locale]/layout.tsx.
O script está definido como «Essential» no Script Manager.
Qualquer Content Security Policy personalizada autoriza https://footnote.pouchapps.com.

Se devolver "1" mas a imagem não tiver etiqueta, o script está a ser executado e não reconheceu a imagem:

Confirme que 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 confirme que contém /products/ seguido de dois números. Se não contiver, a imagem não vem da CDN da BigCommerce num formato que o Footnote reconheça.
No separador Distintivo, confirme que a opção Resultados de categoria e de pesquisa está ativada. As páginas do Catalyst não têm nenhuma marca que indique ao Footnote que se trata de uma página de produto, por isso essa opção também abrange as páginas de produto do Catalyst.

Se o problema continuar, envie um email para footnote@pouchapps.com com o endereço da loja online, uma página de produto que devia mostrar uma etiqueta, a versão do Catalyst e o resultado da verificação na consola. A página de suporte lista os motivos por que uma etiqueta pode faltar em qualquer loja online.