Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
Diagram showing the OneSignal service worker receiving a push event and displaying a notification
Se você usa nosso plugin do WordPress, o service worker é adicionado automaticamente. Pule este guia e volte para a configuração do WordPress.

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

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 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). Nesse caso, substitua OneSignalSDKWorker.js neste guia pelo nome do seu arquivo.
2

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 servira 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. Por exemplo, 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.
3

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 Etapa 1:
Browser displaying the single importScripts line inside OneSignalSDKWorker.js
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.
4

Configurar o caminho do SDK (apenas subdiretório)

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, informe ao SDK onde encontrá-lo:

​
Configuração típica de site

  1. No painel do OneSignal, acesse Configurações > Push & In-App > Configurações web.
  2. Em Configurações avançadas de push, habilite Personalizar caminhos e nomes de arquivo do service worker.
OneSignal dashboard fields for service worker path, filename, and registration scope
CampoDescriçãoExemplo
Path to service worker filesDiretório onde OneSignalSDKWorker.js está hospedado./push/onesignal/
Service worker filenameNome do arquivo .js.OneSignalSDKWorker.js
Service worker registration scopeCaminho URL que o service worker controla. Deve estar no diretório ou abaixo onde o arquivo está hospedado. Use um caminho que nunca sirva páginas voltadas ao usuário./push/onesignal/

​
Configuração de código personalizado

Passe serviceWorkerPath e serviceWorkerParam na sua chamada OneSignal.init():
<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_APP_ID",
      serviceWorkerPath: "push/onesignal/OneSignalSDKWorker.js",
      serviceWorkerParam: { scope: "/push/onesignal/" },
    });
  });
</script>
ParâmetroDescriçãoExemplo
serviceWorkerPathCaminho relativo da raiz do site até o arquivo .js (sem barra inicial)."push/onesignal/OneSignalSDKWorker.js"
serviceWorkerParam.scopeCaminho URL que o service worker controla. Deve estar no diretório ou abaixo onde o arquivo está hospedado. Use um caminho que nunca sirva páginas voltadas ao usuário."/push/onesignal/"
5

Revisar os requisitos do service worker

O arquivo OneSignalSDKWorker.js deve atender a todos os requisitos a seguir. Se algum não for atendido, as notificações push não funcionarão.
RequisitoDetalhes
Acessível publicamenteAcesse a URL do arquivo em um navegador e confirme que você vê o código JavaScript.
Tipo de conteúdo corretoO servidor deve retornar Content-Type: application/javascript; charset=utf-8.
Mesma origemO 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.
HTTPSService 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 a Etapa 4: Configurar o caminho do SDK 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.
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 ou serviceWorkerParam conforme descrito na Etapa 4: Configurar o caminho do SDK. 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:
1

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

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");
3

Atualizar a configuração do OneSignal

Defina o novo caminho e escopo usando o painel ou OneSignal.init() conforme descrito na Etapa 4: Configurar o caminho do SDK.
4

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

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
1

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");
2

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");
3

Atualizar a configuração do OneSignal

Defina o novo caminho, nome de arquivo e escopo conforme descrito na Etapa 4: Configurar o caminho do SDK.
4

Aguardar a migração dos assinantes

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

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.

​
Problemas comuns

​
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, verifique se serviceWorkerPath (código personalizado) ou a configuração de caminho do painel corresponde à localização real do arquivo — incluindo o diretório e o nome de arquivo.

​
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 ser registrado em um escopo específico. 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 service workers 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), você pode renomear o arquivo para algo como onesignalsdkworker.js. Nesse caso, atualize o nome de arquivo na sua configuração do OneSignal — no campo Service worker filename no painel ou no parâmetro serviceWorkerPath na sua chamada OneSignal.init(). Consulte a Etapa 4 para mais detalhes.

​
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 podem retornar um tipo MIME incorreto, o que faz o navegador rejeitar o registro do service worker.