# GSC Connect — Documentación
> 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…
- Página:
- Idioma: es
- Actualizado el: 2026-06-29
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dfgscconnect/index.md), [en](https://www.datafirefly.com/en/documentation/dfgscconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfgscconnect/index.md), [it](https://www.datafirefly.com/it/documentation/dfgscconnect/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfgscconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfgscconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Índice:
**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](https://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._