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

# Configuração de web push para iOS

> Guia completo para habilitar notificações web push em dispositivos iOS e iPadOS, incluindo configuração de arquivo manifest, estratégias de onboarding de usuário e melhores práticas de implementação para navegadores Safari, Chrome e Edge.

export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
  const baseUrl = 'https://onesignal.github.io/sdk-releases';
  const buildUrl = (theme, sdkFilter, viewMode) => {
    const url = new URL(baseUrl);
    const params = new URLSearchParams();
    if (theme) {
      params.set('theme', theme);
    }
    if (sdkFilter) {
      params.set('sdk', sdkFilter);
    }
    if (viewMode) {
      params.set('viewMode', viewMode);
    }
    if (params.toString()) {
      url.search = params.toString();
    }
    return url.toString();
  };
  const detectTheme = () => {
    if (document.documentElement.classList.contains('dark')) {
      return 'dark';
    }
    return 'light';
  };
  const [theme, setTheme] = useState('light');
  const [iframeSrc, setIframeSrc] = useState(() => {
    const initialTheme = detectTheme();
    return buildUrl(initialTheme, sdkFilter, viewMode);
  });
  useEffect(() => {
    const currentTheme = detectTheme();
    setTheme(currentTheme);
    setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleThemeChange = () => {
      const newTheme = detectTheme();
      setTheme(newTheme);
      setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
    };
    if (mediaQuery.addEventListener) {
      mediaQuery.addEventListener('change', handleThemeChange);
    } else {
      mediaQuery.addListener(handleThemeChange);
    }
    window.addEventListener('storage', handleThemeChange);
    const observer = new MutationObserver(handleThemeChange);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ['class', 'data-theme']
    });
    return () => {
      if (mediaQuery.removeEventListener) {
        mediaQuery.removeEventListener('change', handleThemeChange);
      } else {
        mediaQuery.removeListener(handleThemeChange);
      }
      window.removeEventListener('storage', handleThemeChange);
      observer.disconnect();
    };
  }, [sdkFilter, viewMode]);
  const getIframeHeight = () => {
    if (viewMode === 'table') {
      return '450';
    }
    if (viewMode === 'mini') {
      return '170';
    }
    return '800';
  };
  const iframeHeight = height || getIframeHeight();
  return <Frame {...frameProps}>
      <iframe src={iframeSrc} width="100%" height={iframeHeight} frameBorder="0" style={{
    border: "none"
  }} title="SDK Releases" key={iframeSrc} />
    </Frame>;
};

<SdkReleasesIframe sdkFilter="react,vue,vue3,angular,wordpress" viewMode="table" height="380" />

A Apple começou a suportar notificações push no iOS e iPadOS 16.4+ para web apps adicionados à tela inicial de um usuário. Esta funcionalidade funciona através dos navegadores Safari, Chrome e Edge, abrindo novas oportunidades de engajamento para empresas web-first. Este guia abrangente cobre tudo que você precisa para implementar notificações web push do iOS com sucesso.

<Frame caption="Exemplo de notificação web push em dispositivo móvel.">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/2477862-iOS_push-doc.jpg?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=86aed6cdbed6645e568a644ac725f414" width="806" height="929" data-path="images/docs/2477862-iOS_push-doc.jpg" />
</Frame>

***

## Atualizações importantes para 2025

**Suporte Multi-Navegador**: Notificações web push agora funcionam em todos os principais navegadores no iOS/iPadOS 16.4+ incluindo Safari, Chrome e Edge.

**Melhorias do iOS 17+**: Implementação aprimorada com APIs relevantes habilitadas por padrão, tornando web push mais acessível aos usuários.

**Considerações de Confiabilidade**: Alguns desenvolvedores relatam problemas ocasionais de confiabilidade onde notificações web push do iOS podem funcionar inicialmente mas depois parar inesperadamente. Monitore suas taxas de entrega de notificação e tenha estratégias de engajamento de fallback preparadas.

***

## Requisitos

* **Versão iOS/iPadOS**: 16.4 ou superior
* **Origem HTTPS**: Conexão segura com design responsivo
* **Manifest de Aplicação Web**: Arquivo `manifest.json` válido com configurações corretas
* **Instalação na Tela Inicial**: Web app deve ser adicionado à tela inicial do usuário de qualquer navegador suportado
* **Ação Iniciada pelo Usuário**: Usuário deve interagir com seu site antes que prompts de permissão possam aparecer
* **Service Worker OneSignal**: Necessário para entrega de notificação

### Verificação de progressive web app (PWA)

