DataFirefly FAQ IA de Produto para WooCommerce: documentação

O DataFirefly FAQ IA de Produto gera automaticamente FAQ contextuais para as suas fichas de produto WooCommerce com o OpenAI ou o Anthropic Claude, e injeta os rich snippets Schema.org FAQPage na etiqueta head para os resultados enriquecidos da Google. Este guia cobre a instalação, a configuração completa e a utilização diária.

Requisitos

• WordPress 6.0 ou superior (testado até à 6.6)
• WooCommerce 7.0 ou superior (testado até à 9.4), compatível com HPOS
• PHP 7.4 a 8.3
• Uma chave de API da OpenAI (platform.openai.com/api-keys) ou da Anthropic (console.anthropic.com)
• Facultativo: Polylang ou WPML para o multilingue

Instalação

1. Descarregue o ficheiro dffaqai-1.0.0.zip a partir da sua conta DataFirefly.
2. Na administração do WordPress: Plugins → Adicionar → Carregar plugin, selecione o ZIP e clique em Instalar agora.
3. Clique em Ativar. O plugin cria a sua tabela de armazenamento das FAQ e as definições predefinidas.

Configuração do fornecedor de IA

Vá a FAQ IA → Definições → separador Fornecedor.

Escolher OpenAI ou Anthropic Claude

• OpenAI: cole a sua chave de API e escolha um modelo: gpt-4o-mini (o mais económico, recomendado), gpt-4o, gpt-4-turbo ou gpt-3.5-turbo.
• Anthropic Claude: cole a sua chave de API e escolha: claude-haiku-4-5 (económico, recomendado), claude-sonnet-4-6 ou claude-opus-4-7.

O plugin encaminha automaticamente para a API certa consoante o fornecedor selecionado. Pode alternar a qualquer momento: as FAQ já geradas são conservadas.

Parâmetros de geração

• Número de perguntas por produto: 1 a 15 (5 por predefinição).
• Temperatura: 0 (determinista) a 2 (muito criativo). 0,7 por predefinição.
• Max tokens: comprimento máximo da resposta da IA. 2000 por predefinição.

Separador Prompt: personalizar o conteúdo gerado

Tom de voz

Seis estilos pré-configurados: profissional, amigável, descontraído, técnico, entusiasta, tranquilizador. O tom muda a formulação das respostas sem programar nada.

Público-alvo

Texto livre, por exemplo «profissionais de saúde (B2B)», «primeiros compradores» ou «entusiastas de bricolagem». A IA adapta o vocabulário, as referências e o nível de detalhe.

Prompt de sistema personalizado

Deixe vazio para usar o prompt predefinido, construído a partir do tom e do público. Se o preencher, substitui por completo as instruções predefinidas, o que é útil para lojas com uma linha editorial estrita.

Diretrizes adicionais

Instruções acrescentadas a cada prompt, por exemplo «mencionar sempre a garantia de 2 anos», «evitar superlativos», «não comparar com a concorrência».

Contexto de produto a incluir

Três caixas de seleção enriquecem o contexto enviado à IA: categoria principal, marca (taxonomias product_brand, pwb-brand e yith_product_brand detetadas automaticamente) e atributos do WooCommerce. Nos produtos técnicos, a inclusão dos atributos melhora nitidamente a pertinência das perguntas.

Separador Apresentação e SEO

Posição de apresentação

Cinco hooks do WooCommerce à escolha:

• woocommerce_after_single_product_summary: por baixo dos separadores (predefinido)
• woocommerce_single_product_summary: dentro do resumo do produto
• woocommerce_product_meta_end: no fim das metas do produto
• woocommerce_after_single_product: depois de toda a zona do produto
• woocommerce_before_single_product: antes de toda a zona do produto

A prioridade do hook (15 por predefinição) é configurável para gerir a coexistência com outros plugins.

Modo de apresentação

Acordeão (primeira pergunta aberta, navegação por teclado conforme a ARIA) ou todas as respostas abertas.

Rich snippets FAQPage

Quando a opção está ativa, o plugin injeta o JSON-LD Schema.org FAQPage na etiqueta head de cada ficha de produto que tenha pelo menos uma FAQ ativa. A codificação usa JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS e JSON_HEX_QUOT e passa o Rich Results Test da Google.

