OneSignal service worker

O OneSignal service worker (OneSignalSDKWorker.js) é um arquivo JavaScript hospedado em seu servidor, necessário para notificações push web. Ele permite que seu site receba e exiba notificações, mesmo quando o usuário não está na sua página.

Se você usa o plugin do WordPress, pule este guia. O plugin hospeda o OneSignalSDKWorker.js em seu diretório sdk_files e configura o caminho para você. Não faça upload do arquivo para a raiz do seu site nem defina um caminho personalizado no painel ou em código. Consulte a configuração do WordPress. O Shopify também implanta o worker para você. Consulte a configuração do Shopify.

Configuração do service worker

Crie um arquivo OneSignalSDKWorker.js dedicado para notificações push do OneSignal. Se seu site já possui um service worker e você deseja usar um único arquivo, consulte Combinar múltiplos service workers.

Baixar ou criar o OneSignalSDKWorker.js

Baixe o arquivo do painel do OneSignal durante a configuração do Web SDK ou do GitHub.Alternativamente, crie um arquivo chamado OneSignalSDKWorker.js com a seguinte linha única de código:

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

Você pode renomear o arquivo se necessário (p. ex., onesignalsdkworker.js, ossw.js). Nesse caso, substitua OneSignalSDKWorker.js neste guia pelo nome do seu arquivo.

Fazer upload para seu servidor web

Coloque o OneSignalSDKWorker.js em seu servidor de forma que seja acessível publicamente via HTTPS. O arquivo não deve exigir autenticação ou login para acesso.Recomendado: Hospede o arquivo em um subdiretório dedicado que nunca sirva páginas, como /push/onesignal/. Isso evita conflitos com outros service workers em seu site (p. ex., um service worker de PWA ou AMP) e mantém o caminho URL estável.

Exemplo: https://yoursite.com/push/onesignal/OneSignalSDKWorker.js