Se seu website já é um [Progressive Web App (PWA)](https://onesignal.com/blog/what-is-a-pwa/), nenhuma atualização adicional de site é necessária. Use [Lighthouse no Chrome DevTools](https://developer.chrome.com/docs/lighthouse/overview/#devtools) para auditar se seu site se qualifica como PWA.

***

## Configuração

### 1. Crie seu manifest de aplicação web

Um Web Application Manifest (`manifest.json`) é um arquivo JSON que define como sua aplicação web aparece e se comporta quando instalada no dispositivo de um usuário. Para web push do iOS, este arquivo é **obrigatório**.

#### Campos obrigatórios do manifest

Seu `manifest.json` deve incluir estes campos essenciais:

* **`$schema`** (recomendado): URL do schema JSON para validação e suporte IDE
* **`name`** (obrigatório): Nome completo da aplicação exibido aos usuários
* **`display`** (obrigatório): Deve ser definido como `"standalone"` ou `"fullscreen"` para compatibilidade iOS
* **`start_url`** (obrigatório): URL de ponto de entrada quando a aplicação inicia
* **`icons`** (obrigatório): Array de objetos de ícone com múltiplos tamanhos
* **`id`** (recomendado): Identificador único permitindo múltiplas instâncias de app

#### Exemplo de arquivo manifest

```json theme={null}
{
  "$schema": "https://json.schemastore.org/web-manifest-combined.json",
  "name": "OneSignal Manifest Example",
  "short_name": "OS Manifest",
  "display": "standalone",
  "start_url": "/",
  "theme_color": "#E54B4D",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-256x256.png", "sizes": "256x256", "type": "image/png" },
    { "src": "/icon-384x384.png", "sizes": "384x384", "type": "image/png" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "id": "?homescreen=1"
}
```

#### Passos de implementação

1. **Colocação do Arquivo**: Coloque `manifest.json` no diretório raiz do seu website
2. **Integração HTML**: Adicione esta tag link à seção `<head>` de todas as páginas:

```html theme={null}
<link rel="manifest" href="/manifest.json"/>
```

3. **Preparação de Ícone**: Crie ícones PNG de alta qualidade em múltiplos tamanhos (192x192, 256x256, 384x384, 512x512 pixels recomendados)

<Note>
  Use ferramentas como [SimiCart Manifest Generator](https://www.simicart.com/manifest-generator.html/) para criar rapidamente arquivos manifest, ou valide existentes com [Manifest Tester](https://manifesttester.com/).
</Note>

### 2. Adicione o service worker OneSignal

Se você já completou nossa [configuração do Web SDK](./web-sdk-setup) e pode receber notificações web push em outros navegadores, este passo está completo. Veja a documentação do [Service Worker OneSignal](./onesignal-service-worker) para instruções detalhadas de configuração.

### 3. Configure prompts de permissão

[Prompts de permissão Web](./permission-requests) existentes da sua [configuração do Web SDK](./web-sdk-setup) funcionarão em dispositivos iOS **apenas após usuários adicionarem seu site à tela inicial deles e abrirem a partir de lá**. Este é um requisito de design da Apple.

### 4. Guie usuários para "Adicionar à Tela Inicial"

Ao contrário de dispositivos desktop ou Android onde prompts de permissão aparecem baseados em suas configurações, iOS requer uma jornada de usuário específica que você deve facilitar.

#### A jornada de usuário necessária

Usuários devem completar estes passos para receber notificações:

1. Visitar seu website no Safari, Chrome ou Edge no iOS/iPadOS 16.4+
2. Clicar no botão **Share** do navegador
3. Selecionar opção **Add to Home Screen**
4. Salvar o app no dispositivo
5. Abrir o app da tela inicial (não do navegador)
6. Interagir com seu botão de inscrição para acionar o prompt de permissão nativo

<Frame caption="Adicionando um Website à Tela Inicial no iOS">
  <img src="https://mintcdn.com/onesignal/2iWYYuHf1gqm06bv/images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg?fit=max&auto=format&n=2iWYYuHf1gqm06bv&q=85&s=54cb44f40d70397099b32375a3e97683" width="1346" height="736" data-path="images/docs/638b3a1-ios-web-push-add-to-home-screen.jpg" />
</Frame>

#### Estratégias de onboarding de usuário

Como este processo não é intuitivo, implemente orientação clara através de:

* **Banners de website**: Exiba banners especificamente em dispositivos Apple móveis explicando o valor das notificações e fornecendo instruções passo a passo.

* **Guias visuais**: Use screenshots e setas para mostrar aos usuários exatamente onde tocar.

* **Tempo**: Apresente a orientação após usuários demonstrarem engajamento com seu conteúdo.

#### Exemplos de implementação

Aqui estão abordagens efetivas de aplicações reais:

<Frame caption="Exemplo de banner solicitando usuários a adicionar à tela inicial">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/0b97752-image.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=bfec43a31639c25a6eab85961334a8bd" width="2055" height="1257" data-path="images/docs/0b97752-image.png" />
</Frame>

<Frame caption="Orientação visual passo a passo">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4e970c1-image.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=04aef274f934dd44f34eaa8bd7e37360" width="2055" height="1257" data-path="images/docs/4e970c1-image.png" />
</Frame>

<Frame caption="Mensagem focada em benefícios">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/208b123-image.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=c8bd38cfb229c68500a9260b8b6e4b33" width="2055" height="1257" data-path="images/docs/208b123-image.png" />
</Frame>

<Frame caption="Call-to-action claro com pistas visuais">
  <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7ec125a-image.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=c532cb02bcde365092a6bc001beaaf06" width="2055" height="1257" data-path="images/docs/7ec125a-image.png" />
</Frame>

#### Soluções open source

Considere implementar esta popular solução de banner open-source:

**Projeto GitHub**: [add-to-home-screen por rajatsehgal](https://github.com/rajatsehgal/add-to-home-screen)

<Frame caption="Exemplo de um prompt de banner Add to Home Screen de um projeto open source por rajatsehgal.">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=ccc678721ffc636fa5ddb4a71efb7ed0" width="1149" height="2142" data-path="images/docs/b63b31f-GitHub_A2HS_Ex_1.jpg" />
</Frame>

Exemplos adicionais de banner e melhores práticas disponíveis em [web.dev](https://web.dev/promote-install/).

### 5. Teste e validação

#### Teste de arquivo manifest

1. **Verificação de Acessibilidade**: Navegue para `https://yoursite.com/manifest.json` para garantir acessibilidade pública
2. **Browser DevTools**:
   * Abra Chrome DevTools (F12)
   * Vá para aba Application → Manifest
   * Revise quaisquer erros ou avisos
3. **Validadores Online**:
   * [Manifest Tester](https://manifesttester.com/)
   * [Redirection.io Validator](https://redirection.io/tools/web-app-manifest/validator)
   * [ValidBot Manifest Wizard](https://www.validbot.com/tools/app-manifest-wizard.php)

#### Teste de notificação push ponta a ponta

1. Visite seu website em dispositivo iOS 16.4+ usando Safari, Chrome ou Edge
2. Clique no botão **Share** do navegador
3. Selecione **Add to home screen**
4. Salve o app no seu dispositivo
5. Abra o app da tela inicial (passo crucial)
6. Acione seu botão de inscrição - o prompt de permissão nativo deve aparecer
7. Conceda permissão e teste entrega de notificação

#### Notas importantes de teste

**Requisitos para re-testar**: Para testar novamente no mesmo dispositivo:

* Remova o app da tela inicial
* Limpe cache do navegador (Settings > Safari/Chrome/Edge > Clear cache)
* Repita o processo

**Recuperação de permissão negada**: Se permissão for negada, o app da tela inicial deve ser removido e re-adicionado para que o prompt de permissão apareça novamente.

**Problemas comuns para verificar**:

* Assegure que campo `display` é `"standalone"` ou `"fullscreen"`
* Verifique que todos os caminhos de ícone são acessíveis
* Confirme que manifest serve com tipo MIME correto (`application/manifest+json`)
* Teste para erros CORS

***

## Solução de Problemas

**Manifest não carregando**: Verifique caminho do arquivo, requisito HTTPS e configuração de tipo MIME no seu servidor.

**Ícones não exibindo**: Verifique acessibilidade do arquivo de ícone e especificações de tamanho corretas no manifest.

**Prompt de permissão não aparecendo**: Assegure que usuário acessou site via app da tela inicial e clicou em um elemento interativo primeiro.

**Notificações não entregando**: Verifique que service worker OneSignal está propriamente instalado e verifique console do navegador para erros.

***

## Próximos passos

<Check>
  Você está pronto para enviar notificações! Continue para a documentação de [Push](./push) ou use nossa API [Create message](/reference/create-message) para começar a engajar seus usuários iOS com notificações web push.
</Check>

Para sucesso contínuo, monitore suas métricas de desempenho de web push do iOS e considere implementar estratégias de progressive enhancement que lidam graciosamente com os passos adicionais necessários para usuários iOS enquanto fornecem experiências perfeitas em outras plataformas.

***