PS PrestaShop PrestaShop Intermedio

GSC Connect — Documentación

Todo para instalar, configurar y usar GSC Connect: OAuth Google, sitemaps, inspección masiva de URLs, informes clics/posición, alertas de caída y desindexación, cron compatible con compartido.

Actualizado Versión del módulo 1.0.2

GSC Connect trae toda la potencia de Google Search Console directamente al back-office de PrestaShop: conexión OAuth en un clic, envío de sitemaps, inspección masiva de URLs, informes de clics y posición por producto y categoría, alertas automáticas de caída y desindexación. Esta guía cubre la instalación, la configuración OAuth con Google, la primera sincronización, la programación cron, la lectura de informes, la resolución de errores comunes y la arquitectura interna.

Instalación

El módulo se despliega como cualquier módulo estándar de PrestaShop: sin dependencia Composer, sin worker persistente, sin servicio externo aparte de Google.

  1. Descargue dfgscconnect.zip desde su cuenta DataFirefly (enlace de descarga recibido tras la compra).
  2. Back-office → Módulos → Administrador de módulos → Subir un módulo.
  3. Arrastre y suelte el ZIP. PrestaShop instala automáticamente las 8 tablas dfgsc_*, las pestañas del menú y los hooks asociados.
  4. Haga clic en Configurar en la tarjeta del módulo.

Multitienda nativo. El módulo es multitienda. Cada tienda almacena su propio token OAuth, su propia propiedad de Search Console y su propio historial de métricas. Puede conectar una tienda sin afectar a las demás.

Requisitos

  • PrestaShop 8.0.0 a 9.99.99
  • PHP 7.4, 8.0, 8.1, 8.2 u 8.3
  • MySQL 5.6+ o MariaDB 10.3+
  • Extensión PHP curl habilitada (por defecto en todos los alojamientos)
  • Una cuenta de Google que ya tenga acceso propietario o propietario delegado a la propiedad de Search Console de su tienda

Configuración OAuth con Google

El módulo utiliza OAuth 2.0 para acceder a Search Console en nombre del propietario de la tienda. Esta configuración se hace una sola vez y toma unos 5 minutos. No se requiere cuenta de servicio: la autenticación usa directamente la cuenta de Google que ya tiene acceso a su propiedad de Search Console.

Paso 1 — Crear un proyecto en Google Cloud

  1. Vaya a console.cloud.google.com con la cuenta de Google que tiene acceso a Search Console.
  2. Haga clic en el selector de proyecto arriba, luego en Nuevo proyecto.
  3. Nómbrelo por ejemplo prestashop-gsc y créelo.
  4. Seleccione este nuevo proyecto una vez creado.

Paso 2 — Activar la API de Search Console

  1. Menú → APIs y servicios → Biblioteca.
  2. Busque Google Search Console API.
  3. Haga clic en ella y luego en Habilitar.

Paso 3 — Configurar la pantalla de consentimiento

  1. Menú → APIs y servicios → Pantalla de consentimiento OAuth.
  2. Elija External si su cuenta de Google no pertenece a una organización de Google Workspace, sino Internal.
  3. Complete el nombre de la aplicación (por ejemplo GSC Connect), su correo de soporte y el dominio de su tienda.
  4. En la pantalla Scopes, añada el scope https://www.googleapis.com/auth/webmasters (lectura/escritura de Search Console).
  5. En la pantalla Test users, añada su dirección de Google. Mientras la pantalla esté en modo de prueba, esto es suficiente para uso privado: no es necesario enviar la app a verificación por Google.

Paso 4 — Crear las credenciales OAuth

  1. Menú → APIs y servicios → Credenciales.
  2. Crear credenciales → ID de cliente OAuth.
  3. Tipo de aplicación: Aplicación web.
  4. Nombre: GSC Connect (libre).
  5. En Orígenes JavaScript autorizados, añada el dominio de su tienda con HTTPS: https://su-tienda.com.
  6. En URI de redirección autorizada, pegue la URL exacta mostrada en la configuración del módulo PrestaShop (caja URL de redirección OAuth).
  7. Haga clic en Crear. Google muestra un Client ID y un Client Secret.

La URL de redirección debe ser estrictamente idéntica. Incluyendo protocolo (https), subdominio (www o no) y ausencia de barra final. Una sola diferencia y Google bloquea la conexión con redirect_uri_mismatch.

