# Widget de assinatura O **widget de assinatura** é um sino de lançamento mais um aviso que convida os visitantes do site a se inscreverem para receber notificações push. Ele substitui o [botão de inscrição para Push](/pt/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/), o [Popup de Inscrição Personalizado](/pt/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) e os widgets de [solicitação de assinatura](/pt/developer/guides/messaging-channels/subscription-prompt/) em um único componente. Enquanto está habilitado, nenhum desses três é carregado na página, então os visitantes nunca veem dois pedidos concorrentes. Um visitante que ainda não decidiu vê o pedido. Um visitante que já bloqueou notificações vê, em vez disso, uma explicação de como desbloqueá-las. ## Pré-requisitos Certifique-se de ter implementado o Pushwoosh Web SDK 3.0 em seu site. Para isso, siga nosso [guia de integração](/pt/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration). ## 1. Habilitar o widget Adicione o parâmetro `subscriptionWidget` à inicialização do WebSDK e defina `enable` como `true`: ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, } }]); ``` Todos os campos abaixo são opcionais. Um campo omitido usa seu valor padrão. No snippet de inicialização, um número fora do intervalo é silenciosamente limitado ao limite mais próximo, e um valor de enum inválido volta silenciosamente ao seu padrão, sem aviso no console. O formulário do Painel de Controle descrito mais adiante rejeita um valor inválido diretamente e se recusa a salvá-lo. ## 2. Configurar o aviso ```javascript Pushwoosh.push(['init', { //... subscriptionWidget: { enable: true, prompt: { layout: 'card', // 'card' | 'bar' | 'modal' position: 'bottom-right', iconUrl: 'https://url-image.png', borderRadius: 12, // 0–32 overlay: false, }, launcher: { enabled: true, position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' offset: 20, // 0–100 size: 48, // 32–80 }, display: { trigger: 'auto', // 'auto' | 'launcher' | 'manual' delay: 5, // seconds, 0–3600 cappingCount: 3, // auto-shows per visitor, 0–100, 0 = unlimited cappingInterval: 24, // hours between auto-shows, 0–8760 }, texts: { title: 'Stay in the loop', message: 'Get notified about news and updates.', acceptText: 'Allow', declineText: 'Not now', closeText: 'Close', blockedTitle: 'Notifications are blocked', blockedMessage: 'Enable notifications in your browser settings to stay updated.', launcherLabel: 'Subscribe to notifications', launcherBlockedLabel: 'Notifications are blocked', }, colors: { background: '#ffffff', accent: '#4285f4', text: '#000000', textSecondary: '#666666', }, } }]); ``` ### Layout e posição `prompt.layout` define o formato do aviso: - **`card`** — um cartão compacto ancorado a uma borda ou canto. `prompt.position` aceita `top`, `bottom`, `top-left`, `top-right`, `bottom-left` ou `bottom-right`. - **`bar`** — uma barra que ocupa toda a largura da página. `prompt.position` aceita apenas `top` ou `bottom`. - **`modal`** — uma janela centralizada na página. `prompt.position` é sempre `center`. Consulte a lista acima para saber qual layout você definiu antes de escolher uma posição. No snippet de inicialização, uma posição não suportada pelo layout atual é silenciosamente substituída pelo padrão do layout. O formulário do Painel de Controle rejeita essa combinação em vez disso. ### Quando exibi-lo `display.trigger` controla o que abre o aviso: - **`auto`** — abre automaticamente `display.delay` segundos após o carregamento da página, depois novamente a cada `display.cappingInterval` horas se o visitante não decidiu, até `display.cappingCount` vezes no total (`0` significa sem limite). - **`launcher`** — abre apenas quando o visitante clica no sino. - **`manual`** — abre apenas através de `Pushwoosh.moduleRegistry.subscriptionWidget`, descrito abaixo. `display.delay`, `display.cappingCount` e `display.cappingInterval` aplicam-se apenas ao gatilho `auto`. ### O sino de lançamento `launcher.enabled` exibe um sino flutuante enquanto o visitante não estiver inscrito, independentemente de `display.trigger` — mesmo com `trigger: 'auto'`, o sino permanece visível para que o visitante possa reabrir o aviso após fechá-lo. `launcher.position` o posiciona em um dos quatro cantos. `launcher.offset` (deslocamento em pixels das bordas) e `launcher.size` (o diâmetro do sino em pixels) ajustam finamente o posicionamento. ### Textos e cores `texts.blockedTitle`, `texts.blockedMessage` e `texts.closeText` são exibidos no lugar do pedido assim que o navegador relata que o visitante bloqueou as notificações — `texts.acceptText` e `texts.declineText` nunca aparecem nesse estado. `texts.launcherLabel` e `texts.launcherBlockedLabel` são a dica de ferramenta do sino em cada estado. Cada campo de texto aceita até 300 caracteres. `colors.accent`, `colors.background`, `colors.text` e `colors.textSecondary` aceitam um valor hexadecimal ou um nome de cor CSS. O formulário do Painel de Controle valida cada campo dessa forma, até 64 caracteres. O snippet de inicialização aceita qualquer string não vazia para esses campos sem verificar seu formato ou comprimento. ## Gerenciando-o no Painel de Controle Em um aplicativo gerenciado pelo painel, vá para **Settings → Configure platforms → Web** e abra o cartão **Subscription widget**. Um selo no cartão mostra se o widget está **On** ou **Off**. Clique em **Configure** para editar os mesmos campos descritos acima, agrupados como **Prompt**, **When to show**, **Bell**, **Texts** e **Colors**, ao lado de uma prévia ao vivo que mostra tanto o estado do visitante indeciso quanto o do visitante bloqueado. Salvar substitui a cópia da configuração do widget no painel. Isso não afeta o snippet de inicialização do WebSDK em seu site. Enquanto um aplicativo estiver gerenciado pelo painel, os valores salvos neste cartão substituem as mesmas chaves no snippet de inicialização do site. Mover um site para a configuração do painel é um interruptor no painel, sem alteração de código no site. ## 3. Controlar o widget a partir do seu código Assim que o pacote do widget for carregado, ele publica uma API em `Pushwoosh.moduleRegistry.subscriptionWidget`: ```javascript Pushwoosh.moduleRegistry.subscriptionWidget.show(); // Opens the prompt Pushwoosh.moduleRegistry.subscriptionWidget.hide(); // Closes the prompt Pushwoosh.moduleRegistry.subscriptionWidget.toggle(); // Toggles the current state Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true); // Opens the prompt Pushwoosh.moduleRegistry.subscriptionWidget.isVisible(); // Returns whether the prompt is open ``` `show()` não tem efeito para um visitante que já se inscreveu. Abrir o aviso dispara um evento `show-subscription-widget`. Fechá-lo dispara `hide-subscription-widget`: ```javascript Pushwoosh.addEventHandler('show-subscription-widget', function() { console.log('Triggered event: show-subscription-widget'); }); Pushwoosh.addEventHandler('hide-subscription-widget', function() { console.log('Triggered event: hide-subscription-widget'); }); ``` ## Migrando dos widgets antigos O botão de inscrição para Push, o Popup de Inscrição Personalizado e a solicitação de assinatura continuam funcionando conforme documentado em suas próprias páginas enquanto `subscriptionWidget.enable` permanecer indefinido ou `false`. Defini-lo como `true` interrompe o carregamento dos três, tanto em um aplicativo configurado por snippet quanto em um gerenciado pelo painel.