Título da FAQ por idioma

Um campo de título por idioma ativo no site, com valores predefinidos fornecidos em FR, EN, ES, DE, IT, PT e NL.

Categorias excluídas

Lista de identificadores de categorias do WooCommerce separados por vírgulas. Os produtos dessas categorias são ignorados na geração em massa e na geração automática (produtos virtuais, vales de oferta, etc.).

A metabox FAQ na ficha de produto

No ecrã de edição de cada produto, a metabox FAQ IA oferece um controlo completo:

• Gerar com a IA: cria um conjunto de perguntas e respostas para o idioma selecionado.
• Acrescentar uma pergunta manual a qualquer momento.
• Alterar uma pergunta ou uma resposta: a linha é gravada automaticamente ao perder o foco.
• Reordenar por arrastar e largar através da pega à esquerda de cada linha.
• Ativar ou desativar uma entrada sem a eliminar.
• Eliminar definitivamente uma entrada.

Um seletor de idioma no topo da metabox permite alternar instantaneamente entre as traduções Polylang ou WPML do produto: cada tradução tem o seu próprio conjunto de FAQ.

Geração em massa

Menu FAQ IA → Geração em massa:

1. Escolha o idioma de destino: idioma predefinido, idioma específico, ou todos os idiomas ativos.
2. Assinale, se quiser, Forçar a regeneração para substituir as FAQ existentes (útil depois de mudar o tom ou o fornecedor).
3. Clique em Iniciar.

O processamento é sequencial (cerca de um produto por segundo, consoante a latência da API), com barra de progresso em tempo real, contador de produtos tratados e registo de erros por produto. O botão Parar interrompe de forma limpa entre dois produtos. São tratados apenas os produtos publicados; as categorias excluídas são ignoradas.

Geração automática na criação de produto

Opção do separador Fornecedor: quando está ativa, o plugin gera automaticamente uma FAQ no idioma predefinido a cada gravação de um produto que ainda não a tenha. As FAQ existentes nunca são substituídas por este mecanismo.

Multilingue com Polylang e WPML

O plugin deteta automaticamente o Polylang (pll_languages_list, pll_get_post_translations) e o WPML (wpml_active_languages, wpml_object_id). Cada tradução de um produto recebe o seu próprio conjunto de FAQ, gerado nativamente no idioma de destino, e não uma tradução do original. A geração em massa «todos os idiomas» percorre cada tradução de cada produto.

Verificar os rich snippets

1. Abra uma ficha de produto com pelo menos uma FAQ ativa.
2. Veja o código-fonte e procure application/ld+json: tem de existir um bloco "@type":"FAQPage".
3. Teste o URL no Rich Results Test da Google: a deteção «FAQ» tem de ser válida.

Resolução de problemas

«A chave de API do fornecedor de IA não está configurada»

Indique a chave do fornecedor ativo no separador Fornecedor. Verifique que não há espaços antes ou depois da chave.

Erro de API durante a geração

Consulte WooCommerce → Estado → Registos e selecione a origem dffaqai: cada erro de API fica aí registado com o código HTTP e a mensagem do fornecedor (chave inválida, quota excedida, modelo desconhecido…).

O bloco de FAQ não aparece

Verifique que o produto tem pelo menos uma FAQ ativa no idioma apresentado, e que o tema executa o hook escolhido. Em caso de dúvida, volte ao hook predefinido woocommerce_after_single_product_summary, presente em todos os temas WooCommerce padrão.

As perguntas geradas estão no idioma errado

O idioma de geração segue a tradução do produto (Polylang/WPML) ou a locale do site em modo monolingue. Verifique o seletor de idioma da metabox antes de gerar.

Desinstalação

A desativação conserva todos os dados. A remoção do plugin executa o uninstall.php: a tabela SQL das FAQ e todas as opções dffaqai_* são eliminadas definitivamente.

Suporte

O suporte é feito por e-mail com resposta em 24 horas úteis (FR/EN). Junte, se possível, o registo dffaqai e as versões do WordPress, do WooCommerce e do PHP.