Pular para o conteúdo principal

​
Visão geral

Notificações web push permitem enviar atualizações em tempo real, lembretes e mensagens personalizadas para seus usuários, melhorando engajamento e retenção. OneSignal suporta todos os principais navegadores e plataformas, permitindo que você escreva uma vez e entregue através de: Chrome, Firefox, Edge, Safari e outros navegadores suportados.

​
Requisitos

  • Website HTTPS: Web push não funciona em HTTP ou em modos incógnito/privado.
  • Acesso ao servidor: Você precisará fazer upload de um arquivo service worker para seu site.
  • Origem única: Web push segue a política de mesma origem. Se você tem múltiplas origens (domínios/subdomínios), precisará de múltiplos apps OneSignal (um por origem). Para cumprir com esta limitação do navegador, você pode:
    • Redirecionar tráfego para uma origem única para subscriptions.
    • Criar múltiplos apps OneSignal—um por origem.
Se sua equipe já criou uma conta com OneSignal, peça para ser convidado como função de admin para que possa configurar o app. Caso contrário, inscreva-se para uma conta gratuita em onesignal.com para começar!

​
Configure seu app e plataforma OneSignal

No dashboard OneSignal:
  • Vá para Settings > Push & In-App > Web.

Ative a plataforma web nas suas configurações OneSignal

Selecione o tipo de integração:

Site Típico (recomendado)

Gerencie prompts e configurações diretamente através do dashboard OneSignal sem codificação adicional.

WordPress

Necessário se usando WordPress com nosso plugin oficial.

Código Personalizado

Para desenvolvedores que precisam de controle completo sobre prompts e configuração do SDK.

​
Configuração do site

Adicione os detalhes do site:
  • Nome do Site: O nome do seu site e título de notificação padrão.
  • URL do Site: A URL do seu site. Veja URL do Site para mais detalhes.
  • Auto Resubscribe: Habilite isto para reinscrever automaticamente usuários que limpam seus dados de navegador quando retornam ao seu site (nenhum novo prompt de permissão necessário)
  • URL de Ícone Padrão: Faça upload de uma imagem PNG ou JPG quadrada de 256x256px que aparece em notificações e prompts. Se não definido, usamos um sino para o ícone padrão.

Configurações Web no dashboard OneSignal

​
URL do Site

Insira a origem exata do seu site, ex: https://seudominio.com. Evite usar www. se seu site não estiver configurado dessa forma. Se você tem múltiplas origens:
  • Redirecione para uma origem única.
  • Ou configure um app OneSignal por origem.

​
Testes locais

Nosso web SDK pode ser testado em ambientes localhost. Se você está testando em localhost, recomendamos configurar um app OneSignal diferente do seu app de produção.
Defina a URL DO SITE para corresponder exatamente à URL do seu ambiente localhost. Deve ser uma URL localhost comum, exemplos:
  • http://localhost
  • https://localhost:3000
  • http://127.0.0.1
  • https://127.0.0.1:5000
Se seu localhost está usando HTTP, selecione Treat HTTP localhost as HTTPS for testing.Google Chrome trata http://localhost e http://127.0.0.1 como origens seguras, permitindo integrações HTTPS mesmo em HTTP. É por isso que você não pode testar outras origens não-padrão em HTTPS localhost.

Testes locais no dashboard OneSignal

​
Adicione allowLocalhostAsSecureOrigin às suas opções init do OneSignal

Ao inicializar OneSignal no seu site localhost, adicione allowLocalhostAsSecureOrigin: true, às suas opções init do OneSignal.Adicionalmente, se você está testando localhost em HTTPS com um certificado auto-assinado, pode ter que pedir ao Chrome para ignorar certificados inválidos para testes com: --allow-insecure-localhost. Firefox e Safari fornecem mecanismos integrados para adicionar exceções para certificados de segurança.
html
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "YOUR_OS_APP_ID",
        allowLocalhostAsSecureOrigin: true,
      });
    });
  </script>

​
Prompt de permissões

Configuração de site típico permite que você ou seus membros de equipe adicionem, removam e atualizem prompts de permissão através do dashboard OneSignal a qualquer momento.
Para detalhes sobre os prompts de permissão, veja Prompts de Permissão Web.

​
Notificação de boas-vindas (opcional)

Você também pode definir uma notificação de boas-vindas para ser enviada aos usuários quando eles se inscrevem para notificações push.

​
Configurações avançadas

Recursos adicionais configuráveis no dashboard OneSignal.

​
Webhooks

Nosso web SDK fornece a capacidade de fazer POST de certos eventos de web push para uma URL de sua escolha. Web Push Webhooks são uma implementação separada de Event Webhooks e não podem ser usados de forma intercambiável.
Veja Web Push Webhooks para mais detalhes.

​
Service workers

