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, 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 <strong> 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