Google Indexing API para Magento 2 - instalação e configuração

1. Informações importantes antes da implementação

O módulo integra o Magento 2 com o Google Indexing API e permite adicionar URLs a uma fila central de envios. A fila é processada pelo cron do Magento, e cada envio é validado, deduplicado, sujeito a limites e registado em log.

De acordo com a documentação do Google, o Indexing API destina-se oficialmente principalmente a páginas com dados estruturados:

• JobPosting,
• BroadcastEvent incorporado em VideoObject.

A utilização da API para produtos, categorias, páginas CMS ou artigos de blog não garante indexação nem posições nos resultados de pesquisa. O módulo deve ser tratado como uma ferramenta técnica para enviar URLs, e não como substituto de sitemap XML, canonicals corretos, robots, hreflang, linking interno e qualidade geral de SEO.

Materiais oficiais do 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 da instalação, certifique-se de que o ambiente cumpre os requisitos:

• Magento 2.4.x,
• PHP 8.1 ou mais recente,
• Composer,
• cron do Magento funcional,
• possibilidade de instalar o pacote google/apiclient,
• acesso administrativo ao Magento,
• projeto Google Cloud com Indexing API ativado,
• propriedade no Google Search Console verificada para o domínio da loja,
• conta de serviço Google adicionada como proprietária no Google Search Console.

O módulo requer o pacote:

google/apiclient:^2.16

O pacote está declarado no composer.json do módulo, por isso o Composer deve instalá-lo automaticamente.

3. Instalação do módulo

3.1. Instalação via Composer a partir de repositório VCS

Se o módulo for instalado a partir de um repositório Git privado ou público, adicione o repositório ao projeto Magento:

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

Se o repositório for privado, configure o token GitHub:

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

Instale o pacote:

composer require kowal/module-google-indexing-api

Ative o módulo:

bin/magento module:enable Kowal_GoogleIndexingApi

Execute a atualização do esquema da base de dados:

bin/magento setup:upgrade

Limpe a cache:

bin/magento cache:flush

Em modo de produção, execute adicionalmente:

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

3.2. Instalação local em app/code

Se o módulo for instalado sem Composer como código local, coloque-o no diretório:

app/code/Kowal/GoogleIndexingApi

Em seguida, instale a dependência Google API Client no projeto Magento:

composer require google/apiclient:^2.16

Ative o módulo e execute os comandos padrão do Magento:

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

Para produção:

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

3.3. Verificação da instalação

Verifique se o módulo está ativo:

bin/magento module:status Kowal_GoogleIndexingApi

Após a instalação correta, no painel de administração deverão estar disponíveis:

• Stores > Configuration > Kowal > Google Indexing API,
• menu administrativo Google Indexing API > Indexing Queue,
• Google Indexing API > Import URLs,
• Google Indexing API > API Logs,
• Google Indexing API > Setup Assistant.

Na base de dados deverão ser criadas as tabelas:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

4. Preparação do Google Cloud e Search Console

4.1. Criar o projeto Google Cloud

1. Aceda ao Google Cloud Console.
2. Crie um novo projeto ou selecione um projeto existente usado para a loja.
3. Ative a API:

Indexing API

Sem a API ativada, o módulo não poderá enviar os pedidos corretamente.

4.2. Criar a conta de serviço

1. No Google Cloud, aceda a IAM & Admin > Service Accounts.
2. Crie uma nova conta de serviço.
3. Gere uma chave em formato JSON.
4. Transfira o ficheiro JSON e guarde-o em segurança.

O módulo exige que o JSON contenha, no mínimo, os campos:

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

O campo type deve ter o valor:

service_account

4.3. Adicionar a conta de serviço como proprietária no Search Console

1. Abra o Google Search Console.
2. Selecione a propriedade correspondente ao domínio da loja.
3. Certifique-se de que a propriedade está verificada.
4. Adicione o endereço client_email do ficheiro JSON como proprietário da propriedade.

Exemplo de endereço da conta de serviço:

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

Se a conta de serviço não for proprietária da propriedade do Search Console, o Google poderá devolver erros de permissões, por exemplo, ausência de confirmação de propriedade do URL.

5. Configuração do módulo no Magento

A configuração encontra-se em:

Stores > Configuration > Kowal > Google Indexing API

A configuração suporta os âmbitos do Magento:

• Default Config,
• Website,
• Store View.

