AI People Also Ask: documentação completa (dfaipaa)

Apresentação

O AI People Also Ask (slug técnico: dfaipaa) capta as perguntas que os seus clientes fazem realmente à Google, os blocos «People Also Ask», gera as respostas com uma IA à sua escolha e publica uma FAQ com marcação schema.org nas suas fichas de produto e páginas de categoria.

O módulo industrializa um pipeline completo em quatro etapas:

• Recolha — captura das perguntas PAA nas suas palavras-chave alvo através da SerpApi, do DataForSEO ou por introdução manual.
• Geração por IA — redação das respostas através da Mistral, da OpenAI ou da Anthropic, com tom e voz de marca configuráveis.
• Fluxo editorial — revisão, atribuição a produtos e categorias, publicação (manual ou automática).
• Publicação — acordeão de FAQ acessível no lado da loja + JSON-LD FAQPage para a Google e para os motores generativos.

Pré-requisitos

• PrestaShop 8.0.0 → 9.99.99
• PHP 8.1, 8.2 ou 8.3
• MySQL 5.7 / MariaDB 10.4 ou superior
• Uma chave de API para, pelo menos, um fornecedor de IA (Mistral, OpenAI ou Anthropic)
• Opcional: uma chave SerpApi ou uma conta DataForSEO para automatizar a recolha
• Ligações HTTPS de saída autorizadas (cURL) a partir do seu alojamento

Instalação

1. Descarregue o ZIP dfaipaa.zip a partir da sua conta DataFirefly.
2. No back-office do PrestaShop, vá a Módulos › Gestor de módulos › Carregar um módulo.
3. Arraste e largue o ZIP, aguarde a confirmação e clique em Instalar.
4. Aparece um novo menu AI People Also Ask na coluna da esquerda, com três separadores: Configuração, Palavras-chave e Perguntas.

A instalação cria 4 tabelas (prefixo ps_dfaipaa_), define os valores de configuração predefinidos e instala 4 separadores de administração (um pai e três filhos) com legendas localizadas em FR, EN, ES, DE, IT e NL.

Configuração: recolha

Separador AI People Also Ask › Configuração, primeira secção.

Obter uma chave SerpApi

Crie uma conta em serpapi.com. O plano gratuito oferece 100 pedidos por mês, o que corresponde a cerca de 100 palavras-chave recolhidas. A chave encontra-se no seu painel, na secção «Your Account». O módulo consulta o endpoint de pesquisa da Google e utiliza o bloco related_questions da resposta.

Obter uma conta DataForSEO

Crie uma conta em dataforseo.com. Recebe um par de identificador e palavra-passe para colar no campo Chave de API sob a forma login:password (o módulo trata a autenticação HTTP Basic). O DataForSEO cobra por utilização, o que se adequa melhor a grandes volumes. O módulo utiliza o endpoint SERP Google organic live advanced e extrai os elementos people_also_ask.

O mapeamento dos códigos de localização está integrado para os seguintes mercados: FR, BE, CH, LU, CA, US, UK, IE, ES, PT, IT, DE, AT, NL, PL, BR e MX.

Modo de introdução manual

Selecione manual para desativar qualquer chamada externa. Passa então a acrescentar as perguntas você mesmo no separador Perguntas; a geração por IA mantém-se plenamente funcional.

Configuração: inteligência artificial

Segunda secção do separador Configuração.

Modelos recomendados

• Mistral — mistral-large-latest pela qualidade, mistral-small-latest para reduzir custos em grandes volumes.
• OpenAI — gpt-4o-mini oferece uma excelente relação qualidade/preço; gpt-4o para catálogos técnicos exigentes.
• Anthropic — claude-sonnet-4-6 para respostas mais matizadas e bem estruturadas.

Restrições impostas ao modelo

O módulo constrói um prompt de sistema estrito, independente do fornecedor: respostas de 60 a 120 palavras, apenas HTML simples (parágrafos, negrito, itálico, listas), proibição de markdown, de etiquetas de título e de qualquer script. O contexto da entidade (nome e descrição do produto ou da categoria, truncados a 1200 caracteres) e a palavra-chave de origem são injetados para ancorar a resposta. O snippet original da Google é fornecido como referência, com uma instrução explícita de reformulação: nunca de cópia.

Configuração: apresentação

Terceira secção do separador Configuração.

No modo tab, o módulo apoia-se no mecanismo nativo ProductExtraContent do PrestaShop: a FAQ aparece como um separador ao lado de «Descrição» e «Detalhes do produto», sem sobreposição de templates.

Fluxo editorial

Etapa 1: acrescentar palavras-chave

Separador Palavras-chave. Cole a sua lista na caixa de texto, uma palavra-chave por linha, e valide. Os duplicados são ignorados automaticamente (a adição é idempotente por palavra-chave, idioma e loja).

