DataFirefly FAQ IA Producto para WooCommerce — Documentación

DataFirefly FAQ IA Producto genera automáticamente FAQ contextuales para tus páginas de producto WooCommerce usando OpenAI o Anthropic Claude, e inyecta los rich snippets Schema.org FAQPage en la etiqueta head para los resultados enriquecidos de Google. Esta guía cubre la instalación, la configuración completa y el uso diario.

Requisitos

• WordPress 6.0 o superior (probado hasta 6.6)
• WooCommerce 7.0 o superior (probado hasta 9.4), compatible con HPOS
• PHP 7.4 a 8.3
• Una clave API de OpenAI (platform.openai.com/api-keys) o de Anthropic (console.anthropic.com)
• Opcional: Polylang o WPML para tiendas multilingües

Instalación

1. Descarga dffaqai-1.0.0.zip desde tu cuenta DataFirefly.
2. En el admin de WordPress: Plugins → Añadir nuevo → Subir plugin, selecciona el ZIP y haz clic en Instalar ahora.
3. Haz clic en Activar. El plugin crea su tabla de almacenamiento de FAQ y los ajustes por defecto.

Configuración del proveedor de IA

Ve a FAQ AI → Ajustes → pestaña Proveedor.

Elegir OpenAI o Anthropic Claude

• OpenAI: pega tu clave API y elige un modelo — gpt-4o-mini (el más económico, recomendado), gpt-4o, gpt-4-turbo o gpt-3.5-turbo.
• Anthropic Claude: pega tu clave API y elige — claude-haiku-4-5 (económico, recomendado), claude-sonnet-4-6 o claude-opus-4-7.

El plugin enruta automáticamente a la API correcta según el proveedor seleccionado. Puedes cambiar en cualquier momento: las FAQ ya generadas se conservan.

Parámetros de generación

• Número de preguntas por producto: 1 a 15 (5 por defecto).
• Temperatura: 0 (determinista) a 2 (muy creativo). 0,7 por defecto.
• Max tokens: longitud máxima de la respuesta de la IA. 2000 por defecto.

Pestaña Prompt — personalizar el contenido generado

Tono de voz

Seis estilos preconfigurados: profesional, amigable, informal, técnico, entusiasta, tranquilizador. El tono cambia la formulación de las respuestas sin programar nada.

Público objetivo

Texto libre, por ejemplo «profesionales sanitarios (B2B)», «primeros compradores» o «aficionados al bricolaje». La IA adapta el vocabulario, las referencias y la profundidad.

Prompt de sistema personalizado

Déjalo vacío para usar el prompt por defecto construido a partir del tono y el público. Si lo rellenas, sustituye completamente las instrucciones por defecto — útil para tiendas con una línea editorial estricta.

Directrices adicionales

Instrucciones añadidas a cada prompt, por ejemplo «mencionar siempre la garantía de 2 años», «evitar superlativos», «no comparar con la competencia».

Contexto de producto a incluir

Tres casillas enriquecen el contexto enviado a la IA: categoría principal, marca (las taxonomías product_brand, pwb-brand y yith_product_brand se detectan automáticamente) y atributos WooCommerce. En productos técnicos, incluir los atributos mejora mucho la pertinencia de las preguntas.

Pestaña Visualización y SEO

Posición de visualización

Cinco hooks de WooCommerce a elegir:

• woocommerce_after_single_product_summary — bajo las pestañas (por defecto)
• woocommerce_single_product_summary — dentro del resumen del producto
• woocommerce_product_meta_end — al final del meta del producto
• woocommerce_after_single_product — después de toda la zona del producto
• woocommerce_before_single_product — antes de toda la zona del producto

La prioridad del hook (15 por defecto) es configurable para convivir con otros plugins.

Modo de visualización

Acordeón (primera pregunta abierta, navegación por teclado ARIA) o todas las respuestas desplegadas.

Rich snippets FAQPage

Cuando la opción está activa, el plugin inyecta el JSON-LD Schema.org FAQPage en la etiqueta head de cada página de producto con al menos una FAQ activa. La codificación usa JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS y JSON_HEX_QUOT y supera el Rich Results Test de Google.

