Configuração de push web com código personalizado

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:

Se você estiver usando um framework JavaScript, siga estes guias especializados:

Requisitos

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.
- Criar múltiplos apps OneSignal, um por origem.

Configurar seu app e plataforma OneSignal

No dashboard do OneSignal:

Acesse Settings > Push & In-App > Web.
Selecione o tipo de integração Custom Code.

Configuração do site

Adicione os detalhes do site:

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 um PNG, JPG ou GIF não animado quadrado de 256×256 que aparece em notificações e prompts. Se não definido, um ícone de sino é usado como padrão. Consulte Ícones de notificação.

Se os usuários limparem os dados do navegador, eles deixam de receber push até retornarem. Habilite Auto Resubscribe para que eles sejam inscritos novamente sem uma nova solicitação de permissão. Consulte Inscrições.

OneSignal web push configuration showing site name, URL, and icon settings — Configurações Web no dashboard do OneSignal

Testes locais

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.

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

Notificação de boas-vindas (opcional)

O Custom Code define a notificação de boas-vindas em OneSignal.init() com os parâmetros de welcomeNotification. As configurações Typical Site e WordPress a definem no dashboard. Consulte Configuração do Web SDK.

Upload do arquivo service worker

O Web SDK procura o OneSignalSDKWorker.js na raiz do seu site (https://yourdomain.com/OneSignalSDKWorker.js), a menos que você passe um caminho personalizado em OneSignal.init(). O Custom Code não usa os campos Customize service worker paths and filenames do dashboard. Você informa ao SDK onde procurar no código com serviceWorkerPath e serviceWorkerParam. Baixe o arquivo do dashboard do OneSignal, ou crie um arquivo chamado OneSignalSDKWorker.js com esta única linha:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Raiz (padrão): Faça upload do arquivo de modo que ele fique disponível em https://yourdomain.com/OneSignalSDKWorker.js. Você não precisa definir serviceWorkerPath. O SDK solicita essa URL automaticamente. Subdiretório: Se o seu site já tiver um service worker (por exemplo, um PWA), coloque o arquivo do OneSignal em um subdiretório como /push/onesignal/ para que ele não entre em conflito com o worker que controla /. Nesse caso, você deve passar serviceWorkerPath e serviceWorkerParam em OneSignal.init(). Consulte Adicionar código ao site. O arquivo deve estar publicamente acessível em https://yourdomain.com/push/onesignal/OneSignalSDKWorker.js.

Se o arquivo não estiver na raiz do site e você omitir serviceWorkerPath e serviceWorkerParam, o SDK ainda buscará https://yourdomain.com/OneSignalSDKWorker.js e o registro do service worker falhará.

Service worker do OneSignal

Combinação de workers, nomes de arquivo personalizados e migração de outros provedores.

Adicionar código ao site

Adicione este código à seção <head> do seu site. Substitua YOUR_ONESIGNAL_APP_ID pelo seu App ID do dashboard do OneSignal. Se o OneSignalSDKWorker.js estiver na raiz do seu site, use este snippet:

HTML

<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",
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

Se o arquivo estiver em um subdiretório, adicione serviceWorkerPath e serviceWorkerParam. Essas opções são a única forma de o Custom Code informar ao SDK uma localização fora da raiz.

HTML

<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",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
      notifyButton: {
        enable: true,
      },
    });
  });
</script>

Parâmetro	Descrição	Exemplo
`serviceWorkerPath`	Caminho relativo da raiz do site até o arquivo `.js`. Não inclua uma barra inicial.	`"push/onesignal/OneSignalSDKWorker.js"`
`serviceWorkerParam.scope`	Caminho de URL que o service worker controla. Use o mesmo diretório do arquivo.	`"/push/onesignal/"`

A persistência é definida no código com persistNotification. O botão de alternância de Persistência do dashboard não se aplica ao Custom Code. Se você omitir a opção, o SDK atualmente trata a persistência como ativada. Defina persistNotification: false para desativá-la. Ela funciona apenas no Chrome e no Edge em desktop. Consulte Persistência.

Suporte a push web no iOS

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.

Certificado .p12 do Safari Web Push (opcional, legado)

Deixe isso desativado, a menos que você já tenha seu próprio certificado .p12 de Safari Web Push e queira oferecer suporte a usuários de versões legadas do Safari. O Safari moderno (macOS 13+ e iOS 16.4+) usa Web Push baseado em padrões com VAPID (Voluntary Application Server Identification). O OneSignal cuida do VAPID automaticamente. Você não precisa fazer upload de um certificado para navegadores Safari modernos. Se você já tiver seu próprio .p12 (a Apple não oferece suporte a .p8 para Safari Web Push), faça upload dele no dashboard. Consulte Certificado .p12 do Safari Web Push.

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

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 do navegador perguntando ao usuário se permite ou bloqueia notificações — Prompt de permissão nativo de web push

Verifique seu dashboard OneSignal

Vá para Audience > Subscriptions.
Você deve ver uma nova entrada com o 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.

Adicione a Test Users.

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

Menu de opções em uma inscrição mostrando a opção Adicionar a Test Users — Adicionando um dispositivo a Test Users

Nomeie sua inscrição.

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

