# Popup Pro Newsletter: guia completo

> O Popup Pro Newsletter apresenta na sua loja Shopware um popup de inscrição na newsletter que recompensa cada novo subscritor com um código promocional válido na primeira encomenda. O objetivo…

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

O Popup Pro Newsletter apresenta na sua loja Shopware um popup de inscrição na newsletter que recompensa cada novo subscritor com um código promocional válido na primeira encomenda. O objetivo é duplo: fazer crescer a sua lista de envio e desencadear uma primeira venda. A extensão assenta exclusivamente no sistema de **promoções nativo do Shopware**, sem criar qualquer entidade de base de dados própria, e oferece dois modos de código (único por subscritor ou fixo), um desconto configurável em percentagem ou em montante, acionadores por atraso e por scroll, e uma inscrição através da rota de newsletter oficial com duplo opt-in opcional conforme ao RGPD. Este guia cobre a instalação, a configuração, o funcionamento dos códigos promocionais, a personalização e a resolução de problemas. Compatível com Shopware 6.6 e 6.7.

O storefront do Shopware deixou de compilar o JavaScript das extensões na hora desde a 6.6. O ZIP que instala **tem de conter a pasta dist/ do JS pré-compilado**. O ZIP distribuído pela DataFirefly já a inclui; se reconstruir a extensão por si próprio, leia com atenção a secção Instalação abaixo.

## Como funciona o código promocional

No primeiro registo de um visitante, a extensão cria automaticamente uma **promoção Shopware** chamada «Popup Newsletter — Welcome», atribuída ao canal de venda atual, com o desconto definido na configuração. Depois, a cada inscrição:

- em modo de **código único** (recomendado), é gerado na hora um código individual, associado à promoção através dos _códigos individuais de promoção_ nativos do Shopware, e devolvido ao visitante: não partilhável, rastreável e limitável a uma única utilização;
- em modo de **código fixo**, a promoção tem um único código público (do tipo `WELCOME10`) apresentado a todos os subscritores.

A promoção mantém-se inteiramente controlável em **Marketing → Promoções**: período de validade, condições, regras avançadas. Para reservar a oferta à primeira encomenda, mantenha a opção «uma utilização por cliente» ativa; para uma segmentação mais estrita, acrescente uma regra Shopware (por exemplo «número de encomendas do cliente = 0») diretamente na promoção.

## Instalação

1. Transfira o arquivo `DataFireflyPopupProNewsletter-v1.0.0.zip` a partir da sua conta DataFirefly.
2. Instale-o em **Administração → Extensões → As minhas extensões → Carregar extensão**, ou copie a pasta descomprimida para `custom/plugins/`.
3. Instale e ative a extensão: ``` bin/console plugin:refresh bin/console plugin:install --activate DataFireflyPopupProNewsletter bin/console cache:clear ```
4. Compile o tema para integrar os estilos do popup: ``` bin/console theme:compile ```

O `theme:compile` é PHP puro: funciona num alojamento partilhado. Em contrapartida, a **compilação do JavaScript** (`build-storefront.sh`) exige Node e muita memória, e não foi feita para o partilhado. É por isso que o JS é entregue pré-compilado no ZIP: nunca tem de executar o build no seu servidor de produção.

### Se reconstruir a extensão por si próprio

Numa instalação Shopware de desenvolvimento completa, o JS compila-se assim:

```
bin/console plugin:refresh
bin/console plugin:install --activate DataFireflyPopupProNewsletter
bash bin/build-storefront.sh
```

Isto gera `src/Resources/app/storefront/dist/storefront/js/data-firefly-popup-pro-newsletter/data-firefly-popup-pro-newsletter.js`. Volte a comprimir a extensão **com** essa pasta `dist/` antes de a implementar em produção.

## Configuração

Abra **Extensões → As minhas extensões → Popup Pro Newsletter → ⋯ → Configurar**. As definições estão organizadas em cartões.

### Geral

- **Ativar o popup**: ativa ou desativa completamente a apresentação.

### Apresentação

