Guia completo para configurar notificações Web Push do OneSignal usando integração com código personalizado. Configure o SDK JavaScript, service workers e certificados Safari para Chrome, Firefox, Safari e outros navegadores web.
Use esta configuração com Código Personalizado apenas se você precisar de configuração avançada ou controle programático. Para a maioria dos usuários, recomendamos:
Site com HTTPS: O push web não funciona em HTTP ou em modos de navegação anônima/privada.
Acesso ao servidor: Você precisará fazer upload de um arquivo service worker para o seu site.
Origem única: O push web segue a política de mesma origem. Se você tiver múltiplas origens (domínios/subdomínios), precisará de múltiplos apps OneSignal (um por origem). Para cumprir essa limitação do navegador, você pode:
Redirecionar o tráfego para uma única origem para inscrições.
Site Name: O nome do seu site e o título de notificação padrão.
Site URL: A origem exata do seu site, por exemplo https://yourdomain.com. Evite usar www. se o seu site não estiver configurado dessa forma. Consulte os Requisitos se você tiver múltiplas origens.
Auto Resubscribe: Habilite isso para reinscrever automaticamente os usuários que limpam os dados do navegador quando retornam ao seu site (sem nova solicitação de permissão).
Default Icon URL: Faça upload de uma imagem PNG ou JPG quadrada de 256x256px que aparece em notificações e prompts. Se não definida, um ícone de sino é usado como padrão.
Para testar no localhost, use um app OneSignal separado do seu app de produção e adicione allowLocalhostAsSecureOrigin: true às suas opções de init.Se você estiver testando localhost em HTTPS com um certificado autoassinado, pode ser necessário dizer ao Chrome para ignorar certificados inválidos com --allow-insecure-localhost. Firefox e Safari fornecem mecanismos integrados para adicionar exceções para certificados de segurança.
O OneSignal fornece certificados Safari automaticamente sem custo. Habilite isso apenas se você tiver certificados Safari Web Push existentes que precisa usar.
Opção de upload de certificado Safari para certificados existentes
Se habilitado, faça upload do seu Safari Web .p12 Push Certificate e insira a senha.Clique em Save para continuar.
Na próxima página da configuração de push web, você receberá o arquivo service worker OneSignalSDKWorker.js.O SDK web procura esse arquivo na raiz do seu site por padrão, por exemplo https://yourdomain.com/OneSignalSDKWorker.js. Você pode alterar o local, o nome e o escopo do arquivo no código.
Service worker do OneSignal
Configuração avançada de service worker, integração personalizada e migração de outros provedores.
A Apple começou a oferecer suporte a notificações push web em iPhones e iPads com iOS 16.4+. Ao contrário dos dispositivos Android onde o push web simplesmente “funciona” ao acessar em um navegador compatível, a Apple adicionou alguns requisitos extras, como um arquivo manifest.json e uma ação do usuário para adicionar seu site à tela inicial.
Configuração de push web para iOS
Adicione o arquivo manifest.json necessário e guie os usuários para adicionar seu site à tela inicial.
Use Chrome, Firefox, Edge ou Safari durante os testes.
Não use modo Incógnito ou navegação privada. Usuários não podem se inscrever em notificações push nestes modos.
Os prompts devem aparecer baseados na sua configuração de permission prompts.
Clique em Allow no prompt nativo para se inscrever em notificações push.
Prompt de permissão nativo de web push
2
Verifique seu dashboard OneSignal
Vá para Audience > Subscriptions.
Você deve ver uma nova entrada com o status Subscribed.
Dashboard mostrando inscrição com status 'Subscribed'
Você criou com sucesso uma inscrição de web push.
Inscrições de web push são criadas quando usuários se inscrevem pela primeira vez em notificações push no seu site.
Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.
1
Adicione a Test Users.
No dashboard, próximo à inscrição, clique no botão Options (três pontos) e selecione Add to Test Users.
Adicionando um dispositivo a Test Users
2
Nomeie sua inscrição.
Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois na aba Test Users.
3
Crie um segmento de usuários de teste.
Vá para Audience > Segments > New Segment.
4
Nomeie o segmento.
Nomeie o segmento Test Users (o nome é importante porque será usado depois).
5
Adicione o filtro Test Users e clique em Create Segment.
Criando um segmento 'Test Users' com o filtro Test Users
Você criou com sucesso um segmento de usuários de teste.
Agora podemos testar enviar mensagens para este dispositivo individual e grupos de usuários de teste.
Se todos os passos de configuração foram completados com sucesso, as inscrições de teste devem receber uma notificação.
Apenas Chrome suporta imagens. Imagens aparecerão pequenas na visualização de notificação recolhida. Expanda a notificação para ver a imagem completa.
Notificação push expandida com imagem no Chrome macOS
5
Verifique por entrega confirmada.
No seu dashboard, vá para Delivery > Sent Messages, depois clique na mensagem para ver as estatísticas. Você deve ver a estatística confirmed, significando que o dispositivo recebeu o push.
Safari não suporta Entrega Confirmada.
Relatórios de mensagens de notificação push
Veja estatísticas de entrega, clique e conversão para suas notificações push.
Você enviou com sucesso uma notificação via API para um segmento.
Se as notificações não estiverem chegando, contate support@onesignal.com com o seguinte:
A requisição e resposta da API (copie e cole em um arquivo .txt)
A seção anterior cobriu a criação de Inscrições de web push. Esta seção expande para identificar Usuários através de todas as suas inscrições (incluindo push, email e SMS) usando o OneSignal SDK. Cobre External IDs, tags, inscrições multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários em todas as plataformas.
Use um External ID para identificar usuários consistentemente através de dispositivos, endereços de email e números de telefone usando o identificador de usuário do seu backend. Isso garante que suas mensagens permaneçam unificadas através de canais e sistemas de terceiros (especialmente importante para Integrações).Defina o External ID com o método login do SDK cada vez que um usuário é identificado pelo seu app.
OneSignal gera IDs únicos somente leitura para inscrições (Subscription ID) e usuários (OneSignal ID).À medida que usuários baixam seu app em diferentes dispositivos, se inscrevem no seu website e/ou fornecem endereços de email e números de telefone fora do seu app, novas inscrições serão criadas.Definir o External ID via o SDK é altamente recomendado para identificar usuários através de todas as suas inscrições, independentemente de como elas são criadas.
Tags são pares chave-valor de dados string que você pode usar para armazenar propriedades de usuário (como username, role ou preferências) e eventos (como purchase_date, game_level ou interações de usuário). Tags potencializam Personalização de Mensagem avançada e Segmentação permitindo casos de uso mais avançados.Defina tags com os métodos addTag e addTags do SDK conforme eventos ocorrem no seu app.Neste exemplo, o usuário alcançou o nível 6 identificável pela tag chamada current_level definida com um valor de 6.
Um perfil de usuário no OneSignal com uma tag chamada "current_level" definida como "6"
Podemos criar um segmento de usuários que têm um nível entre 5 e 10, e usar isso para enviar mensagens direcionadas e personalizadas:
Editor de segmento mostrando um segmento direcionado a usuários com um valor current_level maior que 4 e menor que 10
Captura de tela mostrando uma notificação push direcionada ao segmento Nível 5-10 com uma mensagem personalizada
O OneSignal SDK cria inscrições de web push automaticamente quando os usuários optam por receber. Você também pode alcançar usuários através de canais de email e SMS criando as inscrições correspondentes.
Se o endereço de email e/ou número de telefone já existem no app OneSignal, o SDK adicionará ao usuário existente, não criará duplicatas.Você pode visualizar usuários unificados via Audience > Users no dashboard ou com a API View user.
Um perfil de usuário com inscrições push, email e SMS unificadas por External ID
Melhores práticas para comunicação multicanal
Obtenha consentimento explícito antes de adicionar inscrições de email ou SMS.
Explique os benefícios de cada canal de comunicação aos usuários.
Forneça preferências de canal para que usuários possam selecionar quais canais eles preferem.
Use listeners do SDK para reagir a ações de usuário e mudanças de estado.O SDK fornece vários event listeners para você conectar. Veja nosso guia de referência do SDK para mais detalhes.
Sim. Todos os navegadores modernos exigem HTTPS para suporte a notificações push. Se o seu site usa HTTP, você deve migrar para HTTPS antes de configurar o push web.
Posso usar esta configuração com uma aplicação de página única (SPA)?
Sim. A configuração Custom Code é a abordagem recomendada para SPAs construídas com frameworks como React, Angular ou Vue. Consulte os guias específicos por framework no topo desta página para Angular, React e Vue.
O que acontece se um usuário limpar os dados do navegador?
A inscrição push do usuário é removida. Se Auto Resubscribe estiver habilitado, ele será reinscrito automaticamente na próxima vez que visitar seu site.
