Pular para o conteúdo principal

​
Visão Geral

Este guia explica como configurar o OneSignal Service Worker para Notificações Push na Web.
Se você está usando nosso plugin do WordPress, o arquivo do OneSignal Service Worker é adicionado automaticamente e você não deve adicionar esses arquivos ao seu site manualmente. Retorne para Configuração do WordPress para mais informações.

​
O que são service workers?

Um Service Worker é um script em segundo plano que é executado em uma thread separada da página principal. Ele habilita recursos como notificações push, cache offline e sincronização em segundo plano. Ele é instalado quando seu site o registra e, embora nem sempre esteja em execução, pode ser ativado para lidar com eventos (incluindo push) mesmo depois que o usuário navega para outro lugar.

Como os service workers funcionam

​
Como integrar o service worker do OneSignal

Ao seguir nosso guia de Configuração do SDK Web, você receberá o arquivo do service worker OneSignalSDKWorker.js.

​
Baixe o arquivo .js

Baixe o arquivo OneSignalSDKWorker.js do painel do OneSignal ou Baixe o Arquivo do Service Worker do OneSignal aqui.

​
Faça upload do arquivo .js para seu servidor

Nosso SDK busca por padrão o arquivo OneSignalSDKWorker.js na raiz do seu site, por exemplo: https://seusite.com/OneSignalSDKWorker.js Você pode simplesmente fazer upload deste arquivo para o diretório raiz do seu site e retornar ao guia de Configuração de push na web para os próximos passos. No entanto, é recomendado colocar este arquivo OneSignalSDKWorker.js em um caminho de subdiretório para o qual você nunca direcionará os usuários, como https://seusite.com/push/onesignal/OneSignalSDKWorker.js. Você pode colocar este arquivo na raiz, mas ele pode entrar em conflito com outros Service Workers que você tem agora ou pode adicionar no futuro. Além disso, o arquivo deve ser colocado em um caminho de localização permanente que nunca mudará. Uma vez que um Service Worker é registrado no navegador, é difícil alterá-lo.

​
Configuração do Service Worker

O arquivo do service worker do OneSignal OneSignalSDKWorker.js deve atender a estes requisitos:
  • O arquivo deve ser publicamente acessível, o que significa que você deve ser capaz de navegar até o arquivo em um navegador e ver o código.
  • O arquivo deve ser servido com um content-type de application/javascript; charset=utf-8.
  • O arquivo deve apontar para a mesma origem do site (domínio do seu site). Apontar para um Service Worker em uma origem diferente não é permitido. Sem CDNs ou subdomínios.

​
Confirme que o service worker está configurado corretamente

Visite o service worker no seu navegador. Você deve ver o código do service worker: importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Exemplo do código do service worker