Paso 5 — Introducir las credenciales en PrestaShop

  1. Back-office → módulo → Configurar.
  2. Pegue el Client ID y el Client Secret.
  3. Guarde el formulario. Aparece un botón Conectar con Google.
  4. Haga clic en él. Se le redirige a la página de consentimiento de Google.
  5. Apruebe los permisos, se le redirige de vuelta al back-office de PrestaShop.
  6. La lista de sus propiedades Search Console se obtiene automáticamente: el módulo selecciona por defecto la que coincide con el dominio de su tienda.

Primer lanzamiento

Una vez establecida la conexión OAuth, lance la primera sincronización para repatriar sus datos:

  1. Pestaña Panel de control. La propiedad por defecto ya está seleccionada.
  2. Haga clic en Sincronizar ahora. El módulo recupera los últimos 28 días de datos (clics, impresiones, CTR, posición) a nivel de página y de consulta. Cuente entre 30 segundos y 2 minutos según el volumen de su catálogo.
  3. Pestaña Sitemaps. Los candidatos se detectan automáticamente (/sitemap.xml raíz + patrón *_sitemap.xml generado por el módulo gsitemap de PrestaShop). Haga clic en Enviar junto a cada sitemap relevante.
  4. Pestaña Inspección. Haga clic en Encolar todos los productos activos. La cola se llena al instante. El procesamiento real se hace vía cron respetando la cuota Google de 2000 inspecciones por día.

Latencia de Search Console. Google entrega los datos de Search Analytics con unas 48 h de retraso. Si acaba de conectarse, algunas métricas de ayer o anteayer aún no estarán disponibles. Es normal. El módulo lo tiene en cuenta automáticamente en los cálculos de caídas (ventana móvil con desfase de 2 días).

Panel de control

El panel reúne 8 KPIs sobre 28 días:

  • Clics — total de clics orgánicos en la ventana
  • Impresiones — total de visualizaciones en la SERP
  • CTR medio — porcentaje de clics respecto a impresiones
  • Posición media — posición media ponderada en todas las consultas
  • Alertas no leídas — número de alertas abiertas por tratar
  • Páginas no indexadas — número de páginas inspeccionadas con veredicto FAIL o NEUTRAL de Google
  • Cuota del día — llamadas a la API URL Inspection consumidas frente a la cuota diaria
  • Última sincronización — fecha y hora del último pase cron sync

Bajo los KPIs, un gráfico de evolución de 28 días muestra los clics (línea sólida) y las impresiones (línea discontinua en eje secundario). Chart.js está empaquetado en local, no se carga ninguna dependencia CDN.

A la derecha, el Top 10 productos y el Top 10 categorías clasifican sus páginas por clics con su posición media y CTR. La resolución URL → entidad usa el enrutamiento nativo de PrestaShop: patrón id-slug para productos, link_rewrite para categorías, cms_lang para páginas CMS.

Informes de clics y posición

La pestaña Informes ofrece tres vistas detalladas: Productos, Categorías, Consultas. Cada vista acepta un lookback configurable: 7 / 14 / 28 / 90 días.

Para cada fila obtiene clics, impresiones, CTR y posición media. Haga clic en cualquier cabecera de columna para ordenar (en cliente, instantáneo). La exportación CSV produce un archivo UTF-8 con BOM y separador de punto y coma (compatible Excel nativo), hasta 5000 filas por exportación.

Comparación de ventanas

Para cada producto o categoría listado, el informe también muestra la variación respecto a la ventana anterior de la misma duración. Una caída significativa de posición aparece en rojo, una mejora en verde.

Sitemaps

La pestaña Sitemaps detecta automáticamente los candidatos en su tienda:

  • https://su-tienda.com/sitemap.xml — sitemap raíz
  • https://su-tienda.com/sitemap_index.xml — índice de sitemaps
  • Patrón *_sitemap.xml en la raíz — generado por el módulo gsitemap de PrestaShop, un archivo por tienda y por idioma

Envíe en un clic. El módulo le hace seguimiento de:

  • El número de URLs enviadas (declaradas por su sitemap)
  • El número de URLs realmente indexadas (informadas por Google)
  • El número de errores detectados por Google
  • La fecha de la última descarga por Googlebot

Si Google detecta errores en un sitemap, se genera una alerta automática: severidad HIGH si ≥ 10 errores, sino MEDIUM.

Inspección masiva de URLs

La API URL Inspection de Google está limitada a 2000 llamadas por día por propiedad. GSC Connect gestiona este límite vía una cola con retry automático.

Acciones disponibles

  • Encolar todos los productos activos — añade todos los productos con visibilidad both, search o catalog
  • Encolar todas las categorías — añade todas las categorías activas (la raíz se excluye)
  • Re-inspeccionar las páginas modificadas — añade solo las entidades marcadas como obsoletas por los hooks actionProductUpdate y actionCategoryUpdate
  • Procesar la cola ahora — para pruebas, sin esperar al cron
  • Inspeccionar una URL ad-hoc — para validar una corrección inmediata en una página concreta

