Carrossel de Avaliações Google para Shopware 6: instalação, configuração e utilização
Guia completo para instalar, configurar e apresentar o carrossel de avaliações Google no Shopware 6.5, 6.6 e 6.7: chave de API, Place ID, posição, temas, cache e comandos de consola.
A extensão Carrossel de Avaliações Google apresenta as avaliações Google do seu estabelecimento num carrossel responsivo no storefront do Shopware 6. Gera automaticamente a marcação Schema.org (LocalBusiness, AggregateRating e Review), coloca as avaliações em cache e oferece dois temas integrados. Não é necessário qualquer build de administração: instala-se em qualquer alojamento, incluindo partilhado.
Pré-requisitos
- Shopware 6.5.x, 6.6.x ou 6.7.x
- PHP 8.1 ou superior
- Uma chave de API Google Cloud com a API Places ativada (gratuita até um volume elevado de pedidos)
- O Place ID do seu estabelecimento Google
Instalação
Carregue o arquivo ZIP em Extensões > As minhas extensões > Carregar extensão, ou copie a pasta DfGoogleReviews para custom/plugins/. Depois execute:
bin/console plugin:refresh
bin/console plugin:install --activate DfGoogleReviews
bin/console cache:clearA extensão aparece então em Extensões > As minhas extensões, pronta a configurar.
Obter a chave de API e o Place ID
Chave de API Google
- Aceda a
console.cloud.google.come crie (ou selecione) um projeto. - Em APIs e serviços, ative a API Places.
- Em Credenciais, crie uma chave de API e copie-a.
- Recomendado: restrinja a chave à API Places e ao seu domínio.
Place ID
Use o Place ID Finder da Google (documentação da Google Maps Platform) para obter o identificador do seu estabelecimento. Tem o aspeto ChIJ....
Configuração
Abra Extensões > As minhas extensões > Carrossel de avaliações Google > Configurar. Todas as definições são geridas por canal de venda: selecione o sales channel em causa no topo da página antes de configurar.
Ligação à Google
- Ativar o carrossel: interruptor principal.
- Chave de API Google: a sua chave com a API Places ativada.
- Place ID: o identificador do seu estabelecimento.
- Idioma das avaliações: código de idioma (por exemplo
pt,de,en) transmitido à API para os textos e as datas relativas. Deixe vazio para a predefinição da Google.
Apresentação
- Posição: Página inicial (acima do rodapé), Todas as páginas, ou Manual (ver secção seguinte).
- Título: título do carrossel (vazio = título traduzido por predefinição, fornecido em 5 idiomas).
- Tema: Light ou Dark.
- Deslocação automática e intervalo (em milissegundos): pausa automática ao passar o rato e ao receber foco.
- Número máximo de avaliações: até 10 (a API da Google devolve 5 no máximo).
- Nota mínima: apresenta apenas as avaliações acima do limiar (por exemplo 4 para manter só as de 4 e 5 estrelas).
Cache
- Tempo de vida da cache: de 1 hora a 7 dias (24 horas recomendado).
Apresentar o carrossel
Modo automático
Com a posição Página inicial ou Todas as páginas, o carrossel insere-se automaticamente acima do rodapé. Não é necessária qualquer alteração ao tema.
O modo automático passa pelo bloco base_footer. Se um tema personalizado sobrepuser completamente esse bloco sem chamar parent(), use o modo manual abaixo.
Modo manual (include Twig)
Escolha a posição Manual e insira o componente onde quiser no seu tema storefront:
{% sw_include '@DfGoogleReviews/storefront/component/df-google-reviews.html.twig' %}É ideal para colocar as avaliações numa página CMS específica, numa Shopping Experience ou num ponto concreto do seu layout.
Comandos de consola
Dois comandos facilitam a manutenção:
# Testar a ligação à API e pré-visualizar as avaliações (cache ignorada)
bin/console df:google-reviews:test
# Limpar a cache das avaliações
bin/console df:google-reviews:clear-cacheAmbos aceitam a opção --sales-channel-id=... para visar a configuração de um canal de venda específico. O comando de teste mostra o nome do estabelecimento, a nota global e a lista de avaliações devolvidas, o que é prático para validar a chave de API e o Place ID antes da publicação.
SEO e Schema.org
A cada apresentação, a extensão injeta uma marcação JSON-LD completa: LocalBusiness (nome, nota global), AggregateRating (média e número total de avaliações) e um bloco Review por avaliação. Esta marcação pode fazer aparecer as estrelas nos resultados do Google (rich snippets). Como o conteúdo é renderizado do lado do servidor, as avaliações mantêm-se legíveis para os robots de indexação e para os utilizadores sem JavaScript; o carrossel é apenas uma melhoria progressiva.
Desempenho
O CSS (cerca de 2 KB) e o JavaScript (cerca de 2 KB, Vanilla JS) são injetados apenas nas páginas onde o carrossel aparece. Sem bibliotecas de terceiros, sem jQuery. As chamadas à API Google Places são colocadas na cache de objetos do Shopware segundo a duração configurada.
Degradação suave: se a API da Google estiver momentaneamente indisponível, as últimas avaliações válidas em cache continuam a ser apresentadas. O storefront nunca fica partido por causa do widget.
Resolução de problemas
- O carrossel não aparece: verifique que a extensão está ativa, que a caixa «Ativar o carrossel» está marcada, e que a chave de API e o Place ID estão preenchidos. Execute
bin/console df:google-reviews:testpara diagnosticar. - Erro de API: confirme que a API Places está ativada na Google Cloud e que a chave não está demasiado restringida. Consulte
var/logpara os detalhes. - As avaliações não se atualizam: limpe a cache com
bin/console df:google-reviews:clear-cache(de qualquer forma, a API da Google só devolve as 5 avaliações mais recentes). - Modo automático invisível num tema personalizado: passe para o modo manual e acrescente o include Twig.
Desinstalação
Desative e desinstale a extensão a partir de Extensões > As minhas extensões, ou com:
bin/console plugin:uninstall DfGoogleReviewsSe optar por eliminar os dados na desinstalação, toda a configuração (chaves DfGoogleReviews.config.*) é automaticamente limpa.