> ## 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 do Web SDK
> Adicione notificações web push do OneSignal ao seu website com o SDK JavaScript, configuração do service worker e configuração do dashboard.
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
;
};
## Visão geral
Este guia orienta você na adição de notificações web push do OneSignal ao seu site — desde a configuração do dashboard até a instalação do SDK. OneSignal suporta Chrome, Firefox, Edge, Safari e [outros navegadores principais](./web-push-setup-faq).
***
## Requisitos
* Website HTTPS: Web push não funciona em HTTP ou em modos incógnito/privado.
* Acesso ao servidor: Você precisará fazer upload de um arquivo service worker para seu site.
* Origem única: Web push segue a [política de mesma origem](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). Se você tem múltiplas origens (domínios/subdomínios), precisará de múltiplos apps OneSignal (um por origem). Para cumprir com esta limitação do navegador, você pode:
* Redirecionar tráfego para uma origem única para subscriptions.
* Criar múltiplos apps OneSignal—um por origem.
Se sua equipe já criou uma conta com OneSignal, [peça para ser convidado como função de admin](./manage-team-members) para que possa configurar o app. Caso contrário, inscreva-se para uma conta gratuita em [onesignal.com](https://onesignal.com) para começar!
***
## Configure seu app e plataforma OneSignal
No dashboard OneSignal:
* Vá para **Settings > Push & In-App > Web**.
Selecione o tipo de integração:
Gerencie prompts e configurações diretamente através do dashboard OneSignal sem codificação adicional.
Necessário se usando WordPress com nosso plugin oficial.
Para desenvolvedores que precisam de controle completo sobre prompts e configuração do SDK.
### Configuração do site
Adicione os detalhes do site:
* **Nome do Site**: O nome do seu site e título de notificação padrão.
* **URL do Site**: A URL do seu site. Veja [URL do Site](#site-url) para mais detalhes.
* **Auto Resubscribe**: Habilite isto para reinscrever automaticamente usuários que limpam seus dados de navegador quando retornam ao seu site (nenhum novo prompt de permissão necessário)
* **URL de Ícone Padrão**: Faça upload de uma imagem PNG ou JPG quadrada de 256x256px que aparece em notificações e prompts. Se não definido, usamos um sino para o ícone padrão.
#### URL do Site
Insira a [origem](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) exata do seu site, ex: `https://seudominio.com`. Evite usar `www.` se seu site não estiver configurado dessa forma.
Se você tem múltiplas origens:
* Redirecione para uma origem única.
* Ou configure um app OneSignal por origem.
#### Testes locais
Nosso web SDK pode ser testado em ambientes localhost. Se você está testando em localhost, recomendamos configurar um app OneSignal diferente do seu app de produção.
Defina a **URL DO SITE** para corresponder exatamente à URL do seu ambiente localhost. Deve ser uma URL localhost comum, exemplos:
* `http://localhost`
* `https://localhost:3000`
* `http://127.0.0.1`
* `https://127.0.0.1:5000`
Se seu localhost está usando HTTP, selecione **Treat HTTP localhost as HTTPS for testing**.
Google Chrome trata `http://localhost` e `http://127.0.0.1` como origens seguras, permitindo integrações HTTPS mesmo em HTTP. É por isso que você não pode testar outras origens não-padrão em HTTPS localhost.
#### Adicione `allowLocalhostAsSecureOrigin` às suas opções `init` do OneSignal
Ao inicializar OneSignal no seu site localhost, adicione `allowLocalhostAsSecureOrigin: true,` às suas opções `init` do OneSignal.
Adicionalmente, se você está testando localhost em HTTPS com um certificado auto-assinado, pode ter que pedir ao Chrome para ignorar certificados inválidos para testes com: ` --allow-insecure-localhost`. Firefox e Safari fornecem mecanismos integrados para adicionar exceções para certificados de segurança.
```html theme={null}
```
### Prompt de permissões
Configuração de site típico permite que você ou seus membros de equipe adicionem, removam e atualizem prompts de permissão através do dashboard OneSignal a qualquer momento.
Configure quando e como o diálogo de permissão do navegador aparece para seus usuários.
### Notificação de boas-vindas (opcional)
Você também pode definir uma notificação de boas-vindas para ser enviada aos usuários quando eles se inscrevem para notificações push.
### Configurações avançadas
Recursos adicionais configuráveis no dashboard OneSignal.
#### Webhooks
Nosso web SDK fornece a capacidade de fazer `POST` de certos eventos de web push para uma URL de sua escolha.
Web Push Webhooks são uma implementação separada de [Event Webhooks](./event-streams) e não podem ser usados de forma intercambiável.
Envie eventos de web push para seu servidor via requisições POST.
#### Service workers
Na próxima página de configuração de web push, você receberá o arquivo service worker `OneSignalSDKWorker.js`.
Nosso web SDK por padrão procura este arquivo na raiz do seu site. Se você quiser mudar a localização, nome e/ou escopo do nosso arquivo service worker, é aqui que você pode atualizar essas configurações.
* **Caminho para arquivos service worker** é o caminho para o diretório onde você colocará estes arquivos.
* **Nomes de arquivo service worker principal e atualizador** podem ser apenas `OneSignalSDKWorker.js` ou se você quiser renomear este arquivo. Deve usar extensão de arquivo `.js`.
* **Escopo de registro do service worker** são as páginas nas quais este arquivo pode funcionar. Para notificações push, isso não importa e foi originalmente projetado para casos onde você quer adicionar mais funcionalidade ao arquivo service worker. Você deve definir isso como o mesmo caminho da sua localização.
Com este exemplo, você deve ver o código do arquivo publicamente acessível em `https://seudominio.com/push/onesignal/OneSignalSDKWorker.js`
Configuração avançada do service worker, integração personalizada e migração de outros provedores.
#### Comportamento de clique
Controle como usuários navegam para a [URL](./links) que você define quando clicam na notificação.
Se o usuário não tem seu site aberto em nenhuma aba, o navegador abre uma nova aba e navega para a URL da notificação. Se o usuário já tem seu site aberto, o comportamento depende da configuração que você escolher:
| Configuração | Corresponde em | Ação |
| --------------------------- | ------------------------------------- | ------------------------------------------------------ |
| **Exact Navigate** (padrão) | URL exata (ex: `example.com/product`) | Navega para a URL da notificação na aba correspondente |
| **Origin Navigate** | Origem (ex: `example.com`) | Navega para a URL da notificação na aba correspondente |
| **Exact Focus** | URL exata | Foca na aba correspondente sem recarregar |
| **Origin Focus** | Origem | Foca na aba correspondente sem recarregar |
#### Persistência
O comportamento padrão de web push é que eles aparecem no dispositivo por aproximadamente 5 segundos antes de serem movidos para o Centro de Notificações onde são mantidos por cerca de 1 semana antes de serem removidos pelo sistema operacional.
Alguns dispositivos e versões do Chrome e Edge permitem persistir notificações por mais tempo na tela. Isso significa que a notificação ficará na tela até que o usuário interaja com ela. **Isso pode incomodar seus usuários e não é recomendado.** Além disso, se você habilitar persistência, afetará como notificações aparecem para inscritos reduzindo contagem de caracteres e pode afetar como imagens e botões são exibidos.
Ao mudá-las, elas entrarão em vigor apenas para inscritos que visitarem o site com as configurações atualizadas. Se você não vir estas opções mudarem, você precisará esperar
#### Certificado Safari (Opcional)
OneSignal fornece automaticamente os certificados necessários para funcionar com navegadores Safari sem custo adicional. Se você já tem seus próprios Certificados Safari Web Push, ative esta opção para fazer upload do seu `Safari Web .p12 Push Certificate` e senha.
***
## Fazer upload do arquivo service worker
Adicione o arquivo service worker `OneSignalSDKWorker.js` ao seu site. Baixe-o no dashboard do OneSignal ou [no GitHub](https://github.com/OneSignal/OneSignal-Website-SDK/files/11480764/OneSignalSDK-v16-ServiceWorker.zip).
Coloque este arquivo no diretório raiz do seu site ou em um subdiretório. Se você colocá-lo em um subdiretório, precisará definir o **Caminho para arquivos service worker** na seção [Configurações avançadas > Service workers](#service-workers).
Uma vez que o arquivo esteja no seu servidor, verifique o seguinte para garantir que funciona:
Certifique-se de que o arquivo está localizado no mesmo **Caminho para arquivos service worker** definido em [Configurações avançadas > Service workers](#service-workers). Se você não atualizou essas configurações, então você deve ter colocado o arquivo na sua raiz. Por exemplo:
* `https://seudominio.com/OneSignalSDKWorker.js`
* `https://seudominio.com/algum-subdiretorio/OneSignalSDKWorker.js`
O arquivo `OneSignalSDKWorker.js` deve ser publicamente acessível e disponível na sua origem. Não pode ser hospedado via CDN ou colocado em uma origem diferente com redirecionamento.
Quando você visitar a URL para o arquivo, você deve ver o código.
Este é um arquivo javascript e precisa ser servido como tal. Não pode ter um content-type de text/html.
Configuração avançada e migração de outros provedores de web push.
## Adicione código ao seu site
O código do JavaScript SDK abaixo funciona em qualquer site. Se seu site é construído com [Angular](./angular-setup), [React JS](./react-js-setup) ou [Vue JS](./vue-js-setup), siga esses links.
Para inicializar OneSignal no seu site com nosso JavaScript SDK, copie/cole o código fornecido nas tags `` do seu website. O dashboard do OneSignal fornece o mesmo trecho pré-preenchido com seu [app ID](./keys-and-ids).
```javascript theme={null}
```
### Suporte de web push para iOS
Apple começou a suportar notificações web push em iPhones e iPads rodando iOS 16.4+. Diferente de dispositivos Android onde web push simplesmente "funciona" desde que visitado em um navegador suportado, Apple adicionou alguns requisitos a mais como um arquivo `manifest.json` e uma ação do usuário para adicionar seu site à tela inicial deles.
Adicione o arquivo `manifest.json` necessário e guie usuários a adicionar seu site à tela inicial deles.
***
## Testando a integração do OneSignal SDK
Este guia ajuda você a verificar se sua integração do OneSignal SDK está funcionando corretamente testando notificações push e registro de inscrição.
### Verifique inscrições de web push
* Use Chrome, Firefox, Edge ou Safari durante os testes.
* **Não use modo Incógnito ou navegação privada.** Usuários não podem se inscrever em notificações push nestes modos.
* Os prompts devem aparecer baseados na sua configuração de [permission prompts](/docs/pt-BR/permission-requests).
* Clique em **Allow** no prompt nativo para se inscrever em notificações push.
* Vá para **Audience > Subscriptions**.
* Você deve ver uma nova entrada com o status **Subscribed**.
Você criou com sucesso uma [inscrição de web push](/docs/pt-BR/subscriptions).
Inscrições de web push são criadas quando usuários se inscrevem pela primeira vez em notificações push no seu site.
### Configure inscrições de teste
Inscrições de teste são úteis para testar uma notificação push antes de enviar uma mensagem.
No dashboard, próximo à inscrição, clique no botão **Options (três pontos)** e selecione **Add to Test Users**.
Nomeie a inscrição para que você possa identificar facilmente seu dispositivo depois na **aba Test Users**.
Vá para **Audience > Segments > New Segment**.
Nomeie o segmento `Test Users` (o nome é importante porque será usado depois).
Você criou com sucesso um segmento de usuários de teste.
Agora podemos testar enviar mensagens para este dispositivo individual e grupos de usuários de teste.
### Envie push de teste via API
No seu dashboard OneSignal, vá para **Settings > [Keys & IDs](/docs/pt-BR/keys-and-ids)**.
Substitua `YOUR_APP_API_KEY` e `YOUR_APP_ID` no código abaixo com suas chaves reais. Este código usa o segmento `Test Users` que criamos anteriormente.
```curl theme={null}
curl -X \
POST --url 'https://api.onesignal.com/notifications' \
--header 'content-type: application/json; charset=utf-8' \
--header 'authorization: Key YOUR_APP_API_KEY' \
--data \
'{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"name": "Testing basic setup",
"headings": {
"en": "👋"
},
"contents": {
"en": "Hello world!"
},
"included_segments": [
"Test Users"
],
"chrome_web_image": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
Execute o código no seu terminal.
Se todos os passos de configuração foram completados com sucesso, as inscrições de teste devem receber uma notificação.
Apenas Chrome suporta imagens. Imagens aparecerão pequenas na visualização de notificação recolhida. Expanda a notificação para ver a imagem completa.
No seu dashboard, vá para **Delivery > Sent Messages**, depois clique na mensagem para ver as estatísticas. Você deve ver a estatística **confirmed**, significando que o dispositivo recebeu o push.
Safari não suporta Entrega Confirmada.
Veja estatísticas de entrega, clique e conversão para suas notificações push.
Você enviou com sucesso uma notificação via API para um segmento.
Se as notificações não estiverem chegando, contate `support@onesignal.com` com o seguinte:
* A requisição e resposta da API (copie e cole em um arquivo `.txt`)
* Seu Subscription ID
* A URL do seu website com o código OneSignal
***
## Identificação de usuário
A seção anterior cobriu a criação de [Inscrições](/docs/pt-BR/subscriptions) de web push. Esta seção expande para identificar [Usuários](/docs/pt-BR/users) através de todas as suas inscrições (incluindo push, email e SMS) usando o OneSignal SDK. Cobre External IDs, tags, inscrições multicanal, privacidade e rastreamento de eventos para ajudá-lo a unificar e engajar usuários em todas as plataformas.
### Atribua External ID
Use um External ID para identificar usuários consistentemente através de dispositivos, endereços de email e números de telefone usando o identificador de usuário do seu backend. Isso garante que suas mensagens permaneçam unificadas através de canais e sistemas de terceiros (especialmente importante para [Integrações](/docs/pt-BR/integrations)).
Defina o External ID com o [método `login`](/docs/pt-BR/web-sdk-reference#login-external-id) do SDK cada vez que um usuário é identificado pelo seu app.
OneSignal gera IDs únicos somente leitura para inscrições (Subscription ID) e usuários (OneSignal ID).
À medida que usuários baixam seu app em diferentes dispositivos, se inscrevem no seu website e/ou fornecem endereços de email e números de telefone fora do seu app, novas inscrições serão criadas.
Definir o External ID via o SDK é altamente recomendado para identificar usuários através de todas as suas inscrições, independentemente de como elas são criadas.
### Adicione Tags
[Tags](/docs/pt-BR/add-user-data-tags) são pares chave-valor de dados string que você pode usar para armazenar propriedades de usuário (como `username`, `role` ou preferências) e eventos (como `purchase_date`, `game_level` ou interações de usuário). Tags potencializam [Personalização de Mensagem](/docs/pt-BR/message-personalization) avançada e [Segmentação](/docs/pt-BR/segmentation) permitindo casos de uso mais avançados.
Defina tags com os [métodos `addTag` e `addTags`](/docs/pt-BR/web-sdk-reference#addtag-%2C-addtags) do SDK conforme eventos ocorrem no seu app.
Neste exemplo, o usuário alcançou o nível 6 identificável pela tag chamada `current_level` definida com um valor de `6`.
Podemos criar um segmento de usuários que têm um nível entre 5 e 10, e usar isso para enviar mensagens direcionadas e personalizadas:
### Adicione inscrições de email e/ou SMS
O OneSignal SDK cria inscrições de web push automaticamente quando os usuários optam por receber. Você também pode alcançar usuários através de canais de email e SMS criando as inscrições correspondentes.
* Use o [método `addEmail`](/docs/pt-BR/web-sdk-reference#addemail-%2C-removeemail) para criar inscrições de email.
* Use o [método `addSms`](/docs/pt-BR/web-sdk-reference#addsms-%2C-removesms) para criar inscrições de SMS.
Se o endereço de email e/ou número de telefone já existem no app OneSignal, o SDK adicionará ao usuário existente, não criará duplicatas.
Você pode visualizar usuários unificados via **Audience > Users** no dashboard ou com a [API View user](/reference/view-user).
Melhores práticas para comunicação multicanal
* Obtenha consentimento explícito antes de adicionar inscrições de email ou SMS.
* Explique os benefícios de cada canal de comunicação aos usuários.
* Forneça preferências de canal para que usuários possam selecionar quais canais eles preferem.
***
### Privacidade e consentimento do usuário
Para controlar quando OneSignal coleta dados de usuário, use os métodos de controle de consentimento do SDK:
* [`setConsentRequired(true)`](/docs/pt-BR/web-sdk-reference#setconsentrequired): Previne coleta de dados até que consentimento seja dado.
* [`setConsentGiven(true)`](/docs/pt-BR/web-sdk-reference#setconsentgiven): Habilita coleta de dados uma vez que consentimento é concedido.
Para mais sobre privacidade e segurança:
Revise quais dados o OneSignal SDK coleta dos usuários.
Gerencie e proteja dados de usuários em conformidade com regulamentações de privacidade.
***
## Escute eventos de push, usuário e in-app
Use listeners do SDK para reagir a ações de usuário e mudanças de estado.
O SDK fornece vários event listeners para você conectar. Veja nosso [guia de referência do SDK](/docs/pt-BR/web-sdk-reference) para mais detalhes.
### Eventos de notificação push
* [Click event listener](/docs/pt-BR/web-sdk-reference#click): Detecte quando uma notificação é tocada.
* [Foreground lifecycle listener](/docs/pt-BR/web-sdk-reference#foregroundwilldisplay): Controle como notificações se comportam em foreground.
### Mudanças de estado do usuário
* [User state change event listener](/docs/pt-BR/web-sdk-reference#addeventlistener-user-state): Detecte quando o External ID é definido.
* [Permission observer](/docs/pt-BR/web-sdk-reference#permissionchange): Rastreie a interação específica do usuário com o prompt de permissão push nativo.
* [Push subscription change observer](/docs/pt-BR/web-sdk-reference#addeventlistener-push-subscription-changes): Rastreie quando o status de inscrição push muda.
***
## Configuração avançada e capacidades
Explore mais capacidades para melhorar sua integração:
Migre de outro provedor de push para o OneSignal.
Conecte o OneSignal com ferramentas e plataformas de terceiros.
Adicione botões interativos às notificações push.
Envie mensagens localizadas aos usuários no idioma de sua preferência.
Proteja sua integração do SDK com verificação de identidade no servidor.
Rastreie eventos de conversão personalizados vinculados às suas mensagens.
### Configuração e referência do Web SDK
Habilite todos os recursos principais de web push para sua integração.
Detalhes completos sobre métodos disponíveis e opções de configuração.
Parabéns! Você completou com sucesso o guia de configuração do Web SDK.
***
***
## FAQ
### O web push funciona em sites HTTP?
Não. O web push requer HTTPS. Os navegadores impõem isso como requisito de segurança. A única exceção é `localhost` e `127.0.0.1`, que os navegadores tratam como origens seguras para fins de desenvolvimento.
### Por que preciso de um arquivo service worker?
O service worker é executado em segundo plano e lida com notificações push recebidas mesmo quando o usuário não tem seu site aberto. Sem ele, o navegador não consegue exibir notificações. O arquivo `OneSignalSDKWorker.js` deve ser publicamente acessível na sua origem.
### Posso usar web push no iOS (iPhone/iPad)?
Sim, a partir do iOS 16.4+. No entanto, a Apple exige um arquivo `manifest.json` e o usuário deve adicionar seu site à tela inicial primeiro. Veja [Configuração de web push para iOS](./web-push-for-ios) para os requisitos completos.
### Por que minhas notificações não estão aparecendo?
Causas comuns incluem um arquivo service worker colocado incorretamente, uma URL do Site incompatível no dashboard, ou o usuário ter notificações bloqueadas nas configurações do navegador. Veja [Notificações exibidas com sucesso mas não sendo mostradas](./notifications-show-successful-but-are-not-being-shown) para uma lista completa de solução de problemas.
***
Precisa de ajuda?
Converse com nossa equipe de Suporte ou envie email para `support@onesignal.com`
Por favor inclua:
* Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
* Seu OneSignal App ID
* O External ID ou Subscription ID se aplicável
* A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
* Quaisquer [logs ou mensagens de erro](/docs/pt-BR/capturing-a-debug-log) relevantes
Estamos felizes em ajudar!
***