Assim, é possível ter definições separadas para diferentes lojas ou vistas de loja, caso o projeto o exija.

6. Secção General

Enable

Predefinição:

No

Ativa ou desativa o funcionamento do módulo.

Quando o campo tem o valor No, o cron não processa a fila. Os endereços podem existir na base de dados, mas o processador da fila não os enviará ao Google.

Recomendação:

• durante a configuração inicial, defina No ou mantenha Dry Run = Yes,
• após testes bem-sucedidos, defina Yes.

Dry Run

Predefinição:

Yes

Modo de teste. Quando Dry Run está ativo, o módulo processa os registos da fila, guarda estados e logs, mas não envia pedidos reais ao Google.

Este é o modo mais seguro para o primeiro arranque, testes de configuração e verificação de que os URLs entram na fila conforme esperado.

Recomendação:

• faça sempre os primeiros testes com Dry Run = Yes,
• desative Dry Run apenas depois de verificar credentials, allowed hosts, fila e logs.

7. Secção Google Access Credentials

Credentials Source

Predefinição:

Encrypted configuration value

Define de onde o módulo obtém o JSON da conta de serviço Google.

Opções disponíveis:

Recomendação:

• para implementações simples pode usar-se o valor cifrado na configuração,
• para ambientes com controlo de acesso a ficheiros, o upload do ficheiro JSON pode ser mais prático.

Service Account JSON

Visível quando Credentials Source = Encrypted configuration value.

Neste campo deve ser colado o conteúdo completo do ficheiro JSON da conta de serviço Google.

O módulo valida o JSON antes de o guardar. São verificados:

• correção do formato JSON,
• presença dos campos type, project_id, private_key, client_email,
• valor type = service_account.

O valor é guardado como configuração cifrada do Magento.

Service Account JSON File

Visível quando Credentials Source = Uploaded JSON file.

Permite carregar o ficheiro JSON da conta de serviço Google.

O módulo:

• aceita apenas ficheiros com extensão .json,
• valida o conteúdo do ficheiro,
• verifica os campos obrigatórios type, project_id, private_key, client_email,
• guarda o ficheiro fora do diretório público, em var/google-indexing,
• tenta definir as permissões do ficheiro para 0600, se o driver de ficheiros o permitir.

O ficheiro é guardado com um nome dependente do âmbito de configuração, por exemplo, para o âmbito global:

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

Google Cloud Project ID

Campo de texto para o identificador do projeto Google Cloud.

Na implementação atual do módulo, a autorização principal baseia-se nos dados do JSON da conta de serviço. O campo Google Cloud Project ID desempenha uma função informativa e ajuda a organizar a configuração, especialmente quando a loja usa vários ambientes ou vários projetos Google Cloud.

Recomendação:

• introduza o valor project_id do ficheiro JSON,
• use projetos Google Cloud separados para ambientes de produção e de teste, caso essa separação exista no projeto.

8. Secção Queue and Limits

Daily Publish Limit

Predefinição:

200

Define o número máximo de envios publish que o módulo pode executar por dia.

O limitador conta requests do tipo:

• publish,
• publish_dry_run.

Se o limite for atingido, o processador da fila não recolherá novos registos para envio até à janela diária seguinte.

Recomendação:

• mantenha 200 se o projeto usar o limite de onboarding padrão do Google,
• aumente o valor apenas se o projeto Google Cloud tiver um limite superior aprovado,
• a definição 0 bloqueia o envio, porque o número de slots disponíveis será 0.

Requests Per Minute Limit

Predefinição:

60

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

O módulo compara este valor com o número de requests guardados nos logs do último minuto. Se o limite por minuto for atingido, o cron não processará mais registos nessa execução.

Recomendação:

• para uma implementação típica, mantenha o valor predefinido,
• reduza o valor se quiser carregar a API de forma mais conservadora,
• não defina 0, a menos que queira parar temporariamente o envio.

Cron Batch Size

Predefinição:

20

Define o número máximo de registos da fila processados numa única execução do cron.

O número real de registos processados é também limitado por:

• Daily Publish Limit,
• Requests Per Minute Limit,
• número de registos prontos para envio,
• estado e data scheduled_at.

Recomendação:

• 20 é um valor inicial seguro,
• em filas grandes, o valor pode ser aumentado, mas apenas tendo em conta os limites do Google.

Default Indexing Lag minutes

Predefinição:

15

