Predictive SEO — Documentación completa

Resumen

DataFirefly Predictive SEO conecta su tienda PrestaShop con Google Search Console, aplica un motor de predicción ML embebido sobre el historial de búsqueda e identifica automáticamente los picos estacionales por venir. Para cada oportunidad detectada, puede generar en un clic un brief de contenido estructurado vía Mistral, OpenAI o Claude.

Requisitos

• PrestaShop 8.0+ o PrestaShop 9.x
• PHP 8.1 mínimo
• MySQL 5.7+ o MariaDB 10.3+
• Una cuenta de Google con acceso a la propiedad Search Console de la tienda
• Una clave API de un proveedor IA (Mistral, OpenAI o Anthropic — Mistral por defecto, alrededor de 0,002 € por brief)
• Al menos 60 a 90 días de historial GSC para predicciones fiables

Instalación

Instalación desde el ZIP

1. Descargue el archivo dfpredictiveseo.zip desde su área de cliente DataFirefly.
2. En el back-office de PrestaShop, vaya a Módulos → Gestor de módulos.
3. Haga clic en Subir un módulo y suelte el ZIP.
4. El módulo se instala automáticamente, crea las 7 tablas dfpseo_*, registra las 6 pestañas bajo IMPROVE y genera un token de cron único.
5. Una vez instalado, encontrará el módulo en Mejorar → Predictive SEO.

Esquema de base de datos

La instalación crea 7 tablas con el prefijo dfpseo_:

• dfpseo_keyword — palabras clave rastreadas desde GSC
• dfpseo_history — historial diario (impresiones, clics, CTR, posición)
• dfpseo_forecast — predicciones diarias con intervalos de confianza
• dfpseo_opportunity — oportunidades estacionales detectadas
• dfpseo_recommendation — briefs de contenido generados por IA
• dfpseo_seasonality — índices estacionales (día-de-semana × mes) por palabra clave
• dfpseo_sync_log — registro de sincronizaciones GSC

Configuración de Google Search Console

El módulo utiliza el protocolo OAuth2 estándar. Usted crea un OAuth Client en Google Cloud, pega las credenciales en los ajustes, y lanza el flujo de autorización desde el botón Conectar.

Paso 1 — Crear un proyecto de Google Cloud

1. Vaya a console.cloud.google.com e inicie sesión con la cuenta de Google que tiene acceso a su propiedad Search Console.
2. Haga clic en el selector de proyecto arriba a la izquierda, luego en Nuevo proyecto.
3. Nómbrelo por ejemplo DataFirefly Predictive SEO y créelo.

Paso 2 — Activar la API de Search Console

1. En el menú de la izquierda, vaya a APIs y Servicios → Biblioteca.
2. Busque Search Console API y haga clic en Habilitar.

Paso 3 — Configurar la pantalla de consentimiento OAuth

1. Vaya a APIs y Servicios → Pantalla de consentimiento OAuth.
2. Tipo de usuario: Externo.
3. Complete nombre de la app, email de soporte, dominio autorizado (su tienda).
4. En Permisos, añada https://www.googleapis.com/auth/webmasters.readonly (solo lectura Search Console).
5. En modo prueba, añada su email en Usuarios de prueba. Puede pasar a producción más tarde sin modificación del módulo.

Paso 4 — Crear el Client OAuth

1. Vaya a APIs y Servicios → Credenciales.
2. Haga clic en Crear credenciales → ID de cliente de OAuth.
3. Tipo de aplicación: Aplicación web.
4. Nombre: libre (por ejemplo Predictive SEO Producción).
5. URI de redirección autorizado: copie el URI mostrado en los ajustes del módulo (Improve → Predictive SEO → Ajustes → Google Search Console → URI de redirección). Formato: https://su-tienda.com/module/dfpredictiveseo/settings/oauth_callback.
6. Haga clic en Crear — Google muestra el client_id y el client_secret.

Paso 5 — Conectar el módulo

1. En los ajustes Predictive SEO, pegue el client_id y el client_secret.
2. Guarde.
3. Haga clic en Conectar a Google Search Console.
4. Se le redirige a la página de consentimiento de Google. Autorice el acceso de solo lectura.
5. De vuelta en el back-office, el módulo ha almacenado el refresh_token cifrado y está listo para sincronizar.
6. Seleccione luego la propiedad Search Console a rastrear en el dropdown (el módulo la detecta automáticamente después de la conexión).

