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

1. Información importante antes de la implementació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 se procesa mediante el cron de Magento, y cada envío se valida, se deduplica, se somete 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,
• BroadcastEventintegrado enVideoObject.

Utilizar la API para productos, categorías, páginas CMS o entradas de blog no garantiza la indexación ni posiciones en resultados de búsqueda. El módulo es una herramienta técnica para notificar URL, no un sustituto del sitemap XML, canonical correctos, robots, hreflang, enlaces internos y 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 funcionando,
• posibilidad de instalar el paquetegoogle/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 propietario en Google Search Console.

El módulo requiere el paquete:

google/apiclient:^2.16

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

3. Instalación del módulo

3.1. Instalación mediante Composer

Añade el repositorio Composer de Kowal al proyecto Magento:

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, la dirección de correo electrónico del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.store

Configura los datos de acceso al repositorio Composer de Kowal:

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"

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 la 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:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3.2. Instalación local enapp/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

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

bin/magento module:enable Kowal_GoogleIndexingApi
bin/magento setup:upgrade
bin/magento cache:flush

Para producción:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/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ónGoogle 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 Google Cloud

1. Accede a Google Cloud Console.
2. Crea un nuevo proyecto 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 solicitudes correctamente.

4.2. Creación de una cuenta de servicio

1. En Google Cloud, ve aIAM & 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 campotype debe tener el valor:

service_account

4.3. Incorporación de la cuenta de servicio como propietario 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ónclient_emaildel archivo JSON como propietario 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 de 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 independientes para distintas tiendas o vistas de tienda, si el proyecto lo requiere.

6. Sección General

Enable

Valor predeterminado:

No

Activa o desactiva el funcionamiento del módulo.

Cuando el campo tiene el valorNo, 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, estableceNoo dejaDry Run = Yes,
• después de realizar pruebas correctas, estableceYes.

Dry Run

Valor predeterminado:

Yes

Modo de prueba. CuandoDry Runestá activado, el módulo procesa los registros de la cola, guarda estados y logs, pero no envía una solicitud real a Google.

Es el modo más seguro para el primer arranque, las pruebas de configuración y la comprobación de si las URL llegan a la cola según lo esperado.

Recomendación:

• realiza siempre las primeras pruebas conDry Run = Yes,
• desactivaDry Runsolo después de comprobar credentials, allowed hosts, la cola y los logs.

7. Sección Google Access Credentials

Credentials Source

Valor predeterminado:

Encrypted configuration value

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

Opciones disponibles:

Recomendación:

• para implementaciones 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 cuandoCredentials Source = Encrypted configuration value.

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

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

• la corrección del formato JSON,
• la presencia de los campostype,project_id,private_key,client_email,
• el valortype = service_account.

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

Service Account JSON File

Visible cuandoCredentials Source = Uploaded JSON file.

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

El módulo:

• acepta únicamente archivos con la extensión.json,
• valida el contenido del archivo,
• comprueba los campos requeridostype,project_id,private_key,client_email,
• guarda el archivo fuera del directorio público, envar/google-indexing,
• intenta establecer los permisos del archivo en0600, si el controlador de archivos lo permite.

El archivo se guarda con un nombre que depende 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 campoGoogle Cloud Project IDcumple una función informativa y ayuda a ordenar la configuración, especialmente cuando la tienda utiliza varios entornos o varios proyectos de Google Cloud.

Recomendación:

• introduce el valorproject_iddel archivo JSON,
• usa proyectos de Google Cloud separados para entornos de producción y de prueba, si en el proyecto se ha adoptado esa separación.

8. Sección Queue and Limits

Daily Publish Limit

Valor predeterminado:

200

Determina el número máximo de solicitudes publish que el módulo puede realizar en un 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 tomará más registros para enviarlos hasta la siguiente ventana diaria.

Recomendación:

