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

# OneSignal service worker

> Configure o arquivo OneSignalSDKWorker.js para que seu site possa receber e exibir notificações push web através do OneSignal.

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.

<Frame caption="Como o OneSignal service worker processa notificações push">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/67882a5-onesignsal-service-worker.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=e0b50cfe6ccc36c1b2b6d36219b6e3ad" alt="Diagram showing the OneSignal service worker receiving a push event and displaying a notification" width="2016" height="949" data-path="images/docs/67882a5-onesignsal-service-worker.jpg" />
</Frame>

<Note>
  Se você usa nosso plugin do WordPress, o service worker é adicionado automaticamente. Pule este guia e volte para a [configuração do WordPress](./wordpress).
</Note>

## 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](#combining-multiple-service-workers).

<Steps>
  <Step title="Baixar ou criar o OneSignalSDKWorker.js">
    Baixe o arquivo do painel do OneSignal durante a [configuração do Web SDK](./web-sdk-setup) ou [do GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).

    Alternativamente, crie um arquivo chamado `OneSignalSDKWorker.js` com a seguinte linha de código:

    ```javascript theme={null}
    importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
    ```

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

  <Step title="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.

    <Warning>
      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](#migration-guide).
    </Warning>
  </Step>

  <Step title="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:

    <Frame caption="Conteúdo esperado do arquivo service worker no navegador">
      <img src="https://mintcdn.com/onesignal/eSOC1PsvyAo3Gten/images/push/service-worker-code-example.png?fit=max&auto=format&n=eSOC1PsvyAo3Gten&q=85&s=3add122d37c9f12a39f1d7e3d40eeaba" alt="Browser displaying the single importScripts line inside OneSignalSDKWorker.js" width="1678" height="322" data-path="images/push/service-worker-code-example.png" />
    </Frame>

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

  <Step title="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**.

    <Frame caption="Configuração do caminho do service worker no painel">
      <img src="https://mintcdn.com/onesignal/npQH4TNAoIbyiAie/images/dashboard/service-worker-configuration-typical-site-setup.png?fit=max&auto=format&n=npQH4TNAoIbyiAie&q=85&s=0bc69998eea5273d287af408c6e925b3" alt="OneSignal dashboard fields for service worker path, filename, and registration scope" width="1840" height="794" data-path="images/dashboard/service-worker-configuration-typical-site-setup.png" />
    </Frame>

    | 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 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()`](./web-push-custom-code-setup):

    ```html theme={null}
    <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â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 ou abaixo onde o arquivo está hospedado. Use um caminho que nunca sirva páginas voltadas ao usuário. | `"/push/onesignal/"`                     |
  </Step>

  <Step title="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.

    | 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://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Registering_your_worker). |
    | **HTTPS**                    | Service workers requerem um contexto seguro. `localhost` é a única exceção durante o desenvolvimento.                                                                                                                                                          |

    <Check>
      A configuração do service worker está concluída.
    </Check>

    <Card title="Configuração do Web SDK" icon="browsers" href="./web-sdk-setup">
      Continue com o guia de configuração do Web SDK para as próximas etapas.
    </Card>
  </Step>
</Steps>

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

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

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

```javascript theme={null}
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](#step-4-configure-the-sdk-path-subdirectory-only) 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.

<Accordion title="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 OneSignal**

  Confirme que `OneSignalSDKWorker.js` contém apenas:

  ```javascript theme={null}
  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](#step-4-configure-the-sdk-path-subdirectory-only). Nenhuma outra alteração é necessária.

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

  **Se o seu arquivo contém OneSignal + outro código**

  Seu service worker pode incluir chamadas `importScripts` adicionais (p. ex., ao seguir o guia [Combinar múltiplos service workers](#combining-multiple-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:

  <Steps>
    <Step title="Adicionar um comentário de retenção ao arquivo existente">
      Acima da linha `importScripts` do OneSignal em seu service worker atual, adicione:

      ```javascript theme={null}
      // 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.
    </Step>

    <Step title="Criar um novo service worker dedicado do OneSignal">
      Crie `OneSignalSDKWorker.js` em um subdiretório (p. ex., `/push/onesignal/`) contendo apenas:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="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](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="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.
    </Step>

    <Step title="Limpeza">
      [Exclua usuários inativos](./delete-users) mais antigos que o período de retenção escolhido, depois remova a linha `importScripts` do OneSignal do arquivo service worker original.
    </Step>
  </Steps>

  **Opção 2: Alterar o nome de arquivo ou localização do arquivo**

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

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

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

  <Steps>
    <Step title="Adicionar um comentário de retenção ao arquivo antigo">
      ```javascript theme={null}
      // 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");
      ```
    </Step>

    <Step title="Criar o novo arquivo na nova localização">
      Coloque `OneSignalSDKWorker.js` (ou o nome de arquivo escolhido) no novo diretório com:

      ```javascript theme={null}
      importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
      ```
    </Step>

    <Step title="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](#step-4-configure-the-sdk-path-subdirectory-only).
    </Step>

    <Step title="Aguardar a migração dos assinantes">
      Novos visitantes e visitantes recorrentes se registram com o novo arquivo automaticamente. Aguarde pelo menos um ano.
    </Step>

    <Step title="Limpeza">
      [Exclua usuários inativos](./delete-users) mais antigos que seu período de retenção, depois remova o arquivo antigo.
    </Step>
  </Steps>

  **Se o seu arquivo contém OneSignal + outro código**

  Siga as etapas da **Opção 1: Alterar apenas o escopo** acima. O processo é o mesmo.
</Accordion>

***

## 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](#migration-guide) e o guia [Notificações push web não exibidas](./notifications-not-shown-web-push).

### 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](#combining-multiple-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](#step-4-configure-the-sdk-path-subdirectory-only) 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.