Crie um segmento de usuários de teste.

Vá para Audience > Segments > New Segment.

Nomeie o segmento.

Nomeie o segmento Test Users (o nome é importante porque será usado depois).

Adicione o filtro Test Users e clique em Create Segment.

Editor de segmento com filtro Test Users selecionado e segmento nomeado Test Users — 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

Obtenha seu App API Key e App ID.

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

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"
}'

Execute o código.

Execute o código no seu terminal.

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 no Chrome macOS exibindo uma imagem personalizada — Notificação push expandida com imagem no Chrome macOS

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)
Seu Subscription ID
A URL do seu website com o código OneSignal

Identificação de usuário

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.

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

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

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.

Use o método addEmail para criar inscrições de email.
Use o método addSms para criar inscrições de SMS.

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:

setConsentRequired(true): Previne coleta de dados até que consentimento seja dado.
setConsentGiven(true): Habilita coleta de dados uma vez que consentimento é concedido.

Para mais sobre privacidade e segurança:

Dados coletados pelo SDK

Revise quais dados o OneSignal SDK coleta dos usuários.

Tratamento de dados pessoais

Gerencie e proteja dados de usuários em conformidade com regulamentações de privacidade.

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

Click event listener: Detecte quando uma notificação é tocada.
Foreground lifecycle listener: Controle como notificações se comportam em foreground.

Mudanças de estado do usuário

User state change event listener: Detecte quando o External ID é definido.
Permission observer: Rastreie a interação específica do usuário com o prompt de permissão push nativo.
Push subscription change observer: Rastreie quando o status de inscrição push muda.

Configuração avançada e capacidades

Explore mais capacidades para melhorar sua integração:

Migrando para o OneSignal

Migre de outro provedor de push para o OneSignal.

Integrações

Conecte o OneSignal com ferramentas e plataformas de terceiros.

Botões de ação

Adicione botões interativos às notificações push.

Mensagens multilíngues

Envie mensagens localizadas aos usuários no idioma de sua preferência.

Verificação de Identidade

Proteja sua integração do SDK com verificação de identidade no servidor.

Custom Outcomes

Rastreie eventos de conversão personalizados vinculados às suas mensagens.

Configuração e referência do Web SDK

Configuração de web push

Habilite todos os recursos principais de web push para sua integração.

Referência do Web SDK

Detalhes completos sobre métodos disponíveis e opções de configuração.

Parabéns! Você completou com sucesso o guia de configuração do Web SDK.

Perguntas frequentes

Onde o Web SDK procura o service worker?

O Web SDK procura o OneSignalSDKWorker.js na raiz do seu site (https://yourdomain.com/OneSignalSDKWorker.js), a menos que você passe serviceWorkerPath e serviceWorkerParam em OneSignal.init(). O Custom Code não usa os campos de caminho do dashboard. Consulte Upload do arquivo service worker.

Preciso de HTTPS para notificações push web?

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 a Configuração Angular, a Configuração React JS e a Configuração Vue JS.

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.

​Requisitos

​Configurar seu app e plataforma OneSignal

​Configuração do site

​Testes locais

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

​Upload do arquivo service worker

Service worker do OneSignal

​Adicionar código ao site

​Suporte a push web no iOS

Configuração de push web para iOS

​Certificado .p12 do Safari Web Push (opcional, legado)

​Testando a integração do OneSignal SDK

​Verifique inscrições de web push

​Configure inscrições de teste

​Envie push de teste via API

Relatórios de mensagens de notificação push

​Identificação de usuário

​Atribua External ID

​Adicione Tags

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

​Privacidade e consentimento do usuário

Dados coletados pelo SDK

Tratamento de dados pessoais

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

​Eventos de notificação push

​Mudanças de estado do usuário

​Configuração avançada e capacidades

Migrando para o OneSignal

Integrações

Botões de ação

Mensagens multilíngues

Verificação de Identidade

Custom Outcomes

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

Configuração de web push

Referência do Web SDK

​Perguntas frequentes

​Onde o Web SDK procura o service worker?

​Preciso de HTTPS para notificações push web?

​Posso usar esta configuração com uma aplicação de página única (SPA)?

​O que acontece se um usuário limpar os dados do navegador?

​Páginas relacionadas

Solicitações de permissão

Referência do Web SDK

Requisitos

Configurar seu app e plataforma OneSignal

Configuração do site

Testes locais

Notificação de boas-vindas (opcional)

Upload do arquivo service worker

Adicionar código ao site

Suporte a push web no iOS

Certificado .p12 do Safari Web Push (opcional, legado)

Testando a integração do OneSignal SDK

Verifique inscrições de web push

Configure inscrições de teste

Envie push de teste via API

Identificação de usuário

Atribua External ID

Adicione Tags

Adicione inscrições de email e/ou SMS

Privacidade e consentimento do usuário

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

Eventos de notificação push

Mudanças de estado do usuário

Configuração avançada e capacidades

Configuração e referência do Web SDK

Perguntas frequentes

Onde o Web SDK procura o service worker?

Preciso de HTTPS para notificações push web?

Posso usar esta configuração com uma aplicação de página única (SPA)?

O que acontece se um usuário limpar os dados do navegador?

Páginas relacionadas