Na próxima página de configuração de web push, você receberá o arquivo service worker OneSignalSDKWorker.js. Nosso web SDK por padrão procura este arquivo na raiz do seu site. Se você quiser mudar a localização, nome e/ou escopo do nosso arquivo service worker, é aqui que você pode atualizar essas configurações.
  • Caminho para arquivos service worker é o caminho para o diretório onde você colocará estes arquivos.
  • Nomes de arquivo service worker principal e atualizador podem ser apenas OneSignalSDKWorker.js ou se você quiser renomear este arquivo. Deve usar extensão de arquivo .js.
  • Escopo de registro do service worker são as páginas nas quais este arquivo pode funcionar. Para notificações push, isso não importa e foi originalmente projetado para casos onde você quer adicionar mais funcionalidade ao arquivo service worker. Você deve definir isso como o mesmo caminho da sua localização.

Configuração de service worker

Com este exemplo, você deve ver o código do arquivo publicamente acessível em https://seudominio.com/push/onesignal/OneSignalSDKWorker.js
Veja OneSignal Service Worker para mais detalhes.

​
Comportamento de clique

Controle como usuários navegam para a URL que você define quando clicam na notificação.
  • Se usuários não têm seu site aberto em nenhuma aba do navegador, e clicam em uma notificação que os leva ao seu site, o navegador abrirá uma nova aba e navegará para a URL da notificação.
  • Se usuários têm seu site aberto em uma ou mais abas do navegador, e clicam em uma notificação que os leva ao seu site, há várias maneiras possíveis que o navegador pode se comportar que você pode configurar:
    • Exact Navigate (padrão) - Se a URL exata da notificação (ex: example.com/product) corresponder a uma aba que o navegador já tem aberta, o navegador navegará para a URL da notificação naquela aba.
    • Origin Navigate - Se a origem da notificação (ex: example.com) corresponder a uma aba que o navegador já tem aberta, o navegador navegará para a URL da notificação naquela aba.
    • Exact Focus - Se a URL exata da notificação (ex: example.com/product) corresponder a uma aba que o navegador já tem aberta, o navegador focará naquela aba, mas não atualizará a página.
    • Origin Focus - Se a origem da notificação (ex: example.com) corresponder a uma aba que o navegador já tem aberta, o navegador focará naquela aba, mas não atualizará a página.

​
Persistência

O comportamento padrão de web push é que eles aparecem no dispositivo por aproximadamente 5 segundos antes de serem movidos para o Centro de Notificações onde são mantidos por cerca de 1 semana antes de serem removidos pelo sistema operacional. Alguns dispositivos e versões do Chrome e Edge permitem persistir notificações por mais tempo na tela. Isso significa que a notificação ficará na tela até que o usuário interaja com ela. Isso pode incomodar seus usuários e não é recomendado. Além disso, se você habilitar persistência, afetará como notificações aparecem para inscritos reduzindo contagem de caracteres e pode afetar como imagens e botões são exibidos. Ao mudá-las, elas entrarão em vigor apenas para inscritos que visitarem o site com as configurações atualizadas. Se você não vir estas opções mudarem, você precisará esperar

​
Certificado Safari (Opcional)

OneSignal fornece automaticamente os certificados necessários para funcionar com navegadores Safari sem custo adicional. Se você já tem seus próprios Certificados Safari Web Push, ative esta opção para fazer upload do seu Safari Web .p12 Push Certificate e senha.

Configuração de certificado Safari

​
Fazer upload do arquivo service worker

Como discutido brevemente acima em Configurações avançadas > Service workers, adicionaremos o arquivo Service Worker OneSignalSDKWorker.js ao seu site.

Passo de upload do arquivo service worker

Se você não definiu o Caminho para arquivos service worker na seção Configurações avançadas > Service workers, você precisará colocar o arquivo OneSignalSDKWorker.js na raiz de nível superior do seu site. Caso contrário, você precisará colocá-lo no diretório que você definiu.
  • Opção 1. Criar arquivo no servidor e copiar código
  • Opção 2. Baixar pasta zip e fazer upload
  1. Crie um novo arquivo chamado OneSignalSDKWorker.js e torne-o público.
  2. Copie e cole a seguinte declaração de importação no arquivo:
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
Uma vez que o arquivo esteja no seu servidor, verifique o seguinte para garantir que funciona:
1

Verifique a localização

Certifique-se de que o arquivo está localizado no mesmo Caminho para arquivos service worker definido em Configurações avançadas > Service workers. Se você não atualizou essas configurações, então você deve ter colocado o arquivo na sua raiz. Por exemplo:
  • https://seudominio.com/OneSignalSDKWorker.js
  • https://seudominio.com/algum-subdiretorio/OneSignalSDKWorker.js
2

Deve ser publicamente acessível na sua origem

O arquivo OneSignalSDKWorker.js deve ser publicamente acessível e disponível na sua origem. Não pode ser hospedado via CDN ou colocado em uma origem diferente com redirecionamento.Quando você visitar a URL para o arquivo, você deve ver o código.
3

