Google Indexing API para Magento 2 - instalación y configuración

1. Información importante antes de la implantación

El módulo integra Magento 2 con Google Indexing API y permite añadir URL a una cola central de envíos. La cola es procesada por el cron de Magento, y cada envío se valida, se deduplica, está sujeto a límites y se registra.

Según la documentación de Google, Indexing API está destinada oficialmente principalmente a páginas con datos estructurados:

• JobPosting,
• BroadcastEvent incrustado en VideoObject.

El uso de la API para productos, categorías, páginas CMS o entradas de blog no garantiza la indexación ni la posición en los resultados de búsqueda. El módulo debe tratarse como una herramienta técnica para notificar URL y no como un sustituto del sitemap XML, canonical correctos, robots, hreflang, enlazado interno y la calidad general del SEO.

Materiales oficiales de Google:

• https://developers.google.com/search/apis/indexing-api/v3/quickstart
• https://developers.google.com/search/apis/indexing-api/v3/prereqs
• https://developers.google.com/search/apis/indexing-api/v3/using-api
• https://developers.google.com/search/apis/indexing-api/v3/quota-pricing

2. Requisitos

Antes de la instalación, asegúrate de que el entorno cumple los requisitos:

• Magento 2.4.x,
• PHP 8.1 o superior,
• Composer,
• cron de Magento en funcionamiento,
• posibilidad de instalar el paquete google/apiclient,
• acceso administrativo a Magento,
• proyecto de Google Cloud con Indexing API habilitada,
• propiedad en Google Search Console verificada para el dominio de la tienda,
• cuenta de servicio de Google añadida como propietaria en Google Search Console.

El módulo requiere el paquete:

google/apiclient:^2.16

El paquete está declarado en el composer.json del módulo, por lo que Composer debería instalarlo automáticamente.

3. Instalación del módulo

3.1. Instalación mediante Composer desde un repositorio VCS

Si el módulo se instala desde un repositorio Git privado o público, añade el repositorio al proyecto Magento:

composer config repositories.kowal.google.indexing.api vcs https://github.com/kowalco/google-indexing-api

Si el repositorio es privado, configura el token de GitHub:

composer config --global --auth github-oauth.github.com 

Instala el paquete:

composer require kowal/module-google-indexing-api

Activa el módulo:

bin/magento module:enable Kowal_GoogleIndexingApi

Ejecuta la actualización del esquema de base de datos:

bin/magento setup:upgrade

Limpia la caché:

bin/magento cache:flush

En modo producción, ejecuta además:

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.2. Instalación local en app/code

Si el módulo se instala sin Composer como código local, colócalo en el directorio:

app/code/Kowal/GoogleIndexingApi

A continuación, instala la dependencia Google API Client en el proyecto Magento:

composer require google/apiclient:^2.16

Activa el módulo y ejecuta los comandos estándar de Magento:

bin/magento module:enable Kowal_GoogleIndexingApibin/magento setup:upgradebin/magento cache:flush

Para producción:

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3.3. Verificación de la instalación

Comprueba si el módulo está activo:

bin/magento module:status Kowal_GoogleIndexingApi

Tras una instalación correcta, en el panel de administración deberían estar disponibles:

• Stores > Configuration > Kowal > Google Indexing API,
• menú de administración Google Indexing API > Indexing Queue,
• Google Indexing API > Import URLs,
• Google Indexing API > API Logs,
• Google Indexing API > Setup Assistant.

En la base de datos deberían crearse las tablas:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Preparación de Google Cloud y Search Console

4.1. Creación de un proyecto de Google Cloud

1. Accede a Google Cloud Console.
2. Crea un proyecto nuevo o selecciona un proyecto existente usado para la tienda.
3. Habilita la API:

Indexing API

Sin la API habilitada, el módulo no podrá enviar notificaciones correctamente.

4.2. Creación de una cuenta de servicio

1. En Google Cloud, ve a IAM & Admin > Service Accounts.
2. Crea una nueva cuenta de servicio.
3. Genera una clave en formato JSON.
4. Descarga el archivo JSON y guárdalo de forma segura.

El módulo requiere que el JSON contenga al menos los campos:

• type,
• project_id,
• private_key,
• client_email.

El campo type debe tener el valor:

service_account

4.3. Añadir la cuenta de servicio como propietaria en Search Console

1. Abre Google Search Console.
2. Selecciona la propiedad correspondiente al dominio de la tienda.
3. Asegúrate de que la propiedad está verificada.
4. Añade la dirección client_email del archivo JSON como propietaria de la propiedad.

Ejemplo de dirección de cuenta de servicio:

my-service-account@project-name.iam.gserviceaccount.com

Si la cuenta de servicio no es propietaria de la propiedad en Search Console, Google puede devolver errores de permisos, por ejemplo, falta de confirmación de propiedad de la URL.

5. Configuración del módulo en Magento

La configuración se encuentra en:

Stores > Configuration > Kowal > Google Indexing API

La configuración admite los ámbitos de Magento:

• Default Config,
• Website,
• Store View.

Gracias a ello, es posible tener ajustes separados para diferentes tiendas o vistas de tienda, si el proyecto lo requiere.

6. Sección General

Enable

Por defecto:

No

Activa o desactiva el funcionamiento del módulo.

Cuando el campo tiene el valor No, el cron no procesa la cola. Las direcciones pueden existir en la base de datos, pero el procesador de la cola no las enviará a Google.

Recomendación:

• durante la primera configuración establece No o deja Dry Run = Yes,
• tras las pruebas correctas establece Yes.

Dry Run

Por defecto:

Yes

Modo de prueba. Cuando Dry Run está activado, el módulo procesa los registros de la cola, guarda estados y logs, pero no envía una notificación real a Google.

Es el modo más seguro para la primera puesta en marcha, pruebas de configuración y comprobación de que las URL llegan a la cola según lo esperado.

Recomendación:

• realiza siempre las primeras pruebas con Dry Run = Yes,
• desactiva Dry Run solo después de verificar credentials, allowed hosts, cola y logs.

7. Sección Google Access Credentials

Credentials Source

Por defecto:

Encrypted configuration value

Define de dónde obtiene el módulo el JSON de la cuenta de servicio de Google.

Opciones disponibles:

Recomendación:

• para implantaciones sencillas se puede usar el valor cifrado en la configuración,
• para entornos con control de acceso a archivos, puede resultar más cómodo subir el archivo JSON.

Service Account JSON

Visible cuando Credentials Source = Encrypted configuration value.

En este campo hay que pegar el contenido completo del archivo JSON de la cuenta de servicio de Google.

El módulo valida el JSON antes de guardarlo. Se comprueban:

• la validez del formato JSON,
• la presencia de los campos type, project_id, private_key, client_email,
• el valor type = service_account.

El valor se guarda como configuración cifrada de Magento.

Service Account JSON File

Visible cuando Credentials Source = Uploaded JSON file.

Permite subir el archivo JSON de la cuenta de servicio de Google.

El módulo:

• acepta solo archivos con extensión .json,
• valida el contenido del archivo,
• comprueba los campos requeridos type, project_id, private_key, client_email,
• guarda el archivo fuera del directorio público, en var/google-indexing,
• intenta establecer permisos del archivo en 0600, si el controlador de archivos lo permite.

El archivo se guarda con un nombre dependiente del ámbito de configuración, por ejemplo, para el ámbito global:

var/google-indexing/service-account-default-0.json

Google Cloud Project ID

Campo de texto para el identificador del proyecto de Google Cloud.

En la implementación actual del módulo, la autorización principal se basa en los datos del JSON de la cuenta de servicio. El campo Google Cloud Project ID cumple una función informativa y de organización de la configuración, especialmente cuando la tienda utiliza varios entornos o varios proyectos de Google Cloud.

Recomendación:

• introduce el valor project_id del archivo JSON,
• usa proyectos de Google Cloud separados para entornos de producción y de pruebas, si esa separación forma parte del proyecto.

8. Sección Queue and Limits

Daily Publish Limit

Por defecto:

200

Define el número máximo de envíos publish que el módulo puede realizar al día.

El limitador cuenta los requests de tipo:

• publish,
• publish_dry_run.

Si se alcanza el límite, el procesador de la cola no recogerá más registros para enviar hasta la siguiente ventana diaria.

Recomendación:

• deja 200 si el proyecto utiliza el límite onboarding predeterminado de Google,
• aumenta el valor solo cuando el proyecto de Google Cloud tenga aprobado un límite superior,
• el valor 0 bloquea el envío, ya que el número de slots disponibles será 0.

Requests Per Minute Limit

Por defecto:

60

Define el número máximo de requests publish por minuto.

El módulo compara este valor con el número de requests guardados en los logs del último minuto. Si se ha agotado el límite por minuto, el cron no procesará más registros en esa ejecución.

Recomendación:

• para una implantación típica, deja el valor por defecto,
• reduce el valor si quieres cargar la API de forma más conservadora,
• no establezcas 0, salvo que quieras detener temporalmente el envío.

Cron Batch Size

Por defecto:

20

Define el número máximo de registros de la cola procesados en una sola ejecución del cron.