Configuración del proveedor IA

El módulo soporta 3 proveedores IA para generar los briefs de contenido. Solo necesita uno, y usted proporciona su propia clave API del proveedor elegido — DataFirefly no cobra ninguna comisión sobre el uso.

Mistral (por defecto, recomendado)

• Modelo: mistral-small-latest
• Coste indicativo: alrededor de 0,002 € por brief generado
• Crear la clave: console.mistral.ai → API Keys
• Pegue la clave en Ajustes → Proveedor IA → Clave API Mistral

OpenAI

• Modelo: gpt-4o-mini
• Coste indicativo: alrededor de 0,005 € por brief
• Crear la clave: platform.openai.com → API keys
• Pegue la clave en Ajustes → Proveedor IA → Clave API OpenAI

Anthropic (Claude)

• Modelo: claude-3-5-haiku-latest
• Coste indicativo: alrededor de 0,004 € por brief
• Crear la clave: console.anthropic.com → API Keys
• Pegue la clave en Ajustes → Proveedor IA → Clave API Anthropic

Seleccione luego el proveedor activo en el dropdown Proveedor IA activo. Si cambia de proveedor, los briefs ya generados no se regeneran automáticamente.

Sincronización de datos

Primera sincronización

Una vez establecida la conexión GSC, lance una primera sincronización manual: Ajustes → Lanzar sincronización. El módulo recupera el historial de los últimos 90 días para la propiedad seleccionada — hasta 250 000 filas por sincronización, con las dimensiones fecha × consulta × página. La primera sincronización puede tardar de 30 segundos a 2 minutos según el volumen.

Cron diario

Para las sincronizaciones automáticas, configure un cron diario (recomendado: temprano por la mañana, 4-6h hora de París) que llame al endpoint securizado del módulo.

La URL exacta y el token se muestran en Ajustes → Cron. Formato genérico:

https://su-tienda.com/module/dfpredictiveseo/cron/sync?token=SU_TOKEN_GENERADO

Ejemplo de línea crontab (cron Unix):

0 5 * * * curl -s "https://su-tienda.com/module/dfpredictiveseo/cron/sync?token=SU_TOKEN" > /dev/null 2>&1

Pipeline de una sincronización

Cada sincronización ejecuta en secuencia:

1. Pull GSC sobre los últimos 90 días deslizantes (dimensiones fecha/consulta/página)
2. Inserción/actualización en dfpseo_keyword y dfpseo_history
3. Recálculo de los índices estacionales (por palabra clave con suficiente historial)
4. Generación de forecasts sobre el horizonte configurado
5. Detección de oportunidades sobre la ventana futura
6. Registro en dfpseo_sync_log

Dashboard

El dashboard (Improve → Predictive SEO → Tablero) reúne los indicadores clave:

• 4 KPI cards: palabras clave rastreadas, oportunidades por venir, clics previstos en 14 días, última sync GSC
• Gráfico principal: curva agregada historial (90 días) + forecast (horizonte configurado, 30 días por defecto), con banda de confianza 95%
• Top oportunidades: los 10 próximos picos estacionales ordenados por puntuación
• Registro de syncs: las 5 últimas sincronizaciones con su estado

Estado de la conexión

Dos badges en la parte superior del dashboard indican el estado de las integraciones: GSC conectado (verde/rojo) y Proveedor IA configurado (verde/rojo). Si alguno está rojo, siga el enlace directo a los ajustes correspondientes.

Palabras clave y previsiones

Lista de palabras clave

La pestaña Palabras clave muestra el grid nativo de PrestaShop con todas las consultas sincronizadas. Columnas: consulta, página de aterrizaje, impresiones 30 d, clics 30 d, CTR, posición media, última actualización. Puede filtrar, ordenar y exportar.

Vista detallada por palabra clave

Un clic en una palabra clave abre su ficha:

• Curva individual historial + forecast personal
• Intervalo de confianza 95% alrededor de la predicción
• Mapa de calor estacional 12 × 7 (mes × día-de-semana)
• Índices estacionales calculados
• Lista de oportunidades vinculadas a esta palabra clave

Mapa de calor de estacionalidad

El mapa de calor visualiza los índices estacionales multiplicativos. Lectura:

• Celda a 1,00 → tráfico medio en esta combinación mes × día
• Celda a 1,50 → tráfico 50% por encima de la media (pico estacional)
• Celda a 0,60 → tráfico 40% por debajo de la media (valle)