• deja200si el proyecto utiliza el límite de onboarding predeterminado de Google,
• aumenta el valor solo si el proyecto de Google Cloud tiene aprobado un límite superior,
• el ajuste0bloquea el envío, porque el número de slots disponibles será0.

Requests Per Minute Limit

Valor predeterminado:

60

Determina 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 alcanzado el límite por minuto, el cron no procesará más registros en esa ejecución.

Recomendación:

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

Cron Batch Size

Valor predeterminado:

20

Determina el número máximo de registros de la cola procesados en una 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 fechascheduled_at.

Recomendación:

• 20es 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)

Valor predeterminado:

15

Determina el retraso predeterminado entre la incorporación de 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 el contenido,
• 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)

Valor predeterminado:

15

Determina 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 correcta se programará con este retraso.

Recomendación:

• establece0si la importación manual debe llegar a la cola de inmediato,
• deja15si quieres mantener un margen para la deduplicación y el control de envíos.

Mass Action Indexing Lag (minutes)

Valor predeterminado:

15

Determina el retraso para las URL añadidas mediante:

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

Recomendación:

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

Max Attempts

Valor predeterminado:

5

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

Si Google devuelve un error temporal, el módulo establecerá el estadoretry, siempre que el número de intentos sea menor queMax Attempts. Tras superar el límite, el registro recibirá el estadofailed_permanent.

Errores tratados como temporales:

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

Retry Delay (minutes)

Valor predeterminado:

15

Retraso base 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 como máximo a24. Gracias a ello, los intentos posteriores no se ejecutan de forma demasiado agresiva.

Ejemplo para el valor15:

Allowed Source Types

Valor predeterminado:

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á comoskipped.

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

Valor predeterminado:

puste

Lista de hosts de URL permitidos, separados por comas.

Ejemplo:

example.com,www.example.com

Si la lista está completada, el módulo aceptará únicamente 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 usados por la tienda, por ejemplo, el dominio principal, la versiónwww, dominios de store view y dominios de idioma,
• no añadas dominios de prueba a la configuración de producción.

Require HTTPS URLs

Valor predeterminado:

Yes

Obliga a que las URL notificadas utilicen el esquemahttps.

Si este campo está activado, una dirección conhttp se rechazará con el error:

https_required

Recomendación:

• para tiendas de producción, dejaYes,
• Noutilízalo solo en entornos de prueba excepcionales.

9. Sección Auto-Indexing

Enable Auto-Indexing

Valor predeterminado:

No

El campo está preparado para integraciones automáticas de guardado o eliminación de entidades y para 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 otros, importación de URL, Mass Actions y botones en formularios de edición.

Recomendación:

• dejaNosi auto-indexing no se ha implementado 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

Valor predeterminado:

90

Determina el número de días de conservación de los logs de la API.

El cron de limpieza de logs se ejecuta diariamente a las:

03:15

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

Recomendación:

• 90días es un valor razonable para diagnóstico,
• con un número elevado 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 del lado de 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:

SiCredentialstiene el estadoMissing or invalid, vuelve a la configuración y corrige el JSON o el archivo credentials.

SiAllowed HostsmuestraNot configured, el módulo no limita 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 las pruebas y, a continuación, importar una URL conDry Run.

El asistente contiene enlaces a:

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

11.3. Test Google Credentials

Botón:

Test Google Credentials

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

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

Un resultado positivo significa que:

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

Un resultado negativo puede indicar:

• JSON incorrecto,
• un valor incorrecto o dañado deprivate_key,
• ausencia de un campo obligatorio en el JSON,
• un problema de comunicación con Google,
• uso de una clave que no pertenece a una cuenta de servicio.

Esta prueba todavía no confirma que la cuenta de servicio tenga acceso de propietario al dominio en Search Console. Se requiere una prueba de metadatos URL o una notificación 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 ejecutar un request metadata a Google Indexing API.

Antes de enviar el request, el módulo:

• normaliza la URL,
• comprueba si la URL es absoluta,
• comprueba el esquemahttpohttps,
• conRequire HTTPS URLsactivado, exigehttps,
• compruebaAllowed URL Hosts, si se han configurado.