Deve ser servido com content-type: application/javascript

Este é um arquivo javascript e precisa ser servido como tal. Não pode ter um content-type de text/html.
Se você tem perguntas adicionais ou está migrando para OneSignal de outro provedor de web push, é recomendado revisar nossa documentação de OneSignal Service Worker.

​
Adicione código ao seu site

Você deve estar pronto agora para adicionar nosso SDK ao seu site. Nosso código JavaScript SDK fornecido deve funcionar em qualquer site, mas se seu site está configurado usando Angular, React JS, ou Vue JS então siga estes links. Para inicializar OneSignal no seu site com nosso JavaScript SDK, copie/cole o código fornecido nas tags <head> do seu website. Nosso dashboard fornecerá o seguinte código mas inclui seu OneSignal app ID.
JavaScript
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(async function(OneSignal) {
      await OneSignal.init({
        appId: "YOUR_ONESIGNAL_APP_ID",
      });
    });
  </script>

​
Suporte de web push para iOS

Apple começou a suportar notificações web push em iPhones e iPads rodando iOS 16.4+. Diferente de dispositivos Android onde web push simplesmente “funciona” desde que visitado em um navegador suportado, Apple adicionou alguns requisitos a mais como um arquivo manifest.json e uma ação do usuário para adicionar seu site à tela inicial deles.

Configuração de Web Push para iOS

Adicione o arquivo manifest.json necessário e guie usuários a adicionar seu site à tela inicial deles.

​
Testando a integração do OneSignal SDK

Este guia ajuda você a verificar se sua integração do OneSignal SDK está funcionando corretamente testando notificações push e registro de inscrição.

​
Verifique inscrições de web push

1

Inicie seu site em um dispositivo de teste.

  • 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

Verifique o 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.

​
Configure inscrições de teste

Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.
1

Adicione a Test Subscriptions.

No dashboard, próximo à inscrição, clique no botão Options (três pontos) e selecione Add to Test Subscriptions.

Adicionando um dispositivo a Test Subscriptions

2

Nomeie sua inscrição.

Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois na aba Test Subscriptions.

Dashboard mostrando o campo 'Name your subscription'

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.

​
Envie push de teste via API

1

Obtenha seu App API Key e App ID.

No seu dashboard OneSignal, vá para Settings > Keys & IDs.
2

Atualize o código fornecido.

Substitua YOUR_APP_API_KEY e YOUR_APP_ID no código abaixo com suas chaves reais. Este código usa o segmento Test Users que criamos anteriormente.
curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
3

Execute o código.

Execute o código no seu terminal.
4

Verifique imagens e entrega confirmada.

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.

Estatísticas de entrega mostrando entrega confirmada

Se você está em um plano Professional ou superior, role para Audience Activity para ver confirmação a nível de inscrição:

Entrega confirmada a nível de dispositivo em Audience Activity

Você enviou com sucesso uma notificação via nossa API para um segmento.
Precisa de ajuda? Contate support@onesignal.com com as seguintes informações:
  • Copie e cole a requisição e resposta da API em um arquivo .txt
  • Seu Subscription ID
  • URL do seu website com o código OneSignal
Ficaremos felizes em ajudar!

​
Identificação de usuário

Anteriormente, demonstramos como criar Inscrições de web push. Agora vamos expandir para identificar Usuários através de todas as suas inscrições (incluindo push, email e SMS) usando o OneSignal SDK. Cobriremos External IDs, tags, inscrições multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários através de plataformas.

​
Atribua External ID

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 nosso SDK cada vez que eles são identificados 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 nosso SDK é altamente recomendado para identificar usuários através de todas as suas inscrições, independentemente de como elas são criadas.

​
Adicione data tags

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 nosso 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

​
Adicione inscrições de email e/ou SMS

Anteriormente vimos como nosso SDK cria inscrições de web push para enviar push. 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.

​
Privacidade e consentimento do usuário

Para controlar quando OneSignal coleta dados de usuário, use os métodos de controle de consentimento do SDK: Veja nossos documentos de Privacidade e segurança para mais sobre:

​
Escute eventos de push, usuário e in-app

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.

​
Eventos de notificação push

​
Mudanças de estado do usuário

​
Configuração avançada e capacidades

Explore mais capacidades para melhorar sua integração:

​
Configuração e referência do Web SDK

Certifique-se de que você habilitou todos os recursos principais revisando o guia Configuração de web push. Para detalhes completos sobre métodos disponíveis e opções de configuração, visite a referência do Web SDK.
Parabéns! Você completou com sucesso o guia de configuração do Web SDK.
Precisa de ajuda?Converse com nossa equipe de Suporte ou envie email para support@onesignal.comPor favor inclua:
  • Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  • Seu OneSignal App ID
  • O External ID ou Subscription ID se aplicável
  • A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  • Quaisquer logs ou mensagens de erro relevantes
Estamos felizes em ajudar!