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 a Google Indexing API e permite adicionar URLs a uma fila central de submissões. A fila é processada pelo cron do Magento, e cada submissão é validada, deduplicada, sujeita a limites e registada em logs.

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

• JobPosting,
• BroadcastEvent incorporado em VideoObject.

A utilização da API para produtos, categorias, páginas CMS ou publicações 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 submissão de URLs, e não como substituto de sitemap XML, canonicals corretos, robots, hreflang, ligações internas 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 Magento funcional,
• possibilidade de instalar o pacote google/apiclient,
• acesso administrativo ao Magento,
• projeto Google Cloud com Indexing API ativada,
• propriedade no Google Search Console verificada para o domínio da loja,
• conta de serviço Google adicionada como proprietário 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 deverá instalá-lo automaticamente.

3. Instalação do módulo

3.1. Instalação via Composer

Adicione o repositório Composer Kowal ao projeto Magento:

Os dados de acesso ao repositório Composer (endereço de e-mail do cliente e token de licença) serão enviados por e-mail após a compra. Também estão disponíveis no painel do cliente depois de iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.

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

Configure os dados de acesso ao repositório Composer Kowal:

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

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, deverão estar disponíveis no painel de administração:

• 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 devem ser criadas as tabelas:

• kowal_google_indexing_queue,
• kowal_google_indexing_api_log.

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

4.1. Criação do projeto Google Cloud

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

Indexing API

Sem a API ativada, o módulo não conseguirá enviar submissões corretamente.

4.2. Criação da 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, pelo menos, 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ário 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 Search Console, o Google poderá devolver erros de permissões, por exemplo falta 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 âmbitos Magento:

• Default Config,
• Website,
• Store View.

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

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á para o Google.

Recomendação:

• durante a primeira configuração, defina No ou deixe Dry Run = Yes,
• após testes corretos, defina Yes.

Dry Run

Predefinição:

Yes

Modo de teste. Quando Dry Run está ativado, o módulo processa registos da fila, guarda estados e logs, mas não envia uma submissão real para o Google.

É o modo mais seguro para a primeira execução, testes de configuração e verificação de que os URLs chegam à fila conforme esperado.

Recomendação:

• execute 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 o valor encriptado na configuração,
• para ambientes com controlo de acesso a ficheiros, o upload do ficheiro JSON pode ser mais conveniente.

Service Account JSON

Visível quando Credentials Source = Encrypted configuration value.

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

O módulo valida o JSON antes de 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 Magento encriptada.

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 a 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 controlador de ficheiros o permitir.

O ficheiro é guardado com um nome dependente do âmbito da 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 tem uma função informativa e de organização da configuração, especialmente quando a loja utiliza 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 teste, se essa separação for adotada no projeto.

8. Secção Queue and Limits

Daily Publish Limit

Predefinição:

200

Define o número máximo de submissões publish que o módulo pode efetuar por dia.

O limitador conta requests do tipo:

• publish,
• publish_dry_run.

Se o limite for utilizado, o processador da fila não recolherá novos registos para envio até à próxima janela diária.

Recomendação:

• deixe 200 se o projeto usar o limite onboarding predefinido 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 estiver utilizado, o cron não processará mais registos nessa execução.

Recomendação:

• para uma implementação típica, deixe o valor predefinido,
• reduza o valor se pretender uma utilização mais conservadora da API,
• não defina 0, salvo se quiser 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, pode aumentar o valor, 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 tempo ao administrador para corrigir conteúdos,
• gerir melhor o limite da API.

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

Manual Form Indexing Lag (minutes)

Predefinição:

15

Define o atraso para URLs adicionados pelo formulário:

Google Indexing API > Import URLs

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

Recomendação:

• defina 0 se a importação manual deve entrar na fila imediatamente,
• deixe 15 se quiser manter um buffer para deduplicação e controlo de submissões.

Mass Action Indexing Lag (minutes)

Predefinição:

15

Define o atraso para URLs adicionados por:

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

Recomendação:

• para operações em massa, deixe 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 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. Depois de exceder 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 nova tentativa de envio após erro temporário.

O cron usa um atraso crescente. O multiplicador depende do número de tentativas e é limitado ao 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 origem permitidos, separados por vírgulas.

Valores suportados:

Se o tipo de origem não estiver na lista, o scheduler ignorará a submissão e assinalá-la-á como skipped.

Recomendação:

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

Allowed URL Hosts

Predefinição:

puste

Lista de hosts de 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 domínio principal, versão www, domínios de store view e domínios linguísticos,
• não adicione domínios de teste à configuração de produção.

Require HTTPS URLs

Predefinição:

Yes

Obriga os URLs submetidos a usar o esquema https.

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

https_required

Recomendação:

• para lojas em produção, deixe 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 eliminaçã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 em formulários de edição.

Recomendação:

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

10. Secção Logs

API Log Retention Days

Predefinição:

90

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

O cron de limpeza de logs é executado diariamente às:

03:15

Remove entradas mais antigas do que o número de dias definido neste campo.

Recomendação:

• 90 dias é um valor razoável para diagnóstico,
• com um grande número 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 credentials.

Se Allowed Hosts mostrar Not configured, o módulo não limita hosts. Tecnicamente pode funcionar, mas em produção recomenda-se inserir 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 escolher o projeto Google Cloud.
2. Ativar a Indexing API e criar a JSON key para a conta de serviço.
3. Colar o JSON ou carregar o ficheiro JSON na configuração 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 ativado.

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

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 incorreta ou danificada,
• 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 o teste URL metadata ou uma submissão real de um URL de teste.

11.4. Test URL Metadata

Formulário:

Test URL Metadata

permite introduzir um URL público de um host permitido e executar um request metadata para a 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 ativado, exige https,
• verifica Allowed URL Hosts, se tiver sido configurado.

Resultados possíveis:

O teste metadata não cria uma nova submissão publish. Serve para diagnóstico da ligação e do estado do URL.

12. Primeira execução passo a passo

Ordem recomendada para a primeira execução:

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. Deixe Dry Run = Yes.
5. Escolha a fonte das 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. Deixe 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 credentials como prontas.
13. Clique em Test Google Credentials.
14. Adicione o service account email como proprietário no Google Search Console, se ainda não o tiver 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 Magento:

bin/magento cron:run

19. Verifique Google Indexing API > Indexing Queue.
20. Verifique Google Indexing API > API Logs.
21. Se tudo 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 contém os campos:

Ações disponíveis:

Após enviar o 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 inclui, entre outros:

• URL,
• hash do URL,
• store ID,
• website ID,
• tipo de origem,
• 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 agendada,
• 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 nos registos da fila

Atenção: Transmit Now executa um request real se Dry Run = No. Com Dry Run = Yes, será guardado um log dry-run sem envio real para o Google.

15. Cron

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

Processamento da fila

kowal_google_indexing_process_queue

Agenda:

*/5 * * * *

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

O processador:

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

Limpeza de logs

kowal_google_indexing_cleanup_logs

Agenda:

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 requests:

17. Mass Actions e botões administrativos

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

Produtos

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

O módulo ignora produtos:

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

Os URLs são gerados com base nos URL rewrites para store view ativas.

Páginas CMS

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

O módulo ignora páginas inativas.

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

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

O módulo adiciona botões de submissão 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 vem 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 danificado durante a colagem.

O Google devolve um 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 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 está a ser processada

Verifique:

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

Os registos passam para retry

Verifique:

• estado HTTP no registo da fila,
• log da API,
• resposta do Google,
• se não ocorre 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 utilizem amasty/blog e precisem de uma ação em massa para publicações de blog.