# Carrossel de Avaliações Google para Shopware 6: instalação, configuração e utilização

> 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),…

- Página: <https://www.datafirefly.com/pt/documentation/carrousel-avis-google-shopware/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/carrousel-avis-google-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/carrousel-avis-google-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/carrousel-avis-google-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/carrousel-avis-google-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/carrousel-avis-google-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/carrousel-avis-google-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/carrousel-avis-google-shopware/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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:clear
```

A 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

1. Aceda a `console.cloud.google.com` e crie (ou selecione) um projeto.
2. Em _APIs e serviços_, ative a **API Places**.
3. Em _Credenciais_, crie uma chave de API e copie-a.
4. 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-cache
```

Ambos 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:test` para 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/log` para 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 DfGoogleReviews
```

Se optar por eliminar os dados na desinstalação, toda a configuração (chaves `DfGoogleReviews.config.*`) é automaticamente limpa.