Define o atraso predefinido entre a adição de um URL à fila e o momento a partir do qual pode ser enviado.

O atraso ajuda a:

• reduzir duplicados,
• evitar envios após cada pequena alteração,
• dar ao administrador tempo para corrigir conteúdos,
• gerir melhor o limite da API.

Na implementação atual, esta definição é usada quando o envio não tem o seu próprio atraso.

Manual Form Indexing Lag minutes

Predefinição:

15

Define o atraso para URLs adicionados através do formulário:

Google Indexing API > Import URLs

Se o administrador colar manualmente uma lista de URLs, cada endereço válido será agendado com este atraso.

Recomendação:

• defina 0 se a importação manual tiver de entrar imediatamente na fila,
• mantenha 15 se quiser preservar uma margem para deduplicação e controlo dos envios.

Mass Action Indexing Lag minutes

Predefinição:

15

Define o atraso para URLs adicionados através de:

• ações em massa de produtos,
• ações em massa de páginas CMS,
• botões de envio de indexação nos ecrãs de edição de produto, categoria e página CMS.

Recomendação:

• para operações em massa, mantenha o valor 15 ou superior,
• para lojas pequenas e trabalho administrativo manual, pode considerar um valor mais baixo.

Max Attempts

Predefinição:

5

Define o número máximo de tentativas de envio de um único registo da fila.

Se o Google devolver um erro temporário, o módulo definirá o estado retry, desde que o número de tentativas seja inferior a Max Attempts. Após ultrapassar o limite, o registo receberá o estado failed_permanent.

Erros tratados como temporários:

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

Retry Delay minutes

Predefinição:

15

Atraso base antes da próxima tentativa de envio após erro temporário.

O cron usa um atraso progressivo. O multiplicador depende do número de tentativas e está limitado no máximo a 24. Assim, as tentativas seguintes não são executadas de forma demasiado agressiva.

Exemplo para o valor 15:

Allowed Source Types

Predefinição:

manual,product,category,cms_page,amasty_blog_post

Lista de tipos de fonte permitidos, separados por vírgulas.

Valores suportados:

Se o tipo de fonte não estiver na lista, o scheduler ignorará o envio e marcá-lo-á como skipped.

Recomendação:

• mantenha os valores predefinidos se a loja usar todas as fontes padrão,
• remova as fontes que não quer permitir na fila.

Allowed URL Hosts

Predefinição:

vazio

Lista de hosts URL permitidos, separados por vírgulas.

Exemplo:

example.com,www.example.com

Se a lista estiver preenchida, o módulo aceitará apenas endereços pertencentes aos hosts indicados. Se o URL tiver outro host, a validação devolverá o erro:

host_not_allowed

Recomendação:

• em produção, preencha sempre esta lista,
• adicione todos os hosts usados pela loja, por exemplo, o domínio principal, a versão www, domínios de store view e domínios de idioma,
• não adicione domínios de teste à configuração de produção.

Require HTTPS URLs

Predefinição:

Yes

Impõe que os URLs enviados usem o esquema https.

Se o campo estiver ativado, um endereço com http será rejeitado com o erro:

https_required

Recomendação:

• para lojas de produção, mantenha Yes,
• use No apenas em ambientes de teste excecionais.

9. Secção Auto-Indexing

Enable Auto-Indexing

Predefinição:

No

O campo está preparado para integrações automáticas de gravação ou remoção de entidades e providers adicionais de URLs.

No âmbito atual do módulo, estão disponíveis mecanismos manuais e administrativos para adicionar URLs à fila, incluindo importação de URLs, Mass Actions e botões nos formulários de edição.

Recomendação:

• mantenha No se o auto-indexing não tiver sido implementado no projeto,
• ative apenas quando o projeto incluir suporte para eventos automáticos de entidades que usem esta configuração.

10. Secção Logs

API Log Retention Days

Predefinição:

90

Define o número de dias de retenção dos logs da API.

O cron de limpeza de logs corre diariamente às:

03:15

Remove registos mais antigos do que o número de dias definido neste campo.

Recomendação:

• 90 dias é um valor razoável para diagnóstico,
• com um número elevado de requests, pode reduzir a retenção,
• em auditorias SEO, pode aumentar a retenção, tendo em conta o tamanho da tabela de logs.

11. Assistente de instalação e configuração

O assistente encontra-se em:

Google Indexing API > Setup Assistant

