AI People Also Ask — Documentación completa (dfaipaa)

Presentación

AI People Also Ask (slug técnico: dfaipaa) captura las preguntas que tus clientes hacen realmente a Google — los bloques «People Also Ask» — genera las respuestas con la IA que elijas y publica una FAQ marcada con schema.org en tus fichas de producto y páginas de categoría.

El módulo industrializa un pipeline completo en cuatro etapas:

• Scraping — captura de preguntas PAA sobre tus palabras clave mediante SerpApi, DataForSEO o entrada manual.
• Generación IA — redacción de las respuestas con Mistral, OpenAI o Anthropic, con tono y voz de marca configurables.
• Flujo editorial — revisión, asignación a productos y categorías, publicación (manual o automática).
• Publicación — acordeón FAQ accesible en la tienda más JSON-LD FAQPage para Google y los motores generativos.

Requisitos

• PrestaShop 8.0.0 → 9.99.99
• PHP 8.1, 8.2 o 8.3
• MySQL 5.7 / MariaDB 10.4 o superior
• Una clave API para al menos un proveedor de IA (Mistral, OpenAI o Anthropic)
• Opcional: una clave SerpApi o una cuenta DataForSEO para automatizar el scraping
• Conexiones HTTPS salientes (cURL) permitidas por tu alojamiento

Instalación

1. Descarga el ZIP dfaipaa.zip desde tu cuenta DataFirefly.
2. En el back-office de PrestaShop, ve a Módulos › Administrador de módulos › Subir un módulo.
3. Arrastra el ZIP, espera la confirmación y pulsa Instalar.
4. Aparece un nuevo menú AI People Also Ask en la columna izquierda, con tres pestañas: Configuración, Palabras clave, Preguntas.

La instalación crea 4 tablas (prefijo ps_dfaipaa_), establece los valores de configuración por defecto e instala 4 pestañas de administración (una padre y tres hijas) con etiquetas localizadas en FR, EN, ES, DE, IT y NL.

Configuración — Scraping

Pestaña AI People Also Ask › Configuración, primera sección.

Obtener una clave SerpApi

Crea una cuenta en serpapi.com. El plan gratuito ofrece 100 solicitudes al mes, aproximadamente 100 palabras clave scrapeadas. La clave está en tu panel, sección «Your Account». El módulo consulta el endpoint de búsqueda de Google y explota el bloque related_questions de la respuesta.

Obtener una cuenta DataForSEO

Crea una cuenta en dataforseo.com. Recibirás un par usuario / contraseña que debes pegar en el campo Clave API con el formato login:password (el módulo gestiona la autenticación HTTP Basic). DataForSEO factura por uso, lo que encaja mejor con volúmenes altos. El módulo usa el endpoint SERP Google organic live advanced y extrae los elementos people_also_ask.

El mapeo de códigos de ubicación está integrado para estos mercados: FR, BE, CH, LU, CA, US, UK, IE, ES, PT, IT, DE, AT, NL, PL, BR y MX.

Modo de entrada manual

Selecciona manual para desactivar toda llamada externa. Añades las preguntas tú mismo desde la pestaña Preguntas; la generación IA sigue plenamente operativa.

Configuración — Inteligencia artificial

Segunda sección de la pestaña Configuración.

Modelos recomendados

• Mistral — mistral-large-latest por calidad, mistral-small-latest para reducir costes en grandes volúmenes.
• OpenAI — gpt-4o-mini ofrece una excelente relación calidad-precio; gpt-4o para catálogos técnicos exigentes.
• Anthropic — claude-sonnet-4-6 para respuestas matizadas y bien estructuradas.

Restricciones impuestas al modelo

El módulo construye un prompt de sistema estricto, independiente del proveedor: respuestas de 60 a 120 palabras, HTML sencillo únicamente (párrafos, negrita, cursiva, listas), sin markdown, sin etiquetas de título y sin scripts. El contexto de la entidad (nombre y descripción del producto o categoría, truncados a 1200 caracteres) y la palabra clave de origen se inyectan para anclar la respuesta. El snippet original de Google se aporta como referencia con una instrucción explícita de reformulación — nunca de copia.