Escolha palavras-chave que correspondam à intenção de compra: «máquina de café automática», «melhor café em grão», «manutenção de máquina de café». Evite pesquisas de marca pura, que raramente despoletam blocos PAA.

Etapa 2: recolher

Duas opções:

• Recolher — botão individual em cada linha de palavra-chave, útil para testar a configuração.
• Recolher todas as desatualizadas — trata em lotes de 20 as palavras-chave cuja última captura ultrapassa o intervalo de atualização.

Cada pergunta captada é guardada com um hash de unicidade (pergunta + idioma + loja): voltar a recolher uma palavra-chave nunca cria duplicados, apenas atualiza a data da última captura.

Etapa 3: gerar as respostas

Separador Perguntas. Filtre pelo estado pending, selecione as perguntas através das caixas de seleção e lance a ação em massa Gerar. Existe também um botão individual em cada linha.

O contexto da entidade é construído a partir da primeira atribuição da pergunta. Para obter melhores respostas, atribua a pergunta a um produto ou a uma categoria antes de gerar: a IA disporá então do nome e da descrição da entidade.

Etapa 4: rever e atribuir

Clique numa pergunta para abrir o formulário de edição. Pode:

• corrigir a resposta HTML no editor enriquecido;
• atribuir a pergunta a um ou vários produtos e categorias (relação N para N);
• reordenar as atribuições para controlar a ordem de apresentação do acordeão;
• rejeitar uma pergunta fora do tema (estado rejected, mantida na base de dados mas nunca apresentada).

Etapa 5: publicar

Passe o estado para published. A FAQ aparece imediatamente do lado da loja, acompanhada do seu JSON-LD.

Se a opção Publicação automática estiver ativada na configuração, as etapas 4 e 5 fundem-se: a geração publica diretamente. Prático para um pipeline totalmente automatizado, a reservar para catálogos em que a revisão humana não é crítica.

Estados das perguntas

Apresentação do lado da loja

O acordeão assenta nos elementos HTML nativos details e summary, o que garante:

• uma navegação por teclado funcional sem JavaScript;
• conteúdo indexável pelos motores mesmo quando recolhido;
• compatibilidade com todos os navegadores modernos.

O primeiro elemento está aberto por predefinição. É carregado um ficheiro CSS leve, totalmente sobreponível a partir do seu tema-filho. Todas as classes usam o prefixo dfaipaa-faq para evitar colisões.

Eventos JavaScript

O script do front-office emite dois eventos personalizados que pode ligar à sua ferramenta de analítica:

document.addEventListener('dfaipaa:open', function (e) {
  // e.detail.question, e.detail.index, e.detail.type, e.detail.entityId
  gtag('event', 'faq_open', { question: e.detail.question });
});

document.addEventListener('dfaipaa:close', function (e) {
  console.log('FAQ fechada:', e.detail.question);
});

O ficheiro views/js/front.js contém também uma constante SINGLE_OPEN (a false por predefinição): passe-a para true para autorizar apenas um painel aberto de cada vez.

Ligação direta a uma pergunta

Uma âncora com a forma #dfaipaa-q-123 abre automaticamente a pergunta correspondente e faz a página deslizar até ela. Prático para partilhar uma resposta específica a partir de um e-mail ou de um ticket de apoio ao cliente.

Marcação JSON-LD FAQPage

Em cada carregamento de uma página de produto ou de categoria com, pelo menos, uma pergunta publicada, o módulo injeta um bloco JSON-LD imediatamente antes do fecho do corpo do documento (hook displayBeforeBodyClosingTag).

Estrutura emitida: um nó FAQPage, um array mainEntity e, para cada entrada, um nó Question que contém um acceptedAnswer do tipo Answer. O conteúdo HTML das respostas é limpo antes da emissão: as etiquetas de script e de estilo, bem como os atributos de eventos, são removidos.

Automatização por cron

É fornecido um script CLI para executar o pipeline sem intervenção manual.

# Recolher as palavras-chave desatualizadas (20 no máximo por predefinição)
php modules/dfaipaa/cli/cron.php scrape --limit=20

# Gerar as respostas de IA para as perguntas pendentes
php modules/dfaipaa/cli/cron.php generate --limit=10

# Encadear recolha e geração
php modules/dfaipaa/cli/cron.php all --limit=20

Exemplo de crontab, execução noturna às 3 h:

0 3 * * * cd /var/www/prestashop && php modules/dfaipaa/cli/cron.php all --limit=30 >> /var/log/dfaipaa.log 2>&1

Multilingue e multiloja

As perguntas são indexadas por id_lang e id_shop. Na prática:

• a mesma palavra-chave recolhida em português e em inglês produz dois conjuntos de perguntas distintos;
• as respostas são geradas no idioma da pergunta, uma vez que o prompt aplica uma diretiva linguística explícita (fr, en, es, de, it, nl, pt, pl);
• em multiloja, as perguntas e atribuições de uma loja nunca aparecem noutra;
• os títulos de apresentação (separador, produto, categoria) são guardados em configuração localizada.

