# Galeria de Fotografias de Clientes Comprável: guia completo

> Apresentação A Galeria de Fotografias de Clientes Comprável (dfugcgallery) mostra as fotografias reais dos seus clientes na página inicial e sob as fichas de produto, com hotspots clicáveis que remetem…

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

## Apresentação

A Galeria de Fotografias de Clientes Comprável (`dfugcgallery`) mostra as fotografias reais dos seus clientes na página inicial e sob as fichas de produto, com hotspots clicáveis que remetem para os produtos presentes em cada fotografia. As fotografias provêm de duas fontes: o carregamento pelos seus clientes autenticados (compradores verificados) e a importação das suas publicações Instagram através da API oficial. Tudo passa por uma fila de moderação no back-office, onde coloca também os hotspots de produtos.

As cadeias do front-office (« As minhas fotografias », legendas, caixa de consentimento, botão de partilha) são fornecidas em francês e inglês. Numa loja em português, traduza-as em Internacional → Traduções → Traduções dos módulos instalados, com especial atenção ao texto de consentimento, que deve ser claro para valer como autorização de publicação (RGPD e direito de imagem).

## Instalação

1. No seu back-office PrestaShop, vá a **Módulos → Gestor de módulos → Instalar um módulo**.
2. Selecione o ficheiro `dfugcgallery.zip` e valide.
3. O módulo cria automaticamente as suas duas tabelas de base de dados, o seu separador de administração **Galeria UGC** (em Catálogo) e a sua pasta de armazenamento de imagens protegida.
4. Clique em **Configurar** para abrir as definições.

O módulo é compatível com PrestaShop 8.0 a 8.2 e 9.x, PHP 8.0 no mínimo. Não cria nenhum override e só usa hooks nativos: `displayHome`, `displayFooterProduct`, `displayCustomerAccount` e `displayHeader`.

## Configuração

A página de configuração do módulo reúne todas as definições:

- **Galeria da página inicial**: ativação e número máximo de fotografias apresentadas.
- **Galeria da ficha de produto**: ativação e número máximo de fotografias apresentadas na faixa sob cada ficha.
- **Aprovação automática**: se ativada, os carregamentos dos clientes são publicados imediatamente sem moderação. As importações Instagram passam sempre pela moderação, qualquer que seja esta definição.
- **Tamanho máximo por ficheiro**: em megabytes, aplicado a cada fotografia carregada.
- **Token Instagram**: o token long-lived que permite a importação das suas publicações (ver secção seguinte).

## Ligar o Instagram

A importação usa a API oficial « Instagram API with Instagram Login ». É necessária uma configuração única:

1. Vá ao portal de programadores Meta e crie uma aplicação do tipo Business.
2. Adicione o produto **Instagram** e configure « API setup with Instagram login ».
3. Associe a conta Instagram profissional da sua loja.
4. Gere um **token long-lived** com a permissão `instagram_business_basic`.
5. Cole esse token no campo **Token Instagram** da configuração do módulo e guarde.

O módulo renova o token automaticamente antes de cada importação. Desde que lance uma importação pelo menos uma vez a cada 60 dias, o token nunca expira e não precisa de voltar a tocar-lhe.

Para importar, abra **Catálogo → Galeria UGC** e clique no botão **Importar do Instagram** da barra de ferramentas. O módulo recupera as suas publicações recentes, ignora os duplicados já importados (deduplicação por identificador de média), retém a primeira imagem dos carrosséis e coloca tudo em estado « Pendente ». Os vídeos e Reels são ignorados nesta versão.

## Carregamento pelos seus clientes

Os clientes autenticados dispõem de uma ligação **As minhas fotografias** na sua área de cliente. A página de envio permite-lhes:

- enviar até 5 fotografias por submissão (jpg, png ou webp);
- associar opcionalmente um produto; a lista só propõe os produtos das suas encomendas válidas, o que garante que cada fotografia etiquetada provém de um comprador verificado;
- acrescentar uma legenda;
- consultar o estado das suas fotografias (pendente, aprovada, recusada) e eliminá-las a qualquer momento.

Uma caixa de consentimento explícito é obrigatória antes de qualquer envio. A eliminação pelo cliente apaga os ficheiros do servidor, não só a entrada na base de dados: o módulo foi concebido para a conformidade RGPD.

## Moderação

A lista **Catálogo → Galeria UGC** mostra todas as fotografias com miniatura, fonte (Carregamento ou Instagram), autor, estado e data. Pode:

- filtrar por fonte e por estado;
- aprovar, recusar ou eliminar cada fotografia num clique a partir das ações de linha;
- aplicar estas ações em massa através das caixas de seleção;
- abrir o editor de hotspots através da ação **Ver**.

Só as fotografias aprovadas aparecem na loja.

## Editor de hotspots

O editor permite associar produtos a locais precisos em cada fotografia:

1. Pesquise um produto por nome, referência ou identificador no campo de pesquisa.
2. Selecione-o e depois **clique na fotografia** no local pretendido para colocar o ponto.
3. Arraste e largue um ponto existente para o reposicionar.
4. Elimine um ponto a partir da lista lateral se necessário.
5. Clique em **Guardar** para gravar as posições.

As posições são registadas em percentagem da largura e da altura da imagem: a renderização é idêntica em telemóvel, tablet e desktop. Do lado da loja, cada ponto pulsa discretamente e abre ao clicar um cartão de produto com o nome, o preço atualizado formatado segundo a moeda do visitante, a imagem de capa e uma ligação direta para a ficha.

Quando um cliente etiqueta um produto no carregamento, é criado automaticamente um hotspot no centro da fotografia. Basta-lhe movê-lo para o local certo durante a moderação.

## Apresentação na loja

- **Página inicial**: grelha responsiva com badge a indicar o número de produtos etiquetados por fotografia e botão de apelo à partilha.
- **Ficha de produto**: faixa horizontal das fotografias de clientes ligadas ao produto consultado.
- **Lightbox**: ecrã inteiro, navegação por setas e teclado, hotspots animados, preferência `prefers-reduced-motion` respeitada.

O JavaScript do front-office é vanilla, sem jQuery, e os assets só são carregados nas páginas em causa. As imagens são recodificadas em JPEG em dois tamanhos (1600 px e miniatura de 600 px) para preservar o desempenho.

## Resolução de problemas

- **A importação Instagram falha**: verifique que o token é um token long-lived válido associado a uma conta profissional, e que a permissão de leitura dos média está concedida. Um token expirado (mais de 60 dias sem importação) deve ser regenerado a partir do portal Meta.
- **Uma fotografia carregada é recusada no envio**: verifique o formato (apenas jpg, png, webp) e o tamanho máximo configurado.
- **As fotografias não aparecem na loja**: só as fotografias com estado « Aprovada » são apresentadas; verifique também que a galeria em causa (página inicial ou ficha de produto) está ativada na configuração.
- **Multiloja**: cada loja gere a sua própria galeria; verifique o contexto de loja selecionado no back-office.

## Desinstalação

A desinstalação elimina as tabelas do módulo, o seu separador de administração e a sua configuração. Os ficheiros de imagem da pasta de carregamento são igualmente retirados com as fotografias eliminadas.