Configuración — Visualización

Tercera sección de la pestaña Configuración.

En modo tab, el módulo se apoya en el mecanismo nativo ProductExtraContent de PrestaShop: la FAQ aparece como una pestaña junto a «Descripción» y «Detalles del producto», sin sobrescribir plantillas.

Flujo editorial

Paso 1 — Añadir palabras clave

Pestaña Palabras clave. Pega tu lista en el área de texto, una palabra clave por línea, y valida. Los duplicados se ignoran automáticamente (el alta es idempotente por palabra clave, idioma y tienda).

Elige palabras clave alineadas con la intención de compra: «cafetera automática», «mejor café en grano», «mantenimiento cafetera». Evita las consultas de marca pura, que rara vez activan bloques PAA.

Paso 2 — Scrapear

Dos opciones:

• Scrapear — botón individual en cada fila, útil para probar la configuración.
• Scrapear todas las caducadas — procesa en lotes de 20 las palabras clave cuya última captura supera el intervalo de actualización.

Cada pregunta capturada se guarda con un hash de unicidad (pregunta + idioma + tienda): volver a scrapear una palabra clave nunca crea duplicados, solo actualiza la fecha de última captura.

Paso 3 — Generar las respuestas

Pestaña Preguntas. Filtra por estado pending, selecciona las preguntas con las casillas y lanza la acción masiva Generar. También hay un botón individual en cada fila.

El contexto de entidad se construye a partir de la primera asignación de la pregunta. Para obtener mejores respuestas, asigna la pregunta a un producto o categoría antes de generar: la IA dispondrá del nombre y la descripción de la entidad.

Paso 4 — Revisar y asignar

Haz clic en una pregunta para abrir el formulario de edición. Puedes:

• corregir la respuesta HTML en el editor enriquecido;
• asignar la pregunta a uno o varios productos y categorías (relación N a N);
• reordenar las asignaciones para controlar el orden del acordeón;
• rechazar una pregunta fuera de tema (estado rejected, conservada en base de datos pero nunca mostrada).

Paso 5 — Publicar

Cambia el estado a published. La FAQ aparece de inmediato en la tienda, acompañada de su JSON-LD.

Si la opción Autopublicación está activada, los pasos 4 y 5 se fusionan: la generación publica directamente. Práctico para un pipeline totalmente automatizado, recomendable solo en catálogos donde la revisión humana no es crítica.

Estados de las preguntas

Visualización en la tienda

El acordeón se basa en los elementos HTML nativos details y summary, lo que garantiza:

• navegación por teclado funcional sin JavaScript;
• contenido indexable por los motores incluso plegado;
• compatibilidad con todos los navegadores modernos.

El primer elemento se abre por defecto. Se carga un CSS ligero, totalmente sobrescribible desde tu tema hijo. Todas las clases usan el prefijo dfaipaa-faq para evitar colisiones.

Eventos JavaScript

El script frontend emite dos eventos personalizados que puedes conectar a tu herramienta 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 cerrada:', e.detail.question);
});

El archivo views/js/front.js incluye además una constante SINGLE_OPEN (a false por defecto): ponla a true para permitir un solo panel abierto a la vez.

Enlaces profundos

Un ancla del tipo #dfaipaa-q-123 abre automáticamente la pregunta correspondiente y desplaza la página hasta ella. Útil para compartir una respuesta concreta desde un email o un ticket de soporte.

Marcado JSON-LD FAQPage

En cada carga de página de producto o categoría con al menos una pregunta publicada, el módulo inyecta un bloque JSON-LD justo antes del cierre del cuerpo del documento (hook displayBeforeBodyClosingTag).

Estructura emitida: un nodo FAQPage, un array mainEntity y, por cada entrada, un nodo Question con un acceptedAnswer de tipo Answer. El contenido HTML de las respuestas se sanea antes de emitirse: se eliminan las etiquetas de script y estilo y los atributos de evento.

Automatización por cron

Se incluye un script CLI para ejecutar el pipeline sin intervención manual.