Resultados posibles:

La prueba 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 ejecutasetup:upgrade.
2. En Magento, ve aStores > Configuration > Kowal > Google Indexing API.
3. EstableceEnable = Yes.
4. DejaDry Run = Yes.
5. Selecciona el origen de las credentials.
6. Pega el JSON de la cuenta de servicio o sube el archivo JSON.
7. CompletaGoogle Cloud Project IDcon el valorproject_iddel JSON.
8. CompletaAllowed URL Hosts, por ejemploexample.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 aGoogle Indexing API > Setup Assistant.
12. Comprueba si el asistente muestra las credentials como listas.
13. Haz clic enTest Google Credentials.
14. Añade el service account email como propietario en Google Search Console, si aún no se ha hecho.
15. EjecutaTest URL Metadatapara una URL pública de un host permitido.
16. Ve aGoogle Indexing API > Import URLs.
17. Añade una URL de prueba con la acciónURL_UPDATED.
18. Ejecuta el cron de Magento:

bin/magento cron:run

13. Importación de URL desde el panel

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 10 primeros 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ónURL_UPDATEDoURL_DELETED,
• estado,
• prioridad,
• número de intentos,
• número máximo de intentos,
• fecha de envío programada,
• fecha de procesamiento,
• último código de error,
• último motivo de error,
• último mensaje de error,
• la respuesta de Google,
• informacióncreated_by.

Estados de la cola

Acciones sobre registros de la cola

Nota:Transmit Nowejecuta un request real siDry Run = No. ConDry Run = Yesse guardará un log dry-run sin envío real a Google.

15. Cron

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

Procesamiento de la cola

kowal_google_indexing_process_queue

Programació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 registrosprocessingcon más de 30 minutos.
3. Mueve los registrosscheduledapendingsischeduled_at <= now.
4. Comprueba los slots disponibles en los límites diario y por minuto.
5. Toma registrospendingyretry.
6. Los ordena por prioridad y fecha de envío programada.
7. Envía el request a Google o ejecuta dry-run.
8. Guarda la respuesta, el estado y el log de la API.

Limpieza de logs

kowal_google_indexing_cleanup_logs

Programación:

15 3 * * *

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

API Log Retention Days

16. Registros API

Los logs están disponibles en:

Google Indexing API > API Logs

El log incluye:

• ID del registro de la 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 requests:

17. Acciones masivas y botones administrativos

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

Productos

En el grid de productos está disponible una acción masiva que añade las URL de productos a la cola.

El módulo omite los productos:

• deshabilitados,
• no visibles individualmente.

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

Páginas CMS

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

El módulo omite las páginas inactivas.

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

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

El módulo añade botones de envío de 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 la store view y las añade a la cola comoURL_UPDATED.

18. Configuración inicial recomendada

Para la primera implementació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 contieneprivate_keyyclient_email,
• si el campotypetiene el valorservice_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,
• siclient_emailde la cuenta de servicio está añadido como propietario,
• si la URL probada pertenece a la misma propiedad de Search Console,
• si estás usando el proyecto de Google Cloud correcto y el JSON correcto.

La URL se rechaza antes del envío

Comprueba el mensaje de validación:

La cola no se procesa

Comprueba:

• siEnable = Yes,
• si el cron de Magento funciona,
• si los registros tienen el estadopendingoretry,
• sischeduled_atno está en el futuro,
• si los límites diario o por minuto no se han agotado,
• siDaily Publish LimityRequests Per Minute Limitno están configurados en0.

Los registros pasan aretry

Comprueba:

• el estado HTTP en el registro de la cola,
• el log de la API,
• la respuesta de Google,
• si no se produce el límite429,
• si no hay errores temporales5xx,
• siMax AttemptsyRetry Delayestá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 únicamente en proyectos que usanamasty/blog y necesitan una acción masiva para entradas de blog.