Alternativa: O OneSignal Web SDK busca por padrão o arquivo na raiz do seu site (https://yoursite.com/OneSignalSDKWorker.js). Você pode fazer upload do arquivo para o diretório raiz, mas pode entrar em conflito com outros service workers que precisam do escopo raiz. Se você usa uma PWA, coloque o OneSignalSDKWorker.js em um subdiretório.

Escolha um caminho URL permanente. Uma vez que um navegador registra um service worker em uma URL específica, alterar essa URL requer uma migração.

Verificar se o arquivo está acessível

Acesse a URL do arquivo no seu navegador (p. ex., https://yoursite.com/push/onesignal/OneSignalSDKWorker.js). Você deve ver a linha importScripts da primeira etapa:

Browser displaying the single importScripts line inside OneSignalSDKWorker.js — Conteúdo esperado do arquivo service worker no navegador

Se você vir um erro 404, uma página em branco ou um prompt de login, o arquivo não foi carregado corretamente ou está por trás de autenticação.

Informar ao SDK onde encontrar o arquivo

O Web SDK procura o OneSignalSDKWorker.js na raiz do seu site (https://yoursite.com/OneSignalSDKWorker.js), a menos que você informe uma localização diferente. Como informar depende do seu tipo de integração.Se você colocou o arquivo na raiz do seu site, nenhuma configuração adicional é necessária. Pule para a próxima etapa.Se você colocou o arquivo em um subdiretório, você deve definir o caminho. Site Típico define no painel. Código Personalizado define em OneSignal.init(). Misturar os dois não funciona: os campos de caminho do painel não se aplicam a Código Personalizado, e serviceWorkerPath não se aplica a Site Típico.

Site Típico

Defina o caminho no painel do OneSignal. Não passe serviceWorkerPath em código.

Acesse Settings > Push & In-App > Web.
Em Advanced Push Settings, habilite Customize service worker paths and filenames.

OneSignal dashboard fields for service worker path, filename, and registration scope — Configuração do caminho do service worker no painel

Campo	Descrição	Exemplo
Path to service worker files	Diretório onde `OneSignalSDKWorker.js` está hospedado.	`/push/onesignal/`
Service worker filename	Nome do arquivo `.js`.	`OneSignalSDKWorker.js`
Service worker registration scope	Caminho URL que o service worker controla. Deve estar no diretório onde o arquivo está hospedado ou abaixo dele. Use um caminho que nunca sirva páginas voltadas ao usuário.	`/push/onesignal/`

Consulte a configuração do Web SDK para o procedimento de Site Típico.

Código Personalizado

Passe serviceWorkerPath e serviceWorkerParam na sua chamada OneSignal.init(). Código Personalizado não usa os campos Customize service worker paths and filenames do painel.

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  window.OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({
      appId: "YOUR_ONESIGNAL_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>

Parâmetro	Descrição	Exemplo
`serviceWorkerPath`	Caminho relativo da raiz do site até o arquivo `.js` (sem barra inicial).	`"push/onesignal/OneSignalSDKWorker.js"`
`serviceWorkerParam.scope`	Caminho URL que o service worker controla. Deve estar no diretório onde o arquivo está hospedado ou abaixo dele. Use um caminho que nunca sirva páginas voltadas ao usuário.	`"/push/onesignal/"`

Se o arquivo não está na raiz do site e você omitir essas opções, o SDK ainda buscará https://yoursite.com/OneSignalSDKWorker.js e o registro falhará.Consulte a Configuração de Código Personalizado para adicionar essas opções ao seu snippet de init completo.

Revisar os requisitos do service worker

O arquivo OneSignalSDKWorker.js deve atender a todos os requisitos a seguir para que as notificações push funcionem.

Requisito	Detalhes
Acessível publicamente	Acesse a URL do arquivo em um navegador e confirme que você vê o código JavaScript.
Tipo de conteúdo correto	O servidor deve retornar `Content-Type: application/javascript; charset=utf-8`.
Mesma origem	O arquivo deve ser hospedado no mesmo domínio que seu site. CDNs e subdomínios não são permitidos. Consulte MDN: Registering your worker.
HTTPS	Service workers requerem um contexto seguro. `localhost` é a única exceção durante o desenvolvimento.

A configuração do service worker está concluída.

Configuração do Web SDK

Continue com o guia de configuração do Web SDK para as próximas etapas.

Combinar múltiplos service workers

Cada arquivo service worker em seu site é registrado em um escopo — um caminho URL que determina quais páginas ele controla. Apenas um service worker pode estar ativo em um dado escopo. Se você já tem um service worker (por exemplo, uma PWA ou worker de cache) e quer que o OneSignal compartilhe o mesmo arquivo, você pode combiná-los.

Manter os service workers em arquivos separados com escopos separados é mais simples de manter e evita conflitos. Combine-os apenas se sua configuração exigir um único arquivo service worker.

Para combinar, adicione a linha importScripts do OneSignal ao seu arquivo service worker existente:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
importScripts("https://yoursite.com/your-other-service-worker.js");

Após combinar, atualize a configuração do OneSignal para apontar para seu arquivo service worker existente. Siga Informar ao SDK onde encontrar o arquivo usando o caminho e o nome de arquivo do seu arquivo combinado.

Guia de migração

Esta seção é para clientes existentes do OneSignal que precisam alterar o caminho do arquivo service worker, o nome de arquivo ou o escopo. Não siga estas etapas a menos que você tenha uma razão específica para alterar sua configuração atual.

Quando e como migrar seu service worker

Motivos para migrar:

O OneSignal service worker com escopo raiz entra em conflito com um Progressive Web App (PWA)
O service worker entra em conflito com AMP ou outro service worker de cache
Políticas de segurança proíbem código de service worker de terceiros no escopo raiz

Opção 1: Alterar apenas o escopo (recomendado)Alterar apenas o escopo é a migração mais segura. O arquivo permanece em sua URL atual, portanto os assinantes existentes continuam recebendo notificações sem interrupção.Se o seu arquivo contém apenas código OneSignalConfirme que OneSignalSDKWorker.js contém apenas:

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

Atualize o escopo usando o painel (Site Típico) ou serviceWorkerParam (Código Personalizado) conforme descrito em Informar ao SDK onde encontrar o arquivo. Nenhuma outra alteração é necessária.

Se OneSignalSDKWorker.js não está hospedado na raiz do seu domínio hoje, você deve continuar hospedando-o em sua URL atual com o cabeçalho Service-Worker-Allowed por pelo menos um ano. Adicione um comentário em seu código backend ou documentação interna para que o arquivo não seja removido acidentalmente.

Se o seu arquivo contém OneSignal + outro códigoSeu service worker pode incluir chamadas importScripts adicionais (p. ex., ao seguir o guia Combinar múltiplos service workers). Se sua configuração atual ainda funciona, mantenha-a como está — separar um service worker mesclado requer um rollout em duas fases.Se você precisar separá-los:

Adicionar um comentário de retenção ao arquivo existente

Acima da linha importScripts do OneSignal em seu service worker atual, adicione:

// KEEP until YYYY-MM-DD: Required for push delivery to subscribers who have not revisited.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Defina a data pelo menos um ano no futuro.

Criar um novo service worker dedicado do OneSignal

Crie OneSignalSDKWorker.js em um subdiretório (p. ex., /push/onesignal/) contendo apenas:

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

Atualizar a configuração do OneSignal

Defina o novo caminho e escopo usando o painel (Site Típico) ou OneSignal.init() (Código Personalizado) conforme descrito em Informar ao SDK onde encontrar o arquivo.

Aguardar a migração dos assinantes

Novos visitantes e visitantes recorrentes se registram automaticamente no novo service worker. Aguarde pelo menos um ano para que a maioria dos assinantes existentes revisite seu site.

Limpeza

Exclua usuários inativos mais antigos que o período de retenção escolhido, depois remova a linha importScripts do OneSignal do arquivo service worker original.

Opção 2: Alterar o nome de arquivo ou localização do arquivoAlterar o nome de arquivo ou diretório é mais complexo porque os navegadores buscam o service worker da URL onde foi originalmente registrado. Os assinantes que não revisitaram seu site ainda referenciam a URL antiga.

Você deve continuar hospedando o arquivo original em sua URL antiga por pelo menos um ano. Removê-lo causa erros 404 quando o navegador tenta atualizar o service worker, e os assinantes afetados param de receber notificações.

Se o seu arquivo contém apenas código OneSignal

Adicionar um comentário de retenção ao arquivo antigo

// KEEP until YYYY-MM-DD: Required for push delivery to subscribers still on the old service worker URL.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Criar o novo arquivo na nova localização

Coloque OneSignalSDKWorker.js (ou o nome de arquivo escolhido) no novo diretório com:

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

Atualizar a configuração do OneSignal

Defina o novo caminho, nome de arquivo e escopo conforme descrito em Informar ao SDK onde encontrar o arquivo.

Aguardar a migração dos assinantes

Novos visitantes e visitantes recorrentes se registram com o novo arquivo automaticamente. Aguarde pelo menos um ano.

Limpeza

Exclua usuários inativos mais antigos que seu período de retenção, depois remova o arquivo antigo.

Se o seu arquivo contém OneSignal + outro códigoSiga as etapas da Opção 1: Alterar apenas o escopo acima. O processo é o mesmo.

Perguntas frequentes

Este guia se aplica ao WordPress?

Não. O plugin do WordPress hospeda e registra o OneSignalSDKWorker.js em seu diretório sdk_files. Não faça upload de um worker para a raiz do site nem defina serviceWorkerPath em código. Consulte a configuração do WordPress.

Como defino o caminho do service worker para Site Típico vs Código Personalizado?

O Web SDK procura o OneSignalSDKWorker.js na raiz do seu site, a menos que você defina um caminho personalizado. Site Típico define esse caminho no painel em Customize service worker paths and filenames. Código Personalizado o define em código com serviceWorkerPath e serviceWorkerParam em OneSignal.init(). Os campos de caminho do painel não se aplicam a Código Personalizado. Consulte Informar ao SDK onde encontrar o arquivo.

Por que meu service worker retorna 404?

O arquivo não está na URL que o SDK espera. Acesse a URL completa do arquivo no seu navegador para confirmar que está acessível. Se você colocou o arquivo em um subdiretório, o caminho configurado deve corresponder à localização real do arquivo, incluindo o diretório e o nome de arquivo. Site Típico: verifique as configurações de caminho do painel. Código Personalizado: verifique o serviceWorkerPath em OneSignal.init().

Por que as notificações não aparecem após eu mover o arquivo service worker?

Os assinantes existentes ainda referenciam a URL antiga do service worker. O navegador busca a URL registrada (com cache de até 24 horas) cada vez que um push chega. Se a URL antiga retornar 404, esses assinantes não recebem notificações. Continue hospedando o arquivo antigo por pelo menos um ano enquanto os assinantes migram naturalmente ao revisitar seu site. Consulte o guia de migração e o guia Notificações push web não exibidas.

Posso hospedar o service worker em um CDN ou subdomínio?

Não. Os navegadores exigem que os service workers sejam servidos da mesma origem que a página que os registra. O arquivo deve estar no seu domínio principal — não em um CDN, subdomínio ou domínio diferente.

Por que minha PWA entra em conflito com o OneSignal service worker?

Ambos provavelmente estão registrados no escopo raiz (/) e apenas um service worker pode estar ativo em um dado escopo. Mova o OneSignal service worker para um escopo de subdiretório (p. ex., /push/onesignal/) para que sua PWA mantenha o controle do escopo raiz, ou combine-os conforme descrito em Combinar múltiplos service workers.

Posso renomear o arquivo OneSignalSDKWorker.js?

Sim. Se seu servidor exige uma convenção de nomenclatura específica (p. ex., tudo em minúsculas), renomeie o arquivo para algo como onesignalsdkworker.js. Site Típico: atualize o campo Service worker filename no painel. Código Personalizado: atualize o serviceWorkerPath na sua chamada OneSignal.init(). Consulte Informar ao SDK onde encontrar o arquivo.

Qual tipo de conteúdo meu servidor deve retornar para o arquivo service worker?

O servidor deve retornar Content-Type: application/javascript; charset=utf-8. Algumas configurações de servidor ou CDN retornam um tipo MIME incorreto, o que faz o navegador rejeitar o registro do service worker.

Documentação de desenvolvedor

SDKs móveis

SDKs web

Atividades ao Vivo

Configuração de Desktop & Watch

OneSignal service worker

Configuração do service worker

Site Típico

Código Personalizado

Configuração do Web SDK

Combinar múltiplos service workers

Guia de migração

Perguntas frequentes

Este guia se aplica ao WordPress?

Como defino o caminho do service worker para Site Típico vs Código Personalizado?

Por que meu service worker retorna 404?

Por que as notificações não aparecem após eu mover o arquivo service worker?

Posso hospedar o service worker em um CDN ou subdomínio?

Por que minha PWA entra em conflito com o OneSignal service worker?

Posso renomear o arquivo OneSignalSDKWorker.js?

Qual tipo de conteúdo meu servidor deve retornar para o arquivo service worker?

​Configuração do service worker

​Site Típico

​Código Personalizado

Configuração do Web SDK

​Combinar múltiplos service workers

​Guia de migração

​Perguntas frequentes

​Este guia se aplica ao WordPress?

​Como defino o caminho do service worker para Site Típico vs Código Personalizado?

​Por que meu service worker retorna 404?

​Por que as notificações não aparecem após eu mover o arquivo service worker?

​Posso hospedar o service worker em um CDN ou subdomínio?

​Por que minha PWA entra em conflito com o OneSignal service worker?

​Posso renomear o arquivo OneSignalSDKWorker.js?

​Qual tipo de conteúdo meu servidor deve retornar para o arquivo service worker?

Configuração do service worker

Site Típico

Código Personalizado

Combinar múltiplos service workers

Guia de migração

Perguntas frequentes

Este guia se aplica ao WordPress?

Como defino o caminho do service worker para Site Típico vs Código Personalizado?

Por que meu service worker retorna 404?

Por que as notificações não aparecem após eu mover o arquivo service worker?

Posso hospedar o service worker em um CDN ou subdomínio?

Por que minha PWA entra em conflito com o OneSignal service worker?

Posso renomear o arquivo OneSignalSDKWorker.js?

Qual tipo de conteúdo meu servidor deve retornar para o arquivo service worker?