OneSignal: Guia Completo de Implementação (Mobile Push, Web Push e Email)
Guia completo para implementar a OneSignal em Mobile Push, Web Push e Email: passos exatos, erros comuns e configuração avançada, baseado em implementações reais com clientes da Bildung Data.
A OneSignal é a plataforma de mensageria omnichannel mais utilizada do mundo — e não é à toa. Ela permite enviar push notifications, emails, SMS e In-App Messages a partir de um único lugar, com uma integração técnica relativamente simples. Mas "relativamente simples" não significa que não existam erros comuns que fazem você perder tempo, assinantes e dinheiro. Este guia, construído a partir da nossa experiência implementando OneSignal com clientes reais, cobre todos os canais com os passos exatos a seguir — e os erros a evitar.
Se precisar de ajuda para implementar a OneSignal ou quiser revisar sua implementação atual, me escreva em guido@bildungdata.com.
📱 Mobile Push & In-App Messages
O canal de maior impacto da OneSignal. Bem implementado, o push mobile tem taxas de abertura 3-10x superiores ao email. Aqui estão os passos críticos para acertar desde o início.
Passo 1 — Criar o app na OneSignal
Acesse onesignal.com → New App/Website → escolha "Mobile App". Depois de criado, salve o App ID e a REST API Key em Settings. Você vai precisar deles na integração do SDK e nas chamadas à API REST.
Passo 2 — Carregar as credenciais de push
Cada plataforma exige suas próprias credenciais para enviar notificações:
Android (FCM): enviar o arquivo JSON do Firebase a partir do console do Firebase.
iOS (APNs): enviar o certificado .p8 da Apple a partir da sua conta de Apple Developer.
Huawei: credenciais do Huawei Push Kit (caso seu app precise dar suporte a dispositivos sem Google Play).
Onde configurar: Settings → Push & In-App → Google Android (FCM) / Apple iOS (APNs).
Passo 3 — Instalar o SDK no app
Adicione o SDK da OneSignal ao projeto: via Gradle no Android ou CocoaPods / Swift Package Manager no iOS. Depois de instalado, inicialize com o App ID na inicialização do app — no Application.onCreate() no Android ou no AppDelegate no iOS.
Passo 4 — Configurar o small icon no Android
Esse passo é fácil de esquecer e tem um impacto visível: sem um ícone configurado corretamente, as notificações do Android aparecem com um ícone genérico branco. O ícone deve ser um PNG com fundo transparente e desenho monocromático. Tamanho recomendado: 96x96px.
Passo 5 — Pedir permissão com um InApp prévio (soft opt-in)
Antes de mostrar o prompt nativo de permissão do sistema operacional, exiba uma In-App Message própria explicando o valor das notificações. Isso melhora muito a taxa de opt-in.
Crítico para iOS: o prompt nativo do iOS só pode ser exibido UMA VEZ. Se o usuário recusar, não é possível pedir novamente sem que ele vá manualmente até as configurações. Por isso o InApp prévio é fundamental — filtre os usuários que vão dizer sim antes de gastar a única chance.
Passo 6 — Configurar a Notification Service Extension no iOS
A NSE (Notification Service Extension) é um target adicional no Xcode que processa as notificações antes de exibi-las. É obrigatória para: Confirmed Delivery, imagens nas notificações, badges e action buttons.
Sem a NSE configurada, o iOS não reporta Confirmed Deliveries e as imagens simplesmente não aparecem. Também é preciso configurar App Groups para que a NSE e o app principal possam compartilhar dados.
Passos 7 e 8 — Testes e verificação de métricas
Envie uma mensagem de teste pelo Dashboard para um device de teste. Teste com o app em foreground e background, no Android e no iOS separadamente. Depois verifique no Dashboard: assinantes ativos, opt-in rate por plataforma e se as mensagens mostram os status Sent / Delivered / Confirmed.
🌐 Web Push
O Web Push permite enviar notificações para navegadores de desktop e mobile sem precisar de um app. Compatível com Chrome, Firefox, Edge e (a partir do iOS 16.4+) Safari mobile, caso o usuário adicione o site à tela de início.
Passo 1 — Criar o app e copiar as credenciais
onesignal.com → New App/Website → "Web". Salve o App ID e a REST API Key.
Passo 2 — Instalar o Web SDK
Adicione o snippet JS da OneSignal no <head> de todas as páginas do site. Também é possível instalar via Google Tag Manager. Verifique se carrega sem erros no console do navegador antes de continuar.
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
await OneSignal.init({
appId: "TU_APP_ID",
});
});
</script>
Passo 3 — Configurar o Permission Prompt
Você tem três opções para pedir permissão ao usuário:
Slide Prompt: um banner da OneSignal que converte melhor do que o prompt nativo direto.
Native Browser Prompt: o popup do navegador diretamente.
Custom Prompt (InApp prévio): seu próprio design antes do prompt nativo.
Assim como no iOS mobile, o permission prompt nativo do navegador só pode ser exibido UMA VEZ. Se o usuário recusar, o navegador não pergunta de novo. Use o Slide Prompt ou um InApp prévio para maximizar as chances.
Passo 4 — Configurar iOS Web Push (Safari mobile)
Para dar suporte a usuários no iOS 16.4+ no Safari, você precisa de um arquivo manifest.json no diretório raiz do site. Além disso, o iOS exige que o usuário adicione o site à tela de início antes de poder se inscrever — é uma limitação do sistema operacional, não da OneSignal.
Passos 5 e 6 — Testes e métricas web
Crie uma campanha de teste pelo Dashboard e verifique o recebimento no Chrome e no Safari. No Dashboard você deve ver assinantes ativos, opt-in rate e mensagens com status Sent / Delivered.
⚙️ Advanced Settings — Opcionais, mas muito recomendados
Esses passos não são obrigatórios para enviar a primeira mensagem, mas são fundamentais para aproveitar todo o potencial da OneSignal: segmentação precisa, personalização e automação.
1 — Identificação de usuários com external_id
Quando o usuário faz login no seu app ou site, identifique-o na OneSignal com o seu próprio ID de usuário. Isso permite direcionar usuários específicos e cruzar os dados da OneSignal com o seu backend ou CRM.
// Quando o usuário faz login
OneSignal.login('SEU_USER_ID');
// Quando faz logout
OneSignal.logout();
O external_id deve ser o mesmo ID usado no seu backend. Sem isso, não é possível enviar notificações transacionais para um usuário específico.
2 — Data Tags para segmentação
Data Tags são propriedades de usuário que você pode usar para segmentar e personalizar mensagens. São enviadas via SDK ou API.
// Definir propriedades do usuário
OneSignal.User.addTags({
plan: 'premium',
cidade: 'sp',
ultima_compra: '2024-03-15'
});
3 — Custom Events para triggers avançados
Custom Events permitem registrar ações específicas do usuário para disparar automações (Journeys) e In-App Messages.
// Rastrear um evento personalizado
OneSignal.trackEvent('purchase', { amount: 100, product: 'course' });
// Outros exemplos
OneSignal.trackEvent('article_read', { category: 'tecnologia' });
OneSignal.trackEvent('checkout_started');
Os triggers básicos como "app open" ou "tempo em tela" funcionam sem código adicional. Os Custom Events exigem implementação, mas abrem possibilidades avançadas de personalização.
4 — Mensageria transacional via API REST
Para envios automáticos a partir do seu backend (ex: "pedido enviado", confirmação de pagamento, alertas de sistema), integre o endpoint POST /notifications da API REST da OneSignal.
curl --request POST \
--url https://api.onesignal.com/notifications \
--header 'Authorization: Key SUA_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "SEU_APP_ID",
"include_aliases": { "external_id": ["user_123"] },
"target_channel": "push",
"contents": { "en": "Seu pedido foi enviado 🚀" }
}'
5 — Migrar assinantes existentes
Se você usava outro provedor de push, pode importar os push tokens históricos e emails via CSV ou API para não perder sua base de assinantes.
✉️ Email
A OneSignal também gerencia email, o que permite coordenar push e email a partir de um único lugar. Isso é muito poderoso para Journeys omnichannel: se o usuário não abrir o push em 24h, o email é enviado automaticamente.
Passo 1 — Habilitar o canal Email
Vá em Settings → Platforms → Email → Activate. Por padrão, a OneSignal usa Mailgun com IP compartilhado. Se você já tem Sendgrid, Mailgun próprio ou Mailchimp, pode conectá-los para não pagar volume de email à OneSignal. Para alto volume, é possível solicitar um IP dedicado.
Passo 2 — Configurar o domínio de envio (SPF / DKIM / DMARC)
Esse é o passo mais técnico e o mais crítico para a deliverabilidade. Sem autenticação do domínio, os emails caem no spam. É preciso adicionar três registros DNS:
SPF: autoriza a OneSignal a enviar emails em nome do seu domínio.
DKIM: assinatura criptográfica que verifica que o email não foi alterado no trajeto.
DMARC: define o que fazer com os emails que não passarem em SPF ou DKIM.
Esse passo deve ser feito pela equipe de TI ou por quem administra o DNS do domínio. Sem isso, não importa quão bons sejam seus emails — eles vão para o spam.
Passo 3 — From Name, From Email e Reply-To
Configure o nome e o endereço de remetente que os usuários vão ver (ex: "Equipe MeuApp" ola@meuapp.com). Configure também o Reply-To para os casos em que os usuários respondam diretamente.
Passos 4 e 5 — Importar emails existentes e capturar novos via SDK
Se você tem uma base de emails histórica, importe via CSV ou API. Inclua o external_id para cruzar com os perfis de usuário existentes. Importe apenas usuários que já tinham opt-in prévio — nunca listas compradas.
// Capturar o email do usuário quando ele o insere
OneSignal.User.addEmail('usuario@mail.com');
Passos 6 e 7 — Templates e Unsubscribe
Crie os templates no editor drag-and-drop da OneSignal. Sempre inclua um link de unsubscribe visível e funcional — é exigido por lei (CAN-SPAM, GDPR/LGPD). A OneSignal gerencia isso automaticamente se você usar o rodapé padrão dela.
Passos 8 e 9 — Testes e métricas de deliverability
Antes de lançar, envie um email de teste para um endereço próprio e verifique: se ele chega, se não cai no spam, se os links funcionam e se o unsubscribe funciona. Confira no Gmail e no Outlook, e na visualização mobile.
Métricas de referência: bounce rate normal abaixo de 2%; open rate objetivo acima de 20%. Um bounce rate alto indica problemas de lista ou de configuração de DNS.
📌 Canais Adicionais: SMS, WhatsApp e Integrações
A OneSignal também suporta SMS via Twilio e WhatsApp via Meta/Twilio Webhooks, o que a torna uma plataforma verdadeiramente omnichannel. Quanto a integrações nativas, ela se conecta com Amplitude, Mixpanel e Appsflyer — muito úteis para cruzar dados comportamentais com as campanhas de mensageria.
Conclusão: a ordem importa
A OneSignal é uma plataforma muito poderosa, mas como toda integração técnica, o diabo mora nos detalhes. Os erros mais custosos que vemos em implementações reais são: não configurar a NSE no iOS (você perde Confirmed Delivery e imagens), gastar o prompt nativo sem um InApp prévio (você perde a taxa de opt-in para sempre) e não autenticar o domínio de email (seus emails vão para o spam desde o primeiro dia).
Seguir esse checklist em ordem evita esses erros e deixa uma implementação sólida para construir campanhas, Journeys e automações que realmente convertem. Se precisar de ajuda com a implementação, na Bildung Data somos parceiros da OneSignal e acompanhamos projetos de integração end-to-end.
📖 Documentação oficial completa: documentation.onesignal.com