O seu objetivo é verificar rapidamente se a configuração do lado do Magento e do Google está pronta para o primeiro teste.

11.1. Secção Current Status

O assistente mostra o estado atual dos elementos mais importantes:

Se Credentials tiver o estado Missing or invalid, deve voltar à configuração e corrigir o JSON ou o ficheiro de credentials.

Se Allowed Hosts mostrar Not configured, o módulo não limita os hosts. Tecnicamente pode funcionar, mas em produção é recomendável indicar explicitamente os hosts da loja.

11.2. Secção Setup Steps

O assistente apresenta a lista de passos necessários antes do primeiro request real:

1. Criar ou selecionar um projeto Google Cloud.
2. Ativar o Indexing API e criar uma JSON key para a conta de serviço.
3. Colar o JSON ou carregar o ficheiro JSON na configuração do Magento.
4. Adicionar o service account email como proprietário no Google Search Console.
5. Executar testes e, em seguida, importar um URL com Dry Run ativo.

O assistente inclui links para:

• Google Cloud para Indexing API,
• configuração do módulo no Magento,
• Google Search Console.

11.3. Test Google Credentials

O botão:

Test Google Credentials

verifica se o Magento consegue usar os dados da conta de serviço para obter um token OAuth para o âmbito:

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

Um resultado positivo significa que:

• o JSON está correto,
• a chave privada pode ser usada,
• o Google emitiu um token OAuth.

Um resultado negativo pode significar:

• JSON incorreto,
• private_key inválido ou corrompido,
• ausência de um campo obrigatório no JSON,
• problema de comunicação com o Google,
• utilização de uma chave que não é uma chave de conta de serviço.

Este teste ainda não confirma que a conta de serviço tem acesso de proprietário ao domínio no Search Console. Para isso, é necessário um teste de URL metadata ou um envio real de um URL de teste.

11.4. Test URL Metadata

O formulário:

Test URL Metadata

permite introduzir um URL público de um host permitido e executar um request metadata ao Google Indexing API.

Antes de enviar o request, o módulo:

• normaliza o URL,
• verifica se o URL é absoluto,
• verifica o esquema http ou https,
• com Require HTTPS URLs ativo, exige https,
• verifica Allowed URL Hosts, se estiverem configurados.

Resultados possíveis:

O teste metadata não cria um novo envio publish. Serve para diagnóstico da ligação e do estado do URL.

12. Primeiro arranque passo a passo

Ordem recomendada para o primeiro arranque:

1. Instale o módulo e execute setup:upgrade.
2. No Magento, aceda a Stores > Configuration > Kowal > Google Indexing API.
3. Defina Enable = Yes.
4. Mantenha Dry Run = Yes.
5. Selecione a origem dos credentials.
6. Cole o JSON da conta de serviço ou carregue o ficheiro JSON.
7. Preencha Google Cloud Project ID com o valor project_id do JSON.
8. Preencha Allowed URL Hosts, por exemplo, example.com,www.example.com.
9. Mantenha os limites predefinidos, se o Google não tiver aprovado limites superiores.
10. Guarde a configuração e limpe a cache.
11. Aceda a Google Indexing API > Setup Assistant.
12. Verifique se o assistente mostra os credentials como prontos.
13. Clique em Test Google Credentials.
14. Adicione o service account email como proprietário no Google Search Console, caso isso ainda não tenha sido feito.
15. Execute Test URL Metadata para um URL público de um host permitido.
16. Aceda a Google Indexing API > Import URLs.
17. Adicione um URL de teste com a ação URL_UPDATED.
18. Execute o cron do Magento:

bin/magento cron:run

19. Verifique Google Indexing API > Indexing Queue.
20. Verifique Google Indexing API > API Logs.
21. Se tudo estiver a funcionar corretamente, desative Dry Run.
22. Adicione novamente um URL de teste e verifique a resposta real do Google.

13. Importação de URLs a partir do painel de administração

A importação manual encontra-se em:

Google Indexing API > Import URLs

O formulário inclui os campos:

Ações disponíveis:

Após o envio do formulário, o módulo mostrará um resumo:

• adicionados,
• atualizados,
• deduplicados,
• inválidos,
• ignorados.

As primeiras 10 mensagens de validação são mostradas como notice no painel de administração.

14. Fila de indexação

A fila encontra-se em:

Google Indexing API > Indexing Queue

Cada registo da fila contém, entre outros:

• URL,
• hash do URL,
• store ID,
• website ID,
• tipo de fonte,
• ID da entidade de origem,
• origem do request,
• ação URL_UPDATED ou URL_DELETED,
• estado,
• prioridade,
• número de tentativas,
• número máximo de tentativas,
• data de envio planeada,
• data de processamento,
• último código de erro,
• último motivo do erro,
• última mensagem de erro,
• resposta do Google,
• informação created_by.

Estados da fila

Ações sobre os registos da fila

Nota: Transmit Now executa um request real se Dry Run = No. Com Dry Run = Yes, será guardado um log dry-run sem envio real ao Google.

15. Cron

O módulo adiciona duas tarefas cron no grupo default.

Processamento da fila

kowal_google_indexing_process_queue

Agendamento:

*/5 * * * *

A tarefa executa o processador da fila a cada 5 minutos.

O processador:

1. Verifica se o módulo está ativado.
2. Liberta bloqueios antigos de registos processing com mais de 30 minutos.
3. Move os registos scheduled para pending se scheduled_at <= now.
4. Verifica os slots disponíveis nos limites diários e por minuto.
5. Recolhe registos pending e retry.
6. Ordena-os por prioridade e data de envio planeada.
7. Envia o request ao Google ou executa dry-run.
8. Guarda a resposta, o estado e o log da API.

Limpeza de logs

kowal_google_indexing_cleanup_logs

Agendamento:

15 3 * * *

A tarefa remove logs da API mais antigos do que o número de dias definido no campo:

API Log Retention Days

16. Logs da API

Os logs estão disponíveis em:

Google Indexing API > API Logs

O log inclui:

• ID do registo da fila,
• store ID,
• tipo de request,
• URL do endpoint,
• payload,
• estado HTTP,
• body da resposta,
• duração do request,
• data de criação do log.

Tipos de request:

17. Mass Actions e botões administrativos

O módulo adiciona mecanismos para enviar URLs a partir do painel de administração.

Produtos

Na grelha de produtos está disponível uma ação em massa que adiciona os URLs dos produtos à fila.

O módulo ignora produtos:

• desativados,
• não visíveis individualmente.

Os URLs são gerados com base em URL rewrites para store view ativos.

Páginas CMS

Na grelha de páginas CMS está disponível uma ação em massa que adiciona os URLs das páginas à fila.

O módulo ignora páginas inativas.

Se a página CMS estiver atribuída a todos os store view, o módulo resolve os URLs para todos os store view.

Produto, categoria e página CMS - botões no formulário de edição

O módulo adiciona botões de envio de indexação nos ecrãs de edição de:

• produto,
• categoria,
• página CMS.

O botão resolve os URLs da entidade para store view e adiciona-os à fila como URL_UPDATED.

18. Configuração inicial recomendada

Para a primeira implementação em produção:

19. Problemas comuns e diagnóstico

Credentials test failed

Verifique:

• se o JSON está correto,
• se o JSON provém de uma conta de serviço,
• se contém private_key e client_email,
• se o campo type tem o valor service_account,
• se o ficheiro JSON não foi corrompido ao ser colado.

O Google devolve erro de permissões

Verifique:

• se o domínio está verificado no Search Console,
• se o client_email da conta de serviço foi adicionado como proprietário,
• se o URL testado pertence à mesma propriedade do Search Console,
• se está a usar o projeto Google Cloud correto e o JSON correto.

O URL é rejeitado antes do envio

Verifique a mensagem de validação:

A fila não é processada

Verifique:

• se Enable = Yes,
• se o cron do Magento está a funcionar,
• se os registos têm estado pending ou retry,
• se scheduled_at não está no futuro,
• se os limites diários ou por minuto não foram atingidos,
• se Daily Publish Limit e Requests Per Minute Limit não estão definidos como 0.

Os registos passam para retry

Verifique:

• o estado HTTP no registo da fila,
• o log da API,
• a resposta do Google,
• se não existe o limite 429,
• se não existem erros temporários 5xx,
• se Max Attempts e Retry Delay estão definidos conforme esperado.

20. Integração opcional com Amasty Blog

A integração com Amasty Blog está prevista como módulo separado:

Kowal_GoogleIndexingApiAmastyBlog

Pacote:

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

Este módulo não é necessário para o funcionamento da integração principal. Deve ser instalado apenas em projetos que usem amasty/blog e precisem de ação em massa para artigos de blog.