Se você fez upload do arquivo OneSignalSDKWorker.js para a raiz do seu site (ele está acessível em https://seusite.com/OneSignalSDKWorker.js) então nenhuma ação adicional é necessária. No entanto, se você o colocou em um subdiretório como https://seusite.com/push/onesignal/OneSignalSDKWorker.js então você precisará definir o escopo de registro da seguinte forma:
  • Configuração típica de site
  • Configuração de Código Personalizado
No painel do OneSignal, vá para Configurações > Push & In-App > Configurações Web do seu AppEm Configurações Avançadas de Push, ative a opção Personalizar caminhos e nomes de arquivos dos service workers e insira seus dados.

Configuração do service worker para Configuração típica de site

  • Caminho para os arquivos do service worker é o diretório onde o arquivo do Service Worker do OneSignal estará disponível. Se o Service Worker estiver disponível em: https://seusite.com/push/onesignal/OneSignalSDKWorker.js então o caminho é: /push/onesignal/
  • Nomes de arquivos dos service workers principal e atualizador é o nome do arquivo do Service worker. Deve ser OneSignalSDKWorker.js mas se você o alterou, certifique-se de usar a extensão de arquivo .js. Por exemplo, se seu servidor força arquivos a terem minúsculas, você pode definir o nome do arquivo como onesignalsdkworker.js
  • Escopo de registro do service worker são as páginas nas quais este arquivo pode funcionar. Este deve ser um caminho para o qual você nunca direcionará usuários e nunca hospedará nenhuma página agora ou no futuro. Um exemplo de caminho comum: /push/onesignal/ e o escopo pode ser o mesmo caminho ou mais profundo como: /push/onesignal/js/
Configuração do service worker concluída!Retorne ao guia de Configuração do SDK Web para os próximos passos.

​
Guia de migração do OneSignal Service Worker

Esta seção é apenas para clientes que já usam o OneSignal, têm uma grande quantidade de assinantes de push na web e desejam alterar as configurações do OneSignal Service Worker. Isso não é recomendado a menos que você tenha um motivo específico para fazê-lo.
Este guia é apenas para clientes que já usam o OneSignal em seu site atualmente e desejam mover o arquivo OneSignalSDKWorker.js para um caminho ou escopo diferente.
O Service Worker do OneSignal usa por padrão um escopo raiz, o que pode criar os seguintes problemas para seu site:
  • Conflito com um PWA
  • Conflito com uma configuração AMP
  • Conflito com seu Service Worker de cache, ou qualquer outro recurso de Service Worker que requer escopo raiz
  • Seu site tem requisitos de segurança que não permitem que código de Service Worker de terceiros seja executado em um escopo que controla uma página que seus usuários visitarão.
Se uma ou mais se aplicam a você, então siga este guia.

​
Escolhendo um Escopo do OneSignal Service Worker

É recomendado que você escolha um caminho de escopo do Service Worker para o qual você nunca direcionará um usuário, mas que ainda deixe claro o que ele faz. Exemplo: /push/onesignal/. Dessa forma, seu PWA, AMP ou qualquer outro ServiceWorker de cache pode controlar a página que um usuário visualiza para funcionar corretamente.É permitido colocar vários service workers no mesmo caminho de localização, mas DEVEM ter caminhos de escopo exclusivos.
  • Opção 1: Alterar escopo
  • Opção 2: Alterar nome do arquivo ou localização

​
Alterar com segurança o Escopo do OneSignal Service Worker

É recomendado apenas alterar o escopo, se possível. Alterar o nome do arquivo ou o caminho de localização do próprio Service Worker tem considerações adicionais. Preste muita atenção tanto aos detalhes de qual cenário se aplica a você quanto a cada etapa para garantir que você não perca assinantes ou enfrente problemas de exibição de notificações

​
Tipo de Configuração 1. Configuração Padrão do OneSignal - Escopo raiz ”/” E Conteúdo padrão do OneSignalSDKWorker.js

Confirme que o conteúdo do seu arquivo OneSignalSDKWorker.js é o mesmo encontrado em Baixe o Arquivo do Service Worker do OneSignal aqui. (Sem nenhum outro código não-OneSignal que você possa precisar nele)Neste caso, você pode alterar o escopo do OneSignal para qualquer coisa que você escolher para dar espaço para outro Service Worker ser colocado no escopo raiz. Veja acima Personalize Sua Integração do Service Worker.
Se o seu OneSignalSDKWorker.js não está hospedado na raiz do seu domínio hoje, por exemplo, você NÃO o tem hospedado assim: https://meusite.com/OneSignalSDKWorker.js então você DEVE continuar hospedando-o com o cabeçalho Service-Worker-Allowed por um período prolongado de tempo. (1 ano ou mais é recomendado)Se possível, recomendamos adicionar um comentário em seu código backend ou em sua documentação interna para garantir que ele não seja removido acidentalmente.

​
Tipo de Configuração 2. Incomum - Escopo raiz ”/” E OneSignalSDKWorker.js (ou seu nome de arquivo configurado) contém OneSignal + outro código ou importScripts

Isso é menos comum, mas você pode já ter feito isso seguindo este guia do OneSignal “Integrando Vários Service Workers”. Se esta configuração ainda atende a todos os seus requisitos, é altamente recomendável manter sua configuração como está devido ao complexo e bifásico lançamento necessário para separar o arquivo ServiceWorker mesclado que lida com eventos push.
Esta seção se aplica se você tem o OneSignal E algum outro código personalizado ou importScript como o seguinte em seu Service Worker atual.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//E algum outro código específico do site no mesmo arquivo, exemplo.
importScripts("https://site.com/my-other-service-worker.js");
1

Mantenha o código existente do seu service worker.

Adicione um comentário de código ao seu arquivo ServiceWorker existente acima desta linha importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); para mantê-la por um período prolongado de tempo. (um ano ou mais é recomendado, depende de quanto tempo você deseja continuar enviando pushes para usuários que nunca revisitam seu site). Exemplo: // MANTER Até AAAA-MM-DD: Necessário para que os pushes funcionem corretamente para usuários que não revisitaram para migrar para o novo ServiceWorker específico do OneSignal.
2

Crie um novo arquivo de service worker

Crie um novo OneSignalSDKWorker.js em um diretório diferente, como /push/onesignal/ com a seguinte linha única de código importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Siga o guia sobre "Personalizando Sua Integração do Service Worker" para alterar seu escopo, nome de arquivo e caminho.

4

Neste ponto, usuários novos e recorrentes serão automaticamente inscritos no novo ServiceWorker do OneSignal.

5

Aguarde a quantidade de tempo (um ano ou mais) conforme observado na etapa 1.

6

Siga o guia do OneSignal - Excluir Usuários para excluir usuários mais antigos do que o cronograma que você escolheu.

7

Remova o comentário do service worker original

Por fim, finalmente remova a linha importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); com o comentário do seu ServiceWorker raiz original.

​
Migrando o escopo do ServiceWorker do OneSignal - FAQ

Por que devo continuar hospedando o URL do arquivo ServiceWorker original se eu alterar o nome ou o caminho de localização?
Isso é necessário para aqueles usuários que não revisitaram seu site para que o novo nome de arquivo seja detectado. O arquivo ServiceWorker original será buscado pelo navegador cada vez que você enviar um push (se tiver passado o tempo de expiração do cache, cache máximo é de 24 horas). Você verá um aumento nos erros 404 retornados do seu provedor de hospedagem ao enviar um push se o arquivo ServiceWorker original não estiver disponível. Isso pode resultar em mais solicitações ao seu servidor. Isso também significa que esses usuários não estarão recebendo os novos recursos e correções do OneSignal.