# Scrapear las palabras clave caducadas (20 máx. por defecto)
php modules/dfaipaa/cli/cron.php scrape --limit=20

# Generar las respuestas IA de las preguntas pendientes
php modules/dfaipaa/cli/cron.php generate --limit=10

# Encadenar scraping y generación
php modules/dfaipaa/cli/cron.php all --limit=20

Ejemplo de crontab, ejecución nocturna a las 3 h:

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

Multiidioma y multitienda

Las preguntas se indexan por id_lang e id_shop. En la práctica:

• una misma palabra clave scrapeada en español y en inglés produce dos conjuntos distintos de preguntas;
• las respuestas se generan en el idioma de la pregunta, aplicando el prompt una directiva lingüística explícita (fr, en, es, de, it, nl, pt, pl);
• en multitienda, las preguntas y asignaciones de una tienda nunca aparecen en otra;
• los títulos de visualización (pestaña, producto, categoría) se guardan como configuración localizada.

Resolución de problemas

El scraping no devuelve ninguna pregunta

• Comprueba tu cuota en el proveedor: SerpApi corta silenciosamente al superar el plan gratuito.
• Verifica la coherencia idioma / país: «es» con «US» da resultados erráticos.
• Algunas palabras clave simplemente no activan bloques PAA en Google. Prueba la consulta manualmente en una ventana de incógnito.
• Para DataForSEO, verifica el formato login:password del campo Clave API.

La IA devuelve markdown en lugar de HTML

Baja la temperatura a 0.2 o cambia a un modelo más capaz. El prompt ya impone reglas HTML estrictas, pero los modelos más ligeros pueden ignorarlas parcialmente.

La FAQ no aparece en la tienda

• Comprueba que al menos una pregunta esté en estado published.
• Comprueba que esté asignada a la entidad consultada (producto o categoría).
• Verifica que la visualización esté activada para ese tipo de entidad en la configuración.
• Vacía la caché Smarty desde Parámetros avanzados › Rendimiento.

El JSON-LD no aparece en el código fuente

Asegúrate de que la opción «Emitir JSON-LD» está activada y de que tu tema llama al hook displayBeforeBodyClosingTag. Algunos temas de terceros lo omiten: en ese caso añade {hook h='displayBeforeBodyClosingTag'} antes del cierre del cuerpo en tu layouts/layout-both-columns.tpl.

Error «Class not found» tras la instalación

La carpeta vendor/ no se extrajo. Reinstala el módulo subiendo el ZIP desde el back-office en lugar de descomprimirlo manualmente.

Consultar los registros de operaciones

Todas las operaciones (scraping, generación, publicación) quedan registradas. Para investigar:

SELECT * FROM ps_dfaipaa_log ORDER BY date_add DESC LIMIT 50;

Desinstalación

Desde Módulos › Administrador de módulos, pulsa Desinstalar. La operación elimina las 4 tablas ps_dfaipaa_*, las 4 pestañas de administración y todas las claves de configuración DFAIPAA_. El contenido generado se pierde definitivamente: exporta tus preguntas antes si quieres conservarlas.

Referencia técnica

• Slug técnico: dfaipaa
• Namespace: DataFirefly Dfaipaa (PSR-4, autoloader incluido)
• Tablas creadas: 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
• Pestañas back-office: AdminDfaipaa (padre), AdminDfaipaaConfig, AdminDfaipaaKeywords, AdminDfaipaaQuestions
• Claves de configuración: 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)
• Plantilla front: views/templates/hook/faq.tpl

Conformidad RGPD

El módulo no recopila ni almacena ningún dato personal: solo se registran palabras clave, preguntas, respuestas generadas y registros técnicos de operaciones. No se deposita ninguna cookie en la tienda. Las llamadas a las API externas (scraping, IA) transmiten únicamente la palabra clave, la pregunta y el contexto del producto — nunca datos de clientes.

Soporte

Para cualquier consulta técnica, contacta con el equipo de DataFirefly en [email protected] o accede a tu área de cliente en datafirefly.com.