# Contador de Vendas Shopware 6: guia de instalação e configuração > Este guia cobre a instalação, a configuração e a personalização da extensão DfSalesCounter, que apresenta em cada página de produto o número de vezes que o produto já foi vendido,… - Página: - Idioma: pt - Atualizado em: 2026-09-02 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/compteur-ventes-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/compteur-ventes-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/compteur-ventes-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/compteur-ventes-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/compteur-ventes-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/licznik-sprzedazy-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/compteur-ventes-shopware/index.md) - Índice: Este guia cobre a instalação, a configuração e a personalização da extensão **DfSalesCounter**, que apresenta em cada página de produto o número de vezes que o produto já foi vendido, a partir das encomendas reais da sua loja Shopware 6. ## Pré-requisitos - Shopware 6.5.x, 6.6.x ou 6.7.x em instalação auto-alojada. O Shopware Cloud (SaaS) não aceita extensões de servidor. - PHP 8.1 ou superior. - Um tema storefront derivado do tema Storefront do Shopware, ou um tema personalizado que mantenha os blocos Twig normais do bloco de compra. - Recomenda-se acesso à linha de comandos para a compilação do tema, mas a instalação pela administração também funciona. ## Instalação ### Por carregamento de ZIP na administração 1. Na administração do Shopware, abra _Extensões_ e depois _As minhas extensões_. 2. Clique em _Carregar extensão_ e selecione o ficheiro `DfSalesCounter-1.0.0.zip`. 3. Quando a extensão aparecer na lista, clique em _Instalar_ e ative-a com o interruptor. 4. Recompile o tema em _Conteúdos_, _Temas_, selecionando o seu tema e depois _Recompilar o tema_. Este passo é necessário uma única vez, porque a extensão fornece uma folha de estilos para o storefront. ### Por linha de comandos Coloque a pasta `DfSalesCounter` em `custom/plugins/` da sua instalação e execute: ``` bin/console plugin:refresh bin/console plugin:install --activate DfSalesCounter bin/console theme:compile bin/console cache:clear ``` Num ambiente com pipeline de deploy, a compilação do tema costuma já fazer parte dos passos normais. ## Configuração A página de configuração encontra-se em _Extensões_, _As minhas extensões_, botão _..._ à direita de DataFirefly Sales Counter, e depois _Configurar_. O seletor no topo da página permite escolher o canal de venda a que a configuração se aplica: cada canal pode ter o seu próprio limiar, o seu próprio texto e a sua própria posição. ### Separador Geral - **Ativar o contador de vendas**: interruptor principal. Desativado, nenhuma consulta é executada e nenhum selo é renderizado. - **Modo de contagem**: _Quantidade vendida_ soma todas as quantidades encomendadas do produto. _Número de encomendas_ conta as encomendas distintas que incluíram o produto. O primeiro modo destaca o volume, o segundo o número de clientes diferentes convencidos. - **Encomendas consideradas**: _Todas as encomendas_ dá o número bruto. _Excluir as encomendas canceladas_ afasta aquelas cuja máquina de estados está em `cancelled`. _Apenas encomendas pagas_ mantém só as encomendas com uma transação em estado `paid` ou `paid_partially`. - **Limiar mínimo antes de apresentar**: abaixo deste valor, nenhum selo aparece. O valor predefinido é 5. Um limiar de 0 é tratado como 1, o selo nunca é renderizado para um produto sem vendas. - **Período em dias**: limita a contagem aos últimos X dias, com base na data da encomenda. O valor 0 significa um acumulado desde sempre. - **Somar as vendas de todas as variantes**: acumula as vendas do produto principal e de todas as suas variantes. Recomendado num catálogo de moda ou por tamanhos, a desativar se cada variante corresponder a um uso distinto. - **Contar apenas as encomendas do canal de venda atual**: evita que uma loja B2B ou um canal de exportação inflacione os números apresentados na loja para o público geral. ### Separador Apresentação - **Posição na página de produto**: _Sob o nome do produto_, _Sob o preço_, ou _Sob o bloco de compra_, ou seja no fundo do bloco, por baixo do botão de adicionar ao carrinho. - **Estilo visual**: _Selo_ renderiza uma pílula com contorno, _Texto simples_ renderiza uma linha sem moldura, _Faixa_ renderiza um bloco de largura total com uma barra lateral colorida. - **Ícone**: chama, carrinho, visto, ou nenhum. Os ícones são SVG renderizados inline, não é carregada qualquer fonte de ícones. - **Cor de destaque**: deixada vazia, é usada a cor primária do tema. Preenchida, alimenta a variável CSS `--df-sales-counter-accent` no elemento do selo. - **Separador de milhares**: espaço fino, vírgula, ponto ou nenhum. Útil assim que os contadores ultrapassam o milhar. - **Texto personalizado**: ver a secção seguinte. - **Duração da cache em segundos**: 900 por predefinição. O valor 0 desativa a cache e consulta a base de dados a cada apresentação da página. ## Personalizar o texto ### Texto global a partir da configuração O campo _Texto personalizado_ aceita uma frase com o marcador `%count%` no sítio onde o número deve aparecer. Exemplo: `Este modelo já saiu %count% vezes este mês`. Este texto é comum a todos os idiomas do canal de venda. É limpo antes da renderização, o que permite uma marcação simples como `` mas bloqueia qualquer script. ### Textos por idioma através dos snippets Deixe o campo _Texto personalizado_ vazio para controlar o texto idioma a idioma. Abra _Definições_, _Loja_, _Snippets_, e pesquise `dfSalesCounter`. Estão disponíveis quatro chaves: - `dfSalesCounter.badge.quantitySingular` e `dfSalesCounter.badge.quantityPlural`, usadas em modo quantidade vendida. - `dfSalesCounter.badge.ordersSingular` e `dfSalesCounter.badge.ordersPlural`, usadas em modo número de encomendas. Cada valor aceita o marcador `%count%`. As traduções francesa, inglesa, espanhola, alemã e italiana são entregues com a extensão. Um valor alterado no gestor de snippets prevalece sobre o da extensão, inclusive após uma atualização. ## Como o número é calculado A extensão lê as linhas de encomenda do tipo produto, ligadas à encomenda e ao seu estado. O cálculo é feito numa única consulta agregada, sem processamento em segundo plano e sem tabela dedicada. - Em modo quantidade, a consulta soma a coluna das quantidades das linhas de encomenda. - Em modo encomendas, conta os identificadores de encomenda distintos. - Só é considerada a versão atual das encomendas, as versões de trabalho criadas numa nota de crédito ou numa alteração de encomenda são ignoradas. - Com a soma das variantes ativa, a extensão resolve primeiro a família do produto apresentado, produto principal e variantes, e depois filtra sobre o conjunto dos identificadores. Se o resultado for inferior ao limiar configurado, nenhuma extensão é acrescentada ao produto e o template não renderiza nada. O selo não existe portanto no HTML, o que evita qualquer apresentação residual através de uma regra CSS do tema. ## Cache e atualidade do número O resultado é guardado no pool de cache aplicacional do Symfony, sob uma chave que combina o identificador do produto, o canal de venda e uma assinatura das opções que influenciam o cálculo. Uma alteração do modo de contagem, do âmbito das encomendas, do período ou das opções de soma muda essa assinatura e invalida portanto mecanicamente os valores anteriores. A cada encomenda feita, a extensão limpa a cache dos produtos contidos nessa encomenda, e também a do respetivo produto principal. O contador reflete assim a venda sem esperar pela expiração da duração configurada. Num catálogo de dimensão modesta, a duração da cache pode ser reduzida a 0 sem consequências de relevo: a consulta incide sobre colunas indexadas. Num catálogo grande com muito tráfego, mantenha uma duração de vários minutos. ## Personalização avançada da renderização A extensão sobrepõe o buy-widget da página de produto e acrescenta o seu selo em três blocos Twig normais, consoante a posição escolhida: o bloco do nome do produto, o bloco do contentor de preço e o bloco do contentor de compra. O próprio selo é renderizado por um template de componente dedicado, `storefront/component/df-sales-counter/badge.html.twig`, que expõe dois blocos sobreponíveis para o ícone e para o texto. A partir de um tema ou de uma extensão, a extensão de entidade fica acessível em Twig no produto da página sob o nome `dfSalesCounter`. Expõe o número em bruto, o número formatado, a posição, o estilo, o ícone, a cor de destaque, o texto personalizado e o modo de contagem. Pode assim renderizar o contador noutro sítio que não o bloco de compra, por exemplo num separador de informações do produto, obtendo a extensão e incluindo o componente. Os estilos estão definidos em `Resources/app/storefront/src/scss/base.scss` em torno das classes `df-sales-counter`, `df-sales-counter__icon` e `df-sales-counter__text`, com um modificador por estilo visual. Qualquer regra do seu tema compilada depois da da extensão prevalece, sem que seja necessário alterar a extensão. ## Resolução de problemas ### Nenhum selo aparece Verifique por ordem: a extensão está ativa, o interruptor de ativação está em sim para o canal de venda certo, o produto atingiu o limiar configurado, e o âmbito de encomendas escolhido não exclui todas as suas encomendas. Um limiar de 5 com o âmbito _Apenas encomendas pagas_ numa loja de testes cujas encomendas nunca são marcadas como pagas nunca produzirá qualquer apresentação. ### O selo aparece sem estilo O tema não foi recompilado depois da ativação. Execute `bin/console theme:compile` ou use o botão de recompilação na administração. ### O número parece congelado A duração da cache ainda está a decorrer. Limpe a cache aplicacional com `bin/console cache:pool:clear cache.app`, ou reduza temporariamente a duração a 0 para validar o cálculo. ### O selo não fica no sítio certo Um tema muito personalizado pode ter removido ou renomeado os blocos Twig do bloco de compra. Experimente outra posição na configuração, ou inclua o componente manualmente no seu template obtendo a extensão do produto. ## Atualização e desinstalação Uma atualização faz-se carregando o novo ZIP e clicando em _Atualizar_, seguido de uma recompilação do tema se a versão contiver alterações de estilo. A configuração é conservada. Na desinstalação, uma caixa propõe conservar os dados do utilizador. Desmarcada, o conjunto das chaves de configuração da extensão é eliminado. A extensão não cria qualquer tabela e não executa qualquer migração, pelo que a desinstalação não deixa nada na base de dados para além da sua configuração. ## Referência das chaves de configuração Todas as chaves têm o prefixo `DfSalesCounter.config.` e podem ser manipuladas pela Admin API ou pelo comando `system:config:set`: - `active`, booleano - `countMode`, valores `quantity` ou `orders` - `orderScope`, valores `all`, `notCancelled` ou `paid` - `minThreshold`, inteiro - `periodDays`, inteiro - `aggregateVariants`, booleano - `scopeToSalesChannel`, booleano - `position`, valores `afterName`, `afterPrice` ou `afterBuy` - `style`, valores `badge`, `inline` ou `banner` - `icon`, valores `none`, `flame`, `cart` ou `check` - `accentColor`, cadeia hexadecimal - `thousandSeparator`, valores `space`, `comma`, `dot` ou `none` - `customText`, cadeia - `cacheTtl`, inteiro em segundos