El número real de registros procesados también está limitado por:

• Daily Publish Limit,
• Requests Per Minute Limit,
• el número de registros listos para enviar,
• el estado y la fecha scheduled_at.

Recomendación:

• 20 es un valor inicial seguro,
• con colas grandes se puede aumentar el valor, pero solo teniendo en cuenta los límites de Google.

Default Indexing Lag (minutes)

Por defecto:

15

Define el retraso predeterminado entre añadir una URL a la cola y el momento a partir del cual puede enviarse.

El retraso ayuda a:

• reducir duplicados,
• evitar envíos tras cada pequeño cambio,
• dar al administrador tiempo para corregir contenidos,
• gestionar mejor el límite de la API.

En la implementación actual, este ajuste se utiliza cuando el envío no tiene su propio retraso.

Manual Form Indexing Lag (minutes)

Por defecto:

15

Define el retraso para las URL añadidas mediante el formulario:

Google Indexing API > Import URLs

Si el administrador pega manualmente una lista de URL, cada dirección válida se programará con este retraso.

Recomendación:

• establece 0 si la importación manual debe entrar en la cola de inmediato,
• deja 15 si quieres mantener un margen para la deduplicación y el control de envíos.

Mass Action Indexing Lag (minutes)

Por defecto:

15

Define el retraso para las URL añadidas mediante:

• acciones masivas de productos,
• acciones masivas de páginas CMS,
• botones para solicitar la indexación en las pantallas de edición de producto, categoría y página CMS.

Recomendación:

• para operaciones masivas, deja el valor 15 o superior,
• para tiendas pequeñas y trabajo administrativo manual puede considerarse un valor inferior.

Max Attempts

Por defecto:

5

Define el número máximo de intentos de envío de un registro de cola.

Si Google devuelve un error temporal, el módulo establecerá el estado retry, siempre que el número de intentos sea inferior a Max Attempts. Al superar el límite, el registro recibirá el estado failed_permanent.

Errores tratados como temporales:

• 408,
• 409,
• 412,
• 429,
• 500,
• 502,
• 503,
• 504.

Retry Delay (minutes)

Por defecto:

15

Retraso básico antes del siguiente intento de envío tras un error temporal.

El cron utiliza un retraso creciente. El multiplicador depende del número de intentos y está limitado a un máximo de 24. Gracias a ello, los intentos posteriores no se realizan de forma demasiado agresiva.

Ejemplo para el valor 15:

Allowed Source Types

Por defecto:

manual,product,category,cms_page,amasty_blog_post

Lista de tipos de origen permitidos, separados por comas.

Valores admitidos:

Si el tipo de origen no está en la lista, el scheduler omitirá el envío y lo marcará como skipped.

Recomendación:

• deja los valores predeterminados si la tienda utiliza todas las fuentes estándar,
• elimina las fuentes que no quieras permitir en la cola.

Allowed URL Hosts

Por defecto:

vacío

Lista de hosts de URL permitidos, separados por comas.

Ejemplo:

example.com,www.example.com

Si la lista está completada, el módulo aceptará solo direcciones pertenecientes a los hosts indicados. Si la URL tiene otro host, la validación devolverá el error:

host_not_allowed

Recomendación:

• en producción, completa siempre esta lista,
• añade todos los hosts utilizados por la tienda, por ejemplo, el dominio principal, la versión www, los dominios de store view y los dominios de idioma,
• no añadas dominios de prueba a la configuración de producción.

Require HTTPS URLs

Por defecto:

Yes

Obliga a que las URL notificadas utilicen el esquema https.

Si el campo está activado, una dirección con http será rechazada con el error:

https_required

Recomendación:

• para tiendas en producción, deja Yes,
• usa No solo en entornos de prueba excepcionales.

9. Sección Auto-Indexing

Enable Auto-Indexing

Por defecto:

No

El campo está preparado para integraciones automáticas de guardado o eliminación de entidades y proveedores adicionales de URL.

En el alcance actual del módulo, están disponibles mecanismos manuales y administrativos para añadir URL a la cola, entre ellos importación de URL, Mass Actions y botones en formularios de edición.

Recomendación:

• deja No si auto-indexing no se ha implantado en el proyecto,
• actívalo solo cuando el proyecto incluya soporte para eventos automáticos de entidades que utilicen esta configuración.

10. Sección Logs

API Log Retention Days

Por defecto:

90

Define el número de días durante los que se conservan los logs de la API.

El cron que limpia los logs se ejecuta cada día a las:

03:15

Elimina las entradas más antiguas que el número de días establecido en este campo.

Recomendación:

• 90 días es un valor razonable para diagnóstico,
• con un gran número de requests se puede reducir la retención,
• en auditorías SEO se puede aumentar la retención, teniendo en cuenta el tamaño de la tabla de logs.

11. Asistente de instalación y configuración

El asistente se encuentra en:

Google Indexing API > Setup Assistant

Su objetivo es comprobar rápidamente si la configuración en Magento y Google está lista para la primera prueba.

11.1. Sección Current Status

El asistente muestra el estado actual de los elementos más importantes:

Si Credentials tiene el estado Missing or invalid, hay que volver a la configuración y corregir el JSON o el archivo de credentials.

Si Allowed Hosts muestra Not configured, el módulo no restringe los hosts. Técnicamente puede funcionar, pero en producción se recomienda introducir explícitamente los hosts de la tienda.

11.2. Sección Setup Steps

El asistente muestra la lista de pasos necesarios antes del primer request real:

1. Crear o seleccionar un proyecto de Google Cloud.
2. Habilitar Indexing API y crear una JSON key para la cuenta de servicio.
3. Pegar el JSON o subir el archivo JSON en la configuración de Magento.
4. Añadir el service account email como propietario en Google Search Console.
5. Ejecutar pruebas y luego importar una URL con Dry Run activado.

El asistente contiene enlaces a:

• Google Cloud para Indexing API,
• la configuración del módulo en Magento,
• Google Search Console.

11.3. Test Google Credentials

El botón:

Test Google Credentials

comprueba si Magento puede utilizar los datos de la cuenta de servicio para obtener un token OAuth para el alcance:

https://www.googleapis.com/auth/indexing

Un resultado positivo significa que:

• el JSON es correcto,
• la clave privada puede utilizarse,
• Google ha emitido el token OAuth.

Un resultado negativo puede significar:

• JSON incorrecto,
• private_key errónea o dañada,
• falta de un campo requerido en el JSON,
• problema de comunicación con Google,
• uso de una clave que no es una clave de cuenta de servicio.

Esta prueba todavía no confirma que la cuenta de servicio tenga acceso de propietario al dominio en Search Console. Para ello hace falta la prueba de URL metadata o un envío real de una URL de prueba.

11.4. Test URL Metadata

El formulario:

Test URL Metadata

permite introducir una URL pública de un host permitido y realizar un request de metadata a Google Indexing API.

Antes de enviar el request, el módulo:

• normaliza la URL,
• comprueba si la URL es absoluta,
• comprueba el esquema http o https,
• si Require HTTPS URLs está activado, exige https,
• comprueba Allowed URL Hosts, si se han configurado.

Posibles resultados:

La prueba de metadata no crea un nuevo envío publish. Sirve para diagnosticar la conexión y el estado de la URL.

12. Primera puesta en marcha paso a paso

Orden recomendado para la primera puesta en marcha:

1. Instala el módulo y ejecuta setup:upgrade.
2. En Magento, ve a Stores > Configuration > Kowal > Google Indexing API.
3. Establece Enable = Yes.
4. Deja Dry Run = Yes.
5. Selecciona la fuente de credentials.
6. Pega el JSON de la cuenta de servicio o sube el archivo JSON.
7. Rellena Google Cloud Project ID con el valor project_id del JSON.
8. Rellena Allowed URL Hosts, por ejemplo, example.com,www.example.com.
9. Deja los límites predeterminados si Google no ha aprobado límites superiores.
10. Guarda la configuración y limpia la caché.
11. Ve a Google Indexing API > Setup Assistant.
12. Comprueba si el asistente muestra las credentials como listas.
13. Haz clic en Test Google Credentials.
14. Añade el service account email como propietario en Google Search Console, si aún no se ha hecho.
15. Ejecuta Test URL Metadata para una URL pública de un host permitido.
16. Ve a Google Indexing API > Import URLs.
17. Añade una URL de prueba con la acción URL_UPDATED.
18. Ejecuta el cron de Magento:

bin/magento cron:run

19. Comprueba Google Indexing API > Indexing Queue.
20. Comprueba Google Indexing API > API Logs.
21. Si todo funciona correctamente, desactiva Dry Run.
22. Vuelve a añadir una URL de prueba y comprueba la respuesta real de Google.

13. Importación de URL desde el panel de administración

La importación manual se encuentra en:

Google Indexing API > Import URLs

El formulario contiene los campos:

Acciones disponibles:

Tras enviar el formulario, el módulo mostrará un resumen:

• añadidas,
• actualizadas,
• deduplicadas,
• incorrectas,
• omitidas.

Los primeros 10 mensajes de validación se muestran como notice en el panel de administración.

14. Cola de indexación