Título de la FAQ por idioma

Un campo de título por idioma activo del sitio, con valores por defecto incluidos para FR, EN, ES, DE, IT, PT y NL.

Categorías excluidas

Lista de identificadores de categorías WooCommerce separados por comas. Los productos de esas categorías se omiten en la generación masiva y automática (productos virtuales, tarjetas regalo, etc.).

La metabox FAQ en la ficha de producto

En la pantalla de edición de cada producto, la metabox FAQ AI ofrece control total:

• Generar con IA: crea un conjunto de preguntas/respuestas para el idioma seleccionado.
• Añadir una pregunta manual en cualquier momento.
• Editar una pregunta o respuesta: la fila se guarda automáticamente al perder el foco.
• Reordenar por arrastrar y soltar con el tirador a la izquierda de cada fila.
• Activar/desactivar una entrada sin eliminarla.
• Eliminar definitivamente una entrada.

Un selector de idioma en la parte superior de la metabox cambia al instante entre las traducciones Polylang o WPML del producto — cada traducción tiene su propio conjunto de FAQ.

Generación masiva

Menú FAQ AI → Generación masiva:

1. Elige el idioma objetivo: idioma por defecto, un idioma específico o todos los idiomas activos.
2. Marca opcionalmente Forzar regeneración para sobrescribir las FAQ existentes (útil tras cambiar el tono o el proveedor).
3. Haz clic en Iniciar.

El procesamiento es secuencial (aproximadamente un producto por segundo según la latencia de la API) con barra de progreso en tiempo real, contador de productos procesados y registro de errores por producto. El botón Detener interrumpe limpiamente entre dos productos. Solo se procesan los productos publicados; las categorías excluidas se omiten.

Generación automática al crear un producto

Opción de la pestaña Proveedor: cuando está activa, el plugin genera automáticamente una FAQ en el idioma por defecto cada vez que se guarda un producto que no tiene ninguna. Las FAQ existentes nunca se sobrescriben con este mecanismo.

Multilingüe con Polylang y WPML

El plugin detecta automáticamente Polylang (pll_languages_list, pll_get_post_translations) y WPML (wpml_active_languages, wpml_object_id). Cada traducción de un producto recibe su propio conjunto de FAQ, generado nativamente en el idioma objetivo — no una traducción del original. El modo masivo «todos los idiomas» recorre cada traducción de cada producto.

Verificar los rich snippets

1. Abre una página de producto con al menos una FAQ activa.
2. Mira el código fuente y busca application/ld+json: debe existir un bloque "@type":"FAQPage".
3. Prueba la URL en el Rich Results Test de Google: la detección «FAQ» debe ser válida.

Solución de problemas

«La clave de API del proveedor de IA no está configurada»

Introduce la clave del proveedor activo en la pestaña Proveedor. Comprueba que no haya espacios antes o después de la clave.

Error de API durante la generación

Ve a WooCommerce → Estado → Registros y selecciona la fuente dffaqai: cada error de API queda registrado con el código HTTP y el mensaje del proveedor (clave no válida, cuota superada, modelo desconocido…).

El bloque FAQ no se muestra

Comprueba que el producto tenga al menos una FAQ activa en el idioma mostrado y que tu tema ejecute el hook elegido. En caso de duda, vuelve al hook por defecto woocommerce_after_single_product_summary, presente en todos los temas WooCommerce estándar.

Las preguntas generadas están en el idioma equivocado

El idioma de generación sigue la traducción del producto (Polylang/WPML) o la configuración regional del sitio en modo monolingüe. Comprueba el selector de idioma de la metabox antes de generar.

Desinstalación

La desactivación conserva todos los datos. Al eliminar el plugin se ejecuta uninstall.php: la tabla SQL de FAQ y todas las opciones dffaqai_* se eliminan definitivamente.

Soporte

El soporte se realiza por email con respuesta en 24 h laborables (FR/EN). Si es posible, adjunta el registro dffaqai y tus versiones de WordPress/WooCommerce/PHP.