- **Apresentar após um atraso (segundos)**: o popup aparece ao fim de X segundos. `0` desativa este acionador.
- **Apresentar após scroll (% da página)**: o popup aparece quando essa percentagem de scroll é atingida. `0` desativa este acionador.
- **Não voltar a apresentar durante (dias)**: frequência de apresentação por visitante, memorizada no navegador.
- **Ocultar para clientes com sessão iniciada**: não apresenta o popup aos clientes já com sessão iniciada.

Os dois acionadores (atraso e scroll) são cumuláveis: o popup aparece assim que o _primeiro_ dos dois é atingido. Para um acionamento apenas por scroll, coloque o atraso a `0`, e vice-versa.

### Conteúdo

Título, subtítulo, placeholder do campo de email, texto do botão, mensagem de sucesso (use o marcador `%code%` para inserir o código), mensagem de espera de confirmação (duplo opt-in), URL de ilustração opcional e cor de destaque. Todos estes textos são editáveis e traduzíveis.

### Código promocional

- **Modo de código**: `único` (recomendado) ou `fixo`.
- **Código fixo / prefixo**: o código público em modo fixo, ou o prefixo dos códigos individuais em modo único.
- **Tipo e valor do desconto**: percentagem ou montante fixo, valor livre.
- **Uma utilização por cliente**: limita a promoção a uma única utilização para reservar a oferta à primeira encomenda.
- **Duplo opt-in**: envia um email de confirmação antes de entregar o código.

## Duplo opt-in e RGPD

A inscrição passa pela rota de newsletter oficial do Shopware (`NewsletterSubscribeRoute`), o que garante a sincronização com os seus destinatários existentes. Quando o duplo opt-in está ativo, o visitante só recebe o código depois de confirmar o endereço por email; entretanto, a mensagem de espera personalizável aparece no popup. Não é usado qualquer cookie de terceiros: a memorização «não voltar a apresentar» é guardada no navegador através do `localStorage`.

O duplo opt-in é recomendado para a conformidade com o RGPD: atesta o consentimento explícito do subscritor. Pode ativá-lo ou desativá-lo a qualquer momento na configuração.

## Personalizar o popup

A renderização está isolada em `views/storefront/component/datafirefly/popup-newsletter.html.twig`, injetada a partir de `views/storefront/base.html.twig` no bloco `base_body`. Para alterar a estrutura do popup, sobreponha esse template no seu tema. Os estilos estão em `app/storefront/src/scss/base.scss` e a cor de destaque é controlada pela variável CSS `--df-popup-accent`, alimentada pela definição «cor de destaque» da configuração. O comportamento (acionadores, AJAX, cópia do código) é gerido pela extensão de storefront `PopupNewsletterPlugin`.

## FAQ e resolução de problemas

**O popup não aparece de todo.** Na quase totalidade dos casos, é porque o JavaScript pré-compilado não está presente: verifique que o ZIP instalado contém mesmo a pasta `dist/`, depois execute `theme:compile` e limpe a cache. Inspecione a página: o elemento `.df-popup-newsletter` tem de estar presente no DOM com o atributo `hidden`; é o JS que o revela.

**Fechei-o uma vez e não volta a aparecer.** É o comportamento esperado: a extensão memoriza o fecho durante o número de dias configurado, através da chave `dfPopupNewsletterDismissedAt` do `localStorage`. Para voltar a testar, abra uma janela de navegação privada ou limpe o armazenamento local do navegador.

**O popup aparece mas sem estilos.** O tema não foi recompilado: execute `bin/console theme:compile`.

**O código não é aplicado ao carrinho.** Verifique em **Marketing → Promoções** que a promoção «Popup Newsletter — Welcome» está ativa, atribuída ao canal de venda certo e dentro do período de validade. Em modo único, confirme que o código individual ainda não foi usado.

**O que acontece na desinstalação?** A promoção e os códigos já distribuídos são deliberadamente conservados, para não invalidar códigos em circulação entre os seus clientes. Elimine-os manualmente em Marketing → Promoções se for necessário.

**A extensão torna a minha loja mais lenta?** Não: sem entidades próprias, sem consultas adicionais no carregamento das páginas, um único ficheiro JS leve e SCSS compilado no seu tema.