Widget de assinatura

O widget de assinatura é um aviso e um sino de lançamento que convidam os visitantes do site a se inscreverem para receber notificações push, configurados juntos como subscriptionWidget, mas ativados de forma independente: só o aviso, só o sino, ou ambos ao mesmo tempo. Ativar qualquer um dos dois substitui o botão de inscrição para Push, o Popup de Inscrição Personalizado e os widgets de solicitação de assinatura — enquanto pelo menos uma das partes estiver ativada, nenhum desses três widgets mais antigos é carregado na página.

Um visitante que ainda não decidiu vê o pedido do aviso. 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.

1. Ativar o aviso e o sino

Adicione o parâmetro subscriptionWidget à inicialização do WebSDK e defina prompt.enabled e/ou launcher.enabled como true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

Sem um único interruptor de nível superior

O campo subscriptionWidget.enable de nível superior não é lido. Definir apenas esse campo não ativa nada. Veja Migrando dos widgets antigos abaixo.

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. Os formulários do Painel de Controle descritos mais adiante validam cada campo e se recusam a salvar um valor inválido.

2. Configurar o aviso e o sino

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      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
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    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 exibir o aviso

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 — nunca abre por temporizador. Defina junto com launcher.enabled: true para que um clique no sino possa abri-lo. A API manual o abre de qualquer forma, independentemente desta configuração ou de o sino estar ativado.
• 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 para um visitante que ainda pode agir sobre o pedido (ainda não inscrito, ou bloqueado), independentemente do aviso e de display.trigger. O sino permanece na tela enquanto o aviso está aberto. launcher.position o posiciona em um dos quatro cantos. launcher.offset define sua distância das bordas, em pixels.

O efeito de um clique no sino depende do aviso. Se prompt.enabled for true, o clique alterna o aviso: abre-o ou, se já estiver aberto, fecha-o. Se o aviso estiver desativado, o clique solicita a permissão diretamente ao navegador, como Pushwoosh.subscribe() — a menos que o visitante já tenha bloqueado as notificações; nesse caso, o clique não faz nada.

launcher.width e launcher.height definem o tamanho do sino em pixels (16–200, padrão 48 cada). launcher.imageUrl desenha uma imagem no lugar do botão redondo do sino. launcher.background e launcher.iconColor definem a cor de preenchimento e a cor do glifo do botão redondo. Se não forem definidos, launcher.background usa por padrão a cor de destaque da paleta, e launcher.iconColor uma cor de glifo calculada para contrastar com ela.

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. Os formulários do Painel de Controle validam cada um deles, e também launcher.background/launcher.iconColor, dessa forma, até 64 caracteres. O snippet de inicialização aceita qualquer string não vazia para colors.* sem verificar formato ou comprimento. Para launcher.background/launcher.iconColor, não verifica nenhum dos dois, mas corta silenciosamente o valor em 64 caracteres.

Nota

Uma paleta de modo escuro, launcher.zIndex e uma fontFamily personalizada estão disponíveis como campos adicionais apenas de parâmetros de inicialização. Eles não são expostos nos formulários do Painel de Controle descritos abaixo.

Gerenciando-o no Painel de Controle

Apenas para aplicativos gerenciados pelo painel

Os cartões do Painel de Controle estão disponíveis apenas para aplicativos com a plataforma Web no modo gerenciado pelo painel (veja Web Push SDK 3.0). Para um aplicativo configurado por snippet, defina subscriptionWidget no snippet de inicialização como mostrado acima.

Em um aplicativo gerenciado pelo painel, vá para Settings → Configure platforms → Web. O aviso e o sino são dois cartões separados ali, cada um com seu próprio selo On/Off e botão Configure:

• Subscription invitation edita o aviso: Invitation (layout, posição, ícone), When to show (gatilho, atraso, limite de exibições), Texts e Colors.
• Subscription bell edita o sino de lançamento: posição, URL da imagem, largura/altura, cor de fundo e do ícone, e seus próprios textos de dica de ferramenta.

O botão Configure de cada cartão abre uma prévia ao vivo ao lado do formulário. A prévia não desenha nada enquanto o interruptor do próprio cartão estiver desativado. Depois de ativado, um menu suspenso acima da prévia alterna entre o pedido para o visitante indeciso e a explicação para o visitante bloqueado. Salvar um cartão substitui apenas a sua metade da cópia da configuração do widget no painel — as configurações do outro cartão e o snippet de inicialização do WebSDK em seu site não são afetados.

Enquanto um aplicativo estiver gerenciado pelo painel, os valores salvos em qualquer um dos cartões substituem as mesmas chaves no snippet de inicialização do site.

3. Controlar o aviso a partir do seu código

Assim que o pacote do widget for carregado, ele publica uma API em Pushwoosh.moduleRegistry.subscriptionWidget:

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() e toggle() não têm efeito enquanto prompt.enabled for false, nem para um visitante que já se inscreveu. Abrir o aviso dispara um evento show-subscription-widget. Fechá-lo dispara hide-subscription-widget:

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.prompt.enabled e subscriptionWidget.launcher.enabled do site permanecerem ambos indefinidos ou false. Ativar qualquer um dos dois interrompe o carregamento dos três, tanto em um aplicativo configurado por snippet quanto em um gerenciado pelo painel.

Cuidado

Uma versão anterior do widget usava um único interruptor de nível superior subscriptionWidget.enable em vez de prompt.enabled/launcher.enabled separados. Esse formato não é mais lido. Um snippet que ainda define apenas enable: true agora desativa o widget por completo: nem o aviso nem o sino desenham nada, o WebSDK registra no console uma dica com os dois campos a definir e os três widgets mais antigos são carregados como se subscriptionWidget nunca tivesse sido definido. Alternar um aplicativo gerenciado pelo painel para o novo widget também não transfere as configurações de qualquer widget antigo que ele substitui — cada cartão começa com seus próprios padrões.