La cola se encuentra en:

Google Indexing API > Indexing Queue

Cada registro de la cola contiene, entre otros:

• URL,
• hash de la URL,
• store ID,
• website ID,
• tipo de origen,
• ID de la entidad de origen,
• origen del request,
• acción URL_UPDATED o URL_DELETED,
• estado,
• prioridad,
• número de intentos,
• número máximo de intentos,
• fecha de envío planificada,
• fecha de procesamiento,
• último código de error,
• último motivo de error,
• último mensaje de error,
• respuesta de Google,
• información created_by.

Estados de la cola

Acciones sobre los registros de la cola

Nota: Transmit Now realiza un request real si Dry Run = No. Con Dry Run = Yes se guardará un log de dry-run sin envío real a Google.

15. Cron

El módulo añade dos tareas cron en el grupo default.

Procesamiento de la cola

kowal_google_indexing_process_queue

Planificación:

*/5 * * * *

La tarea ejecuta el procesador de la cola cada 5 minutos.

El procesador:

1. Comprueba si el módulo está activado.
2. Libera bloqueos antiguos de registros processing con más de 30 minutos.
3. Mueve los registros scheduled a pending si scheduled_at <= now.
4. Comprueba los slots disponibles en los límites diario y por minuto.
5. Recoge los registros pending y retry.
6. Los ordena según prioridad y fecha de envío planificada.
7. Envía el request a Google o ejecuta dry-run.
8. Guarda la respuesta, el estado y el log de API.

Limpieza de logs

kowal_google_indexing_cleanup_logs

Planificación:

15 3 * * *

La tarea elimina los logs de API más antiguos que el número de días establecido en el campo:

API Log Retention Days

16. Logs de API

Los logs están disponibles en:

Google Indexing API > API Logs

El log incluye:

• ID del registro de cola,
• store ID,
• tipo de request,
• URL del endpoint,
• payload,
• estado HTTP,
• body de la respuesta,
• duración del request,
• fecha de creación del log.

Tipos de request:

17. Mass Actions y botones administrativos

El módulo añade mecanismos para notificar URL desde el panel de administración.

Productos

En la rejilla de productos hay disponible una acción masiva que añade las URL de productos a la cola.

El módulo omite los productos:

• desactivados,
• no visibles individualmente.

Las URL se generan a partir de URL rewrites para los store view activos.

Páginas CMS

En la rejilla de páginas CMS hay disponible una acción masiva que añade las URL de las páginas a la cola.

El módulo omite las páginas inactivas.

Si una página CMS está asignada a todos los store view, el módulo resuelve las URL para todos los store view.

Producto, categoría y página CMS - botones en el formulario de edición

El módulo añade botones para solicitar la indexación en las pantallas de edición de:

• producto,
• categoría,
• página CMS.

El botón resuelve las URL de la entidad para el store view y las añade a la cola como URL_UPDATED.

18. Configuración inicial recomendada

Para la primera implantación en producción:

19. Problemas habituales y diagnóstico

Credentials test failed

Comprueba:

• si el JSON es correcto,
• si el JSON procede de una cuenta de servicio,
• si contiene private_key y client_email,
• si el campo type tiene el valor service_account,
• si el archivo JSON no se ha dañado al pegarlo.

Google devuelve un error de permisos

Comprueba:

• si el dominio está verificado en Search Console,
• si el client_email de la cuenta de servicio está añadido como propietario,
• si la URL probada pertenece a la misma propiedad de Search Console,
• si estás utilizando el proyecto de Google Cloud correcto y el JSON correcto.

La URL es rechazada antes del envío

Comprueba el mensaje de validación:

La cola no se procesa

Comprueba:

• si Enable = Yes,
• si el cron de Magento está funcionando,
• si los registros tienen estado pending o retry,
• si scheduled_at no está en el futuro,
• si los límites diarios o por minuto no se han agotado,
• si Daily Publish Limit y Requests Per Minute Limit no están configurados como 0.

Los registros pasan a retry

Comprueba:

• el estado HTTP en el registro de la cola,
• el log de API,
• la respuesta de Google,
• si no se está produciendo el límite 429,
• si no hay errores temporales 5xx,
• si Max Attempts y Retry Delay están configurados según lo esperado.

20. Integración opcional con Amasty Blog

La integración con Amasty Blog está prevista como un módulo independiente:

Kowal_GoogleIndexingApiAmastyBlog

Paquete:

kowal/module-google-indexing-api-amasty-blog

Este módulo no es necesario para el funcionamiento de la integración principal. Debe instalarse solo en proyectos que utilicen amasty/blog y necesiten una acción masiva para entradas del blog.