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

# FAQ de web push

> Guia completo para configuração de Notificações Web Push do OneSignal, requisitos, compatibilidade de navegador, mudanças de domínio e solução de problemas comuns para desenvolvedores e proprietários de websites.

## Requisitos de web push

Seu website deve atender todos os seguintes requisitos para que Web Push funcione:

**APIs de navegador necessárias**

* [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
* [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
* [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)

**Segurança & conexão**

* ✅ Apenas HTTPS (com certificado SSL válido)
* ✅ [Service worker](./onesignal-service-worker) do OneSignal instalado
* ✅ Navegador deve alcançar:
  * Servidores push do navegador (ex: FCM, Mozilla)
  * `api.onesignal.com`

**Estado do usuário**

* ✅ Permissão de notificação concedida pelo usuário
* ❌ Não em modo Anônimo/Privado/Convidado
* ❌ Dados do site não limpos (deleta subscriptions)

<Warning>Limpar dados do navegador (cookies, armazenamento do site) automaticamente cancela inscrição de usuários de notificações push.</Warning>

### Requisitos iOS/iPadOS

Para receber push no iOS ou iPadOS:

* iOS 16.4+ ou iPadOS 16.4+
* Site deve ser adicionado à tela inicial e aberto de lá
* Arquivo `manifest.json` válido com campos obrigatórios
* Usuários devem aceitar permissões de notificação após abrir como web app

<Card title="Configuração de web push para iOS" href="./web-push-for-ios" arrow={true}>
  Siga passos específicos da Apple para habilitar web push em iPhones e iPads rodando iOS 16.4+.
</Card>

***

## Suporte de navegador & plataforma

### Compatibilidade de navegador por sistema operacional

|                                      Browser                                     | Windows PC |  macOS  | Android | iOS (iPhone, iPad) |
| :------------------------------------------------------------------------------: | :--------: | :-----: | :-----: | :----------------: |
|             [Chrome 50+](https://en.wikipedia.org/wiki/Google_Chrome)            |   **Sim**  | **Sim** | **Sim** |      **Sim** ¹     |
|               [Firefox 47+](https://en.wikipedia.org/wiki/Firefox)               |   **Sim**  | **Sim** | **Sim** |      **Sim** ¹     |
|        [Safari 10+](https://en.wikipedia.org/wiki/Safari_\(web_browser\))        |     Não    | **Sim** |   Não   |      **Sim** ¹     |
|       [Microsoft Edge 18+](https://en.wikipedia.org/wiki/Microsoft_Edge) ²       |   **Sim**  | **Sim** | **Sim** |      **Sim** ¹     |
|          [Opera](https://en.wikipedia.org/wiki/Opera_\(web_browser\)) ²          |   **Sim**  | **Sim** | **Sim** |      **Sim** ¹     |
| [Samsung Internet](https://en.wikipedia.org/wiki/Samsung_Internet_for_Android) ² |     Não    |   Não   | **Sim** |      **Sim** ¹     |
|             [Yandex](https://en.wikipedia.org/wiki/Yandex_Browser) ²             |   **Sim**  | **Sim** | **Sim** |      **Sim** ¹     |
|             [UC Browser](https://en.wikipedia.org/wiki/UC_Browser) ²             |   **Sim**  |   Não   | **Sim** |      **Sim** ¹     |
|      [Internet Explorer](https://en.wikipedia.org/wiki/Internet_Explorer) ³      |     Não    |   Não   |   Não   |         Não        |
|              [DuckDuckGo](https://en.wikipedia.org/wiki/DuckDuckGo)              |     Não    |   Não   |   Não   |         Não        |

* ¹ iOS requer instalação de web app (veja requisitos de [configuração de web push para iOS](./web-push-for-ios) acima)
* ² Navegadores baseados em Chromium aparecem como "Chrome" no analytics do OneSignal
* ³ Internet Explorer está descontinuado e não recebe mais atualizações

<Warning> Modo Anônimo, Modo de Navegação Privada e Modo de Navegador Convidado **não** suportam Web Push em qualquer plataforma.</Warning>

***

## Mudanças de domínio & migração

### Entendendo política de origem do navegador

Navegadores vinculam subscriptions de web push a uma [origem (domínio/URL do site)](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) específica por razões de segurança. **Você não pode transferir inscritos entre origens diferentes** - esta é uma limitação do navegador, não uma restrição do OneSignal.

**Origens diferentes incluem:**

* HTTP vs HTTPS (ex: `http://mysite.com` → `https://mysite.com`)
* www vs não-www (ex: `www.mysite.com` vs `mysite.com`)
* Domínios/subdomínios diferentes (ex: `domain1.com` vs `domain2.com` ou `sub1.domain.com` vs `sub2.domain.com`)

### Opções de migração

Ao mudar a origem do seu site, escolha uma destas abordagens:

<Tabs>
  <Tab title="Novo App OneSignal (Recomendado)">
    **Melhor para**: A maioria das mudanças de domínio, especialmente quando você quer uma migração limpa

    1. **Crie novo App OneSignal** para seu novo domínio
    2. **Estratégia de envio duplo**: Continue enviando do app antigo, mas defina "Launch URL" para seu novo domínio
    3. **Transição gradual**:
       * Remetentes de alta frequência (1+ notificações/dia): 2 semanas de transição
       * Remetentes de frequência média (2+ notificações/semana): 2 meses de transição
    4. **Notificações de migração**: Envie 1-2 mensagens como "Mudamos! Visite nosso novo site para continuar atualizado" no início e fim da transição

    <Warning> Enviar mensagens idênticas de ambos os apps criará notificações duplicadas para usuários inscritos em ambos.</Warning>
  </Tab>

  <Tab title="Atualizar App & Deletar Inscritos Antigos">
    **Melhor para**: Quando você precisa manter o mesmo ID de App OneSignal

    1. Use a API [Update an app](/reference/update-an-app) com:
       * `name`: Nome do seu app/site
       * `chrome_web_origin`: URL do novo site
       * `chrome_web_default_notification_icon`: URL da imagem do ícone

    2. **Delete inscritos antigos** para prevenir duplicatas:
       * Crie segmento: "Device Type is Web Push"
       * [Delete todos os usuários no segmento](./delete-users)
  </Tab>
</Tabs>

### Upgrade de HTTP para HTTPS

Fazer upgrade de HTTP para HTTPS cria uma nova origem. Siga os passos de migração de domínio acima pois navegadores tratam sites HTTPS como completamente separados de suas versões HTTP.

***

## Múltiplos sites & subdomínios

### Limitações de app único

Devido à política de mesma origem do navegador, você **não pode** usar um App OneSignal para múltiplas origens como:

* `https://mysite.com` e `https://www.mysite.com`
* `https://main.com` e `https://shop.main.com`

### Soluções para múltiplas origens

<Tabs>
  <Tab title="Estratégia de Origem Única">
    * Inscreva usuários apenas no seu domínio principal
    * Redirecione usuários de outras origens para domínio principal para inscrição
    * Redirecione de volta para página original após inscrição
  </Tab>

  <Tab title="Apps Separados">
    * Crie Apps OneSignal individuais para cada origem
    * Aceite que usuários podem receber notificações duplicadas se inscritos em múltiplos sites
  </Tab>
</Tabs>

***

### Cenários de suporte a idioma

<Tabs>
  <Tab title="Mesma Origem (Recomendado)">
    * URLs como `https://mysite.com/en/` ou `https://mysite.com/es/`
    * Use App OneSignal único
    * Siga [guia de prompts multi-idioma](./permission-requests#faq)
    * Implemente [Idioma & Localização](./multi-language-messaging)
  </Tab>

  <Tab title="Origens Diferentes">
    * URLs como `https://en.mysite.com` ou `https://es.mysite.com`
    * Requer Apps OneSignal separados para cada subdomínio
  </Tab>
</Tabs>

***

## Configuração avançada

### Múltiplos apps OneSignal no mesmo site

* **Não recomendado** - causa conflitos de subscription.
* **O que acontece**: OneSignal reinscreve automaticamente usuários no App ID visitado mais recentemente, fazendo inscritos saltarem entre apps e criando muitos dispositivos não inscritos.
* **Melhor abordagem**: Use [Tags](./add-user-data-tags) para segmentar usuários dentro de um único app.

### Sites em subpasta

Web push opera no nível de origem. Para sites em subpastas (ex: `https://example.com/blog`), use a origem principal (`https://example.com`) para configuração.

### Auto-hospedagem de arquivos SDK

**Fortemente desencorajado**. Especificações de push do navegador mudam frequentemente, e o OneSignal atualiza arquivos imediatamente para manter compatibilidade. Use URLs CDN do OneSignal das suas Configurações de Web Push.

### Código init personalizado

Código `init` personalizado apenas funciona com [Configuração de Código Personalizado](./web-push-custom-code-setup).

**Usuários de Configuração Típica ou Website Builder**: Código init personalizado será ignorado pelo SDK OneSignal. Se você precisa atrasar inicialização, use os [métodos de privacidade](./web-sdk-reference#privacy).

***

## Desenvolvimento & testes

### Teste de ambiente local

Veja [Configuração do Web SDK > Testes locais](./web-sdk-setup#local-testing) para configuração completa de teste local.

### Integração de service worker

O OneSignal pode trabalhar junto com service workers existentes e PWAs. Veja [Integrando Múltiplos Service Workers](./onesignal-service-worker) para detalhes de implementação.

***

## Spam de push

Notificações push não são projetadas para serem usadas para anúncios, spam de usuários ou campanhas enganosas.

Se seu app for detectado enviando notificações spam, navegadores podem enviar aos seus usuários uma notificação de "Aviso de spam".

Evite enviar notificações que:

* Não são relevantes para os usuários
* Usam palavras como "Anúncios" ou linkam para uma página não relacionada ao app
* Não são de uma fonte confiável (ex: uma marca com a qual você não está associado)

<Warning>
  Veja [Combatendo Notificações Indesejadas com Machine Learning no Chrome](https://blog.chromium.org/2025/05/fighting-unwanted-notifications-with.html) para mais informações.
</Warning>

Se seu app está sendo marcado como spam, você pode:

* Revisar seu conteúdo de notificação e remover qualquer coisa que possa ser considerada spam. Isso inclui:
  * As palavras "Anúncios" ou "Anúncio" no título ou corpo
  * Links para páginas não relacionadas ao app
  * Links para páginas que não são de uma fonte confiável (ex: uma marca com a qual você não está associado)
* Continuar enviando e monitorar relatórios adicionais.

***

## Solução de problemas

### Tempo de implantação de atualização

* **Arquivos de Service Worker**: cache de 24 horas
* **Web SDK**: cache de 3 dias

Planeje adequadamente ao implantar atualizações críticas.

### Problemas de notificação do Chrome no macOS

Para usuários do Chrome no macOS, assegure que notificações estão habilitadas para **ambos**:

1. App **Google Chrome** (Menu Apple > Settings > Notifications)
2. App **Google Chrome Helper**

Sem ambos habilitados, notificações não aparecerão no centro de notificações.

### Próximos passos após configuração

1. **Teste completamente** através dos seus navegadores e dispositivos suportados
2. **Implemente tratamento de erro adequado** para requisições de permissão
3. **Configure analytics** para monitorar taxas de subscription
4. **Planeje sua estratégia de notificação** para evitar fadiga do usuário
5. **Considere teste A/B** do tempo e mensagem de requisição de permissão

### Armadilhas comuns de migração

* **Limpeza de dados do navegador** cancela inscrição de usuários automaticamente
* **Notificações duplicadas** durante transições de app duplo
* **iOS requer instalação de web app** antes que push funcione
* **Modos Privado/Anônimo** nunca suportam notificações push
* **Service workers devem ser acessíveis** na raiz do seu site ou subdiretório configurado

***

## Próximos passos

* [Configuração do Web SDK](./web-sdk-setup)
* [Referência do Web SDK](./web-sdk-reference)

***