Resolução de problemas

A recolha não devolve qualquer pergunta

• Verifique a sua quota no fornecedor: a SerpApi corta silenciosamente acima do plano gratuito.
• Confirme a coerência entre idioma e país: «pt» com «US» dá resultados erráticos.
• Algumas palavras-chave simplesmente não despoletam bloco PAA na Google. Teste o pedido manualmente num navegador em navegação privada.
• No DataForSEO, verifique o formato login:password do campo Chave de API.

A IA devolve markdown em vez de HTML

Baixe a temperatura para 0.2 ou mude para um modelo mais capaz. O prompt já impõe regras HTML estritas, mas os modelos mais leves podem ignorá-las parcialmente.

A FAQ não aparece na loja

• Verifique se há, pelo menos, uma pergunta no estado published.
• Verifique se está mesmo atribuída à entidade consultada (produto ou categoria).
• Confirme que a apresentação está ativada para esse tipo de entidade na configuração.
• Limpe a cache do Smarty em Parâmetros avançados › Desempenho.

O JSON-LD não aparece no código-fonte

Certifique-se de que a opção «Emitir o JSON-LD» está ativada e de que o tema chama efetivamente o hook displayBeforeBodyClosingTag. Alguns temas de terceiros omitem-no: acrescente então {hook h='displayBeforeBodyClosingTag'} antes do fecho do corpo no seu layouts/layout-both-columns.tpl.

Erro «Class not found» depois da instalação

A pasta vendor/ não foi extraída. Reinstale o módulo carregando o ZIP através do back-office em vez de o descomprimir manualmente.

Consultar os registos de operação

Todas as operações (recolha, geração, publicação) ficam registadas. Para investigar:

SELECT * FROM ps_dfaipaa_log ORDER BY date_add DESC LIMIT 50;

Desinstalação

Em Módulos › Gestor de módulos, clique em Desinstalar. A operação elimina as 4 tabelas ps_dfaipaa_*, os 4 separadores de administração e todas as chaves de configuração DFAIPAA_. O conteúdo gerado é definitivamente perdido: exporte as suas perguntas previamente se as quiser conservar.

Referência técnica

• Slug técnico: dfaipaa
• Namespace: DataFirefly Dfaipaa (PSR-4, autoloader incorporado)
• Tabelas criadas: ps_dfaipaa_keyword, ps_dfaipaa_question, ps_dfaipaa_assignment, ps_dfaipaa_log
• Hooks utilizados: displayHeader, displayProductExtraContent, displayFooterProduct, displayCategoryFooter, displayBeforeBodyClosingTag, actionFrontControllerSetMedia, actionAdminControllerSetMedia, actionProductUpdate, actionProductSave, actionCategoryUpdate, actionObjectProductDeleteAfter, actionObjectCategoryDeleteAfter
• Separadores do back-office: AdminDfaipaa (pai), AdminDfaipaaConfig, AdminDfaipaaKeywords, AdminDfaipaaQuestions
• Chaves de configuração: DFAIPAA_SCRAPER_PROVIDER, DFAIPAA_SCRAPER_API_KEY, DFAIPAA_SCRAPER_LANG, DFAIPAA_SCRAPER_COUNTRY, DFAIPAA_SCRAPER_MAX_PER_KEYWORD, DFAIPAA_AI_PROVIDER, DFAIPAA_AI_MODEL, DFAIPAA_AI_API_KEY, DFAIPAA_AI_TEMPERATURE, DFAIPAA_AI_MAX_TOKENS, DFAIPAA_AI_TONE, DFAIPAA_AI_BRAND_VOICE, DFAIPAA_AUTO_PUBLISH, DFAIPAA_REFRESH_INTERVAL, DFAIPAA_PRODUCT_MODE, DFAIPAA_EMIT_JSONLD, DFAIPAA_TAB_TITLE, DFAIPAA_PRODUCT_TITLE, DFAIPAA_CATEGORY_TITLE
• CLI: modules/dfaipaa/cli/cron.php (comandos scrape, generate, all)
• Template do front-office: views/templates/hook/faq.tpl

Conformidade com o RGPD

O módulo não recolhe nem guarda qualquer dado pessoal: apenas palavras-chave, perguntas, respostas geradas e registos técnicos de operações. Não é depositado qualquer cookie do lado da loja. As chamadas às API externas (recolha, IA) transmitem apenas a palavra-chave, a pergunta e o contexto do produto: nunca dados de clientes.

Apoio ao cliente

Para qualquer questão técnica, contacte a equipa DataFirefly através de contact@datafirefly.com ou consulte a sua área de cliente em datafirefly.com.