Datos registrados

Para cada URL inspeccionada, el módulo registra:

  • El veredicto global de Google: PASS, PARTIAL, FAIL o NEUTRAL
  • El estado de cobertura (Indexed, Discovered, Crawled but not indexed, etc.)
  • El estado robots.txt y la indexabilidad declarada
  • Los resultados enriquecidos detectados (Product, Breadcrumb, Review, etc.)
  • El estado AMP y la conformidad mobile-friendly
  • El sitemap referente y las URLs referentes
  • La fecha del último rastreo por Googlebot

Desindexación detectada → alerta automática. Si el veredicto es FAIL o NEUTRAL, o el estado de cobertura es DEINDEXED o INDEXING_NOT_ALLOWED, se genera una alerta HIGH automáticamente con la razón devuelta por Google.

Alertas y caídas

El módulo gestiona automáticamente tres familias de alertas:

Caídas de posición

Detecta una caída significativa de posición en una página ya bien posicionada. Por defecto: caída de 5 posiciones o más en una página posicionada ≤ 50. Umbral ajustable en la configuración (DFGSC_DROP_POS).

Caídas de clics

Detecta una caída significativa de clics en una página que generaba un volumen mínimo. Por defecto: caída del 30 % con un mínimo de 5 clics en la ventana anterior. Umbrales ajustables en la configuración (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Desindexaciones

Generada automáticamente cuando una URL inspeccionada devuelve un veredicto FAIL o NEUTRAL, o un estado de cobertura DEINDEXED / INDEXING_NOT_ALLOWED.

Mecánica de comparación

La comparación de caídas se hace sobre una ventana móvil de 7 días frente a los 7 días anteriores, con un desfase de 2 días para respetar la latencia de Search Console. El módulo compara D-9..D-2 con D-16..D-9.

Desduplicación 24h

Una misma alerta (misma página, mismo tipo) solo se dispara una vez cada 24h para evitar el ruido, incluso si el cron corre cada hora.

Notificaciones por correo

Las alertas pueden enviarse por correo como digest HTML agrupado por severidad, en francés o inglés. Actívelas desde la configuración e indique la dirección destinataria.

Cron y programación

Todas las tareas en segundo plano pasan por un endpoint único protegido por token, visible en la página de configuración:

https://su-tienda.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Prográmelo cada 1 a 6 horas desde el panel cron de su alojamiento (cPanel, Plesk, o2switch, OVH). Ejemplo crontab:

0 */2 * * * curl -fsS "https://su-tienda.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX" > /dev/null 2>&1

Tareas ejecutadas

Por defecto, el endpoint ejecuta todas las tareas. Puede filtrar algunas con el parámetro &tasks=:

Tarea Acción
sync Recupera nuevos datos de Search Analytics (lookback configurable)
inspect Procesa la cola de inspección URL respetando la cuota
sitemaps Refresca el estado de los sitemaps enviados
drops Detecta caídas de posición y clics
notify Envía el digest de alertas por correo
prune Purga entradas de cola completadas y contadores antiguos de cuota

Ejemplo para sincronizar solo las métricas sin tocar la inspección:

curl "https://su-tienda.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX&tasks=sync,drops,notify"

Compatible con alojamiento compartido. Sin dependencia de Redis, BullMQ, worker persistente o PHP-FPM dedicado. El endpoint cron es una simple URL HTTPS protegida por token. Funciona de forma nativa en o2switch, OVH compartido y cualquier alojamiento Linux estándar.

Configuración de referencia

Todas las opciones están en la página Configurar del módulo:

Opción Clave Defecto
Client ID de Google DFGSC_CLIENT_ID (a rellenar)
Client Secret de Google DFGSC_CLIENT_SECRET (a rellenar)
Lookback de sincronización (días) DFGSC_LOOKBACK_DAYS 28
Cuota diaria de inspección URL DFGSC_DAILY_QUOTA 2000
Umbral caída de posición DFGSC_DROP_POS 5
Umbral caída de clics (%) DFGSC_DROP_CLICKS 30
Clics mínimos para detectar caída DFGSC_DROP_MIN_CLICKS 5
Notificaciones por correo activadas DFGSC_ALERT_ENABLED sí
Dirección destinataria de alertas DFGSC_ALERT_EMAIL correo admin
Token cron DFGSC_CRON_TOKEN auto-generado

Cuotas y límites de la API de Google

La API de Search Console es gratuita pero está sujeta a cuotas Google:

  • URL Inspection: 2000 llamadas al día por propiedad, 600 por minuto (límite duro Google, no negociable)
  • Search Analytics: 25000 filas por llamada, ~1200 llamadas por minuto, 30000 al día (soft cap)
  • Sitemaps: 5000 llamadas al día

El módulo registra todas las llamadas por endpoint y por día en la tabla dfgsc_quota. La cola de inspección se detiene limpiamente cuando se alcanza la cuota configurada, generando una alerta de severidad MEDIUM. Los contadores se purgan automáticamente después de 30 días por la tarea prune.

Arquitectura y datos

El módulo sigue una arquitectura PSR-4 clásica bajo el namespace DataFirefly/GscConnect/, con un autoloader propio entregado en vendor/autoload.php. Sin dependencia Composer. Sin dependencia externa: las llamadas a la API de Google se hacen en cURL nativo con verificación SSL.

Capas

  • Api/ — clientes HTTP (GoogleOAuth, SearchConsoleClient)
  • Model/ — repositorios de acceso a la base (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
  • Services/ — orquestación (MetricsSync, Inspection, Sitemap, Alert)

Tablas creadas

Tabla Rol
dfgsc_token Refresh token OAuth + expiración por tienda
dfgsc_site Propiedades Search Console conocidas (por tienda, con la predeterminada)
dfgsc_metric Filas de Search Analytics (por día, por página, opcionalmente por consulta)
dfgsc_inspection Caché local de inspecciones URL con su veredicto completo
dfgsc_sitemap Estado de los sitemaps enviados (URL, enviadas, indexadas, errores, última descarga)
dfgsc_alert Alertas generadas (tipo, severidad, página, delta, estado)
dfgsc_queue Cola de inspección con estados pending/processing/done/failed
dfgsc_quota Contadores de llamadas API por endpoint y por día

Hooks utilizados

  • actionAdminControllerSetMedia — carga de assets del back-office
  • displayBackOfficeHeader — reservado para notificaciones futuras
  • actionProductUpdate / actionCategoryUpdate — invalidación del caché de inspección
  • actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — purga de inspecciones huérfanas

Seguridad

  • Token CSRF de estado basado en cookie en el flujo OAuth
  • Validación hash_equals en el token cron
  • Refresh token almacenado en BD, nunca registrado
  • Access token nunca persistido: regenerado a demanda desde el refresh token y mantenido en memoria durante la petición
  • Archivos index.php anti-listing en todos los subdirectorios
  • Escapado sistemático vía Tools::safeOutput en todas las salidas de plantillas

Depuración

El botón «Conectar con Google» no aparece

Compruebe que Client ID y Client Secret están guardados. Guarde el formulario, luego recargue la página de configuración.

La pantalla Google muestra redirect_uri_mismatch

La URI de redirección en Google Cloud debe ser estrictamente idéntica a la mostrada en la configuración del módulo: mismo protocolo (https), mismo subdominio (www o no), mismo path, sin barra final. Copie y pegue sin modificar.

La sincronización no devuelve datos

Compruebe tres puntos: (1) la propiedad seleccionada es su tienda; (2) tiene al menos 72 h de historial en Search Console (Google emite con ~48 h de latencia); (3) la cuenta Google conectada tiene acceso propietario o propietario delegado a esta propiedad.

Las inspecciones no se hacen

Compruebe que el cron está programado y se ejecuta. Luego compruebe la cuota del día: si consumió las 2000 llamadas Google, la cola está pausada hasta el día siguiente. Puede forzar manualmente vía el botón Procesar la cola ahora.

Las alertas por correo no llegan

Compruebe que la dirección es válida, que la configuración SMTP de PrestaShop funciona (pruebe con un correo de bienvenida por ejemplo), y que las notificaciones están activadas en la configuración del módulo.

Error 401 o 403 en las llamadas Search Console

El refresh token probablemente fue revocado del lado Google (cambio de contraseña, seguridad de la cuenta, o consentimiento expirado). Desconecte y reconecte la tienda desde la configuración.

Error Quota Exhausted (429)

La cuota Google de la propiedad está alcanzada. Está limitada a 2000 inspecciones al día por Google, independientemente del número de módulos o herramientas que consultan la propiedad. La cola se reanuda automáticamente al día siguiente.

Changelog

Consulte el archivo CHANGELOG.md incluido en el ZIP del módulo para la lista completa de cambios por versión.

Para cualquier pregunta no cubierta aquí, contacte con el soporte DataFirefly en support@datafirefly.com.

¿Te ha resultado útil esta página?

¿Sigues atascado? Contacta con soporte