Las celdas están coloreadas del azul pálido (valle) al azul profundo y rojo-naranja (pico). Un vistazo basta para detectar las semanas a explotar.

Oportunidades estacionales

Detección automática

Una oportunidad se detecta cuando, sobre una ventana futura de 14 días (configurable vía DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS):

• La predicción supera la baseline de la palabra clave × 1,25 (umbral de pico)
• Y el índice estacional de la combinación mes × día es superior a 1,10

Los picos contiguos (gap ≤ 2 días) se agrupan en una sola oportunidad que cubre la ventana completa.

Puntuación de oportunidad

La puntuación combina tres factores:

score = clics_esperados × lift × confianza

• clics_esperados: suma de los clics predichos sobre la ventana
• lift: ratio pico / baseline
• confianza: anchura del intervalo de predicción (cuanto más estrecho, mayor la puntuación)

Una puntuación > 80 indica una oportunidad de alto potencial y fuerte señal estacional. Una puntuación 40-80 indica una oportunidad moderada. Por debajo de 40, la señal es demasiado débil o demasiado incierta para justificar una acción prioritaria.

Workflow de oportunidad

Cada oportunidad tiene un estado:

• Nueva — recién detectada, a la espera de decisión
• En curso — se ha generado un brief, en trabajo editorial
• Procesada — contenido publicado, oportunidad explotada
• Ignorada — decisión de no procesar (falso positivo, fuera de estrategia)

Recomendaciones IA

Generar un brief

Desde cualquier oportunidad, haga clic en Generar brief. El módulo envía una solicitud al proveedor IA activo con el contexto de la palabra clave (volumen, estacionalidad, posición actual, página afectada) y recibe un brief JSON estructurado conteniendo:

• summary — resumen estratégico del brief
• meta_description — meta description SEO lista para pegar (150-160 caracteres)
• search_intent — intención de búsqueda dominante (informacional / transaccional / navegacional / comercial)
• outline — plan detallado h1/h2/h3 del artículo o página
• keywords_to_include — palabras clave semánticas a incluir
• internal_links — sugerencias de enlaces internos hacia otras páginas del sitio
• rationale — justificación estratégica de la recomendación

La generación tarda de 1 a 3 segundos según el proveedor.

Workflow de aprobación

Cada brief pasa por los estados:

1. Pending — generado, a la espera de revisión
2. Approved — validado para redacción
3. Published — contenido en línea (marcar manualmente)
4. Rejected — rechazado (brief de mala calidad o fuera de tema)
5. Draft — en modificación

El workflow le permite mantener un seguimiento claro de lo procesado.

Arquitectura técnica

Stack

• Arquitectura PSR-4, namespace DfPredictiveSeo → src/
• Controllers Symfony extendiendo FrameworkBundleAdminController
• Repositories Doctrine DBAL (sin ObjectModel)
• GSC accedida en REST directo vía cURL + OAuth2 (sin google/apiclient, para mantenerse ligero)
• Ninguna dependencia Composer obligatoria en la instalación (autoloader PSR-4 embebido)

Pipeline ML

1. Descomposición estacional multiplicativa: índices día-de-semana y mes calculados vía media móvil centrada 28 días y media truncada 10%
2. Regresión OLS sobre log(impresiones+1) para modelar la tendencia log-lineal
3. Forecast: exp(prediccion_log) × indice_estacional_dia × indice_estacional_mes
4. Intervalos 95%: aproximación Student sobre el error residual de la regresión, ensanchamiento progresivo con el horizonte

Endpoint cron

El endpoint es público pero protegido por token. Ejemplo en PHP para llamadas programáticas:

$token = 'su_token_cron';
$url = 'https://su-tienda.com/module/dfpredictiveseo/cron/sync?token=' . $token;
$response = file_get_contents($url);
$data = json_decode($response, true);
// $data['status'] = 'ok' | 'error'
// $data['keywords_synced'] = número de palabras clave actualizadas
// $data['opportunities_detected'] = número de oportunidades nuevamente detectadas

Variables de configuración

El módulo almacena 18 claves de configuración en la tabla ps_configuration:

• DFPSEO_GSC_CLIENT_ID, DFPSEO_GSC_CLIENT_SECRET, DFPSEO_GSC_REFRESH_TOKEN (cifrado), DFPSEO_GSC_PROPERTY
• DFPSEO_AI_PROVIDER, DFPSEO_AI_MISTRAL_KEY, DFPSEO_AI_OPENAI_KEY, DFPSEO_AI_ANTHROPIC_KEY
• DFPSEO_FORECAST_HORIZON_DAYS (defecto: 30)
• DFPSEO_OPPORTUNITY_LOOKAHEAD_DAYS (defecto: 14)
• DFPSEO_PEAK_THRESHOLD (defecto: 1.25)
• DFPSEO_SEASONAL_THRESHOLD (defecto: 1.10)
• DFPSEO_CRON_TOKEN (generado en la instalación)
• DFPSEO_LAST_SYNC, DFPSEO_LAST_FORECAST

Solución de problemas

Error redirect_uri_mismatch en el momento de la conexión GSC

El URI de redirección configurado en Google Cloud no corresponde exactamente al esperado por el módulo. Verifique:

• Protocolo: https:// y no http://
• Sin barra final: ...oauth_callback y no ...oauth_callback/
• Subdominio: www. o no según su tienda, debe coincidir

La sync GSC no devuelve ninguna palabra clave

• Verifique que la propiedad seleccionada en los ajustes es realmente la que recibe tráfico SEO (y no una propiedad de dominio vacía)
• Verifique que la cuenta Google conectada es propietario o usuario autorizado sobre esta propiedad
• La propiedad debe tener al menos unos días de historial indexado (Google Search Console publica los datos con 2-3 días de retraso)

Las predicciones parecen poco fiables

• Verifique que tiene al menos 60-90 días de historial. Por debajo, los índices estacionales no pueden estimarse correctamente
• Para palabras clave erráticas (poca señal, mucho ruido), la anchura del intervalo 95% se extiende voluntariamente — el módulo muestra explícitamente una baja confianza
• Para predicciones más precisas en horizontes largos (60-90 días), espere a haber acumulado 6-12 meses de historial. El motor mejora con el tiempo

El endpoint cron devuelve error 403

El token pasado en query string no corresponde a DFPSEO_CRON_TOKEN. Verifique el valor exacto en Ajustes → Cron. En caso de duda, regenere el token y actualice su crontab.

El brief IA no se genera

• Verifique que ha pegado correctamente una clave API válida para el proveedor activo seleccionado
• Verifique su saldo en la consola del proveedor (Mistral, OpenAI o Anthropic)
• Si el proveedor devuelve un error de rate limit, espere unos minutos y reintente
• Los briefs generados se almacenan en dfpseo_recommendation; en caso de error, el error también se registra en esta tabla con el estado error

FAQ

¿El módulo funciona sin Google Search Console?

No, GSC es la fuente de datos primordial. El módulo necesita un mínimo de 60 a 90 días de historial para producir predicciones fiables y calcular la estacionalidad. Si su tienda acaba de lanzarse, espere a tener al menos 2 meses de datos indexados antes de instalar el módulo.

¿Cuánto cuesta un brief IA?

Depende del proveedor elegido. Con Mistral (defecto), cuente alrededor de 0,002 € por brief. OpenAI GPT-4o-mini alrededor de 0,005 €. Claude Haiku alrededor de 0,004 €. Usted proporciona su propia clave API y paga directamente al proveedor — DataFirefly no cobra ninguna comisión.

¿Cuántas palabras clave puede rastrear el módulo?

No hay límite codificado. Una sync estándar recupera hasta 250 000 filas (fecha × consulta × página) por llamada — lo que cubre casi la totalidad de las tiendas. Más allá, aumente la memoria PHP asignada al worker cron.

¿Es el módulo compatible con otros módulos SEO?

Sí, Predictive SEO nunca escribe en las páginas de productos o en las meta — solo lee GSC y produce recomendaciones. Es totalmente compatible con todos los módulos SEO existentes (DataFirefly o de terceros).

¿Mis datos GSC se almacenan en DataFirefly?

No. Todos los datos permanecen en su servidor, en su base de datos PrestaShop. El módulo llama directamente a la API de Google con sus credenciales OAuth, y llama directamente a los proveedores IA con su clave API. Ningún dato transita por los servidores DataFirefly.

¿Qué horizonte de predicción es el más fiable?

El horizonte 7-14 días es muy fiable (intervalo 95% estrecho). El horizonte 30-60 días es indicativo (intervalo ensanchado). Más allá de 90 días, las predicciones se vuelven poco útiles para decisiones operativas — el módulo las calcula pero muestra una confianza baja.