Passo 0. Configure o FCM no OneSignal (necessário para entregar push)
Você pode instalar e inicializar o SDK Android da OneSignal sem concluir este passo. No entanto, as notificações push não serão entregues até que as credenciais do Firebase Cloud Messaging (FCM) sejam configuradas no seu aplicativo OneSignal.Passos para configurar seu aplicativo OneSignal.
Passos para configurar seu aplicativo OneSignal.
- Faça login em https://onesignal.com e crie ou selecione seu App.
- Navegue até Settings > Push & In-App.
- Selecione Google Android (FCM) e clique em Continue para prosseguir pelo assistente de configuração.
- Faça upload do seu JSON de FCM Service Account.
- Continue pelo assistente de configuração para obter seu App ID. Ele será usado para inicializar o SDK.
Contrato de configuração e requisitos
Esta seção resume as ferramentas, versões e premissas usadas ao longo do guia.- Versão do SDK:
5.6.1+(mais recente: verifique os releases) - Instruções de configuração por IA:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md - Repositório do SDK:
https://github.com/OneSignal/OneSignal-Android-SDK - Android Studio: Meerkat | 2024.3.1+
- API Android: 23+ mínimo (Android 6.0+), 31+ recomendado (Android 12+)
- Dispositivo/emulador: Android 7.0+ com Google Play Services instalado
- Dependência obrigatória:
com.onesignal:OneSignal:[5.6.1, 5.99.99] - Classe Application: Necessária para inicialização correta do SDK
- Formato do App ID: UUID de 36 caracteres (exemplo:
12345678-1234-1234-1234-123456789012). Encontre em Dashboard > Settings > Keys & IDs. - Inicialização:
OneSignal.initWithContext(this, "YOUR_APP_ID") - Otimização de bateria: Pode afetar notificações em segundo plano
- Recomendado: Atribuir External ID via
OneSignal.login("user_id")para unificar usuários entre dispositivos
Passos de configuração do Android
Ao final dos passos abaixo, você terá:- O SDK da OneSignal instalado e inicializado no seu aplicativo Android
- A solicitação de permissão de notificações push funcionando corretamente em um dispositivo real
- Um push de teste e uma mensagem in-app entregues com sucesso
Passo 1. Adicione o SDK da OneSignal
- No Android Studio, abra o arquivo
build.gradle.kts (Module: app)oubuild.gradle (Module: app) - Adicione o OneSignal à seção
dependencies:

O exemplo mostra como adicionar o OneSignal ao arquivo build.gradle.kts do seu App.
- Sincronize o Gradle: Clique em Sync Now no banner que aparece ou vá em File > Sync Project with Gradle Files
Passo 2. Crie e configure a classe Application
A prática recomendada é inicializar o OneSignal no métodoonCreate da sua classe Application para garantir a configuração correta do SDK em todos os pontos de entrada.
Crie uma classe Application se você ainda não tiver uma:
- File > New > Kotlin Class/File (ou Java Class)
- Nome:
ApplicationClass(ou o nome de sua preferência)

O exemplo mostra a criação de uma nova classe Kotlin chamada ApplicationClass.
YOUR_APP_ID pelo seu App ID real da OneSignal em Dashboard > Settings > Keys & IDs.

Exemplo do arquivo ApplicationClass.kt.
- Abra o
AndroidManifest.xmldo seu aplicativo - Na tag
<application>, adicioneandroid:name=".ApplicationClass"(substitua.ApplicationClasspelo nome real da sua classe, caso tenha definido um nome diferente).

AndroidManifest.xml com o nome .ApplicationClass.
Passo 3. Configure os ícones de notificação padrão (recomendado)
Substitua o ícone de sino padrão por um ícone pequeno chamadoic_stat_onesignal_default. Use uma silhueta monocromática em fundo transparente, ou o Android renderizará um quadrado branco.
- Gere as densidades com o Android Asset Studio.
- Coloque
ic_stat_onesignal_defaultem cada pasta de densidade: deres/drawable-mdpi/(24×24) atéres/drawable-xxxhdpi/(96×96).
Passo 4. Teste a integração
Verifique a criação da Subscription:- Inicie o aplicativo em um dispositivo ou emulador com Google Play Services.
- Verifique em Dashboard > Audience > Subscriptions. O status mostra Never Subscribed.
- Aceite o prompt de permissão quando ele aparecer.
- Atualize o dashboard. O status muda para Subscribed.

Prompt de permissão de push no Android

Dashboard mostrando Subscription com status 'Never Subscribed'

Após permitir as permissões de push, atualize o dashboard para ver o status da Subscription mudar para 'Subscribed'
Crie um usuário de teste e um segmento
- Ao lado da Subscription, selecione Options > Add as test user e insira um nome.
- Vá para Audience > Segments > New Segment.
- Nome:
Test Users, adicione o filtro Test Users > Create Segment.

Adicionar um usuário de teste

Criar um segmento 'Test Users' com o filtro Test Users
Envie um push de teste via API
- Navegue até Settings > Keys & IDs.
- No código fornecido, substitua
YOUR_APP_API_KEYeYOUR_APP_IDno código abaixo pelas suas chaves reais. Este código usa o segmentoTest Usersque criamos anteriormente.

As imagens aparecerão pequenas na visualização recolhida da notificação. Expanda a notificação para ver a imagem completa.

Estatísticas de entrega mostrando recebimento confirmado (indisponível em planos gratuitos)
Teste mensagens in-app
- Feche o aplicativo por mais de 30 segundos
- Dashboard > Messages > In-App > New In-App > selecione o template Welcome
- Público: segmento Test Users
- Gatilho: On app open
- Agendamento: Every time trigger conditions are satisfied
- Clique em Make Message Live
- Abra o aplicativo

Direcionando o segmento 'Test Users' com uma mensagem in-app

Exemplo de personalização da mensagem in-app de boas-vindas

Opções de agendamento de mensagens in-app

Mensagem in-app de boas-vindas exibida nos dispositivos
- Coletar Subscriptions, definir Test Users e criar Segmentos.
- Enviar Push com imagens usando Segmentos e nossa API Create message.
- Enviar Mensagens in-app.
Erros comuns e correções
Gerenciamento de usuários
Anteriormente, demonstramos como criar Subscriptions mobile. Agora vamos expandir para identificar Usuários em todas as suas Subscriptions (incluindo push, e-mail e SMS) usando o SDK da OneSignal.Atribuir External ID (recomendado)
Use um External ID para identificar usuários de forma consistente entre dispositivos, endereços de e-mail e números de telefone usando o identificador de usuário do seu backend. Isso mantém as mensagens unificadas entre canais e sistemas de terceiros.login na referência do SDK.Adicionar Tags e Custom Events
Tags e Custom Events adicionam dados aos usuários. Tags são stringskey-value para propriedades de usuário (como username, role ou status). Custom Events usam JSON e geralmente representam ações (como new_purchase ou abandoned_cart). Ambos podem potencializar a Personalização de Mensagens e Journeys.
Adicionar subscriptions de e-mail e/ou SMS
Você pode alcançar usuários por e-mail e SMS, além de push. Se o endereço de e-mail ou número de telefone já existir no aplicativo OneSignal, o SDK o adiciona ao usuário existente e não cria duplicatas. Chamelogin() primeiro para que o endereço seja vinculado ao usuário identificado.

Um perfil de usuário com subscriptions de push, e-mail e SMS unificadas por External ID
- Obtenha consentimento explícito antes de adicionar subscriptions de e-mail ou SMS.
- Explique os benefícios de cada canal de comunicação aos usuários.
- Forneça preferências de canal para que os usuários possam selecionar quais canais preferem.
Privacidade e consentimento do usuário
Para controlar quando o OneSignal coleta dados do usuário, use os métodos de controle de consentimento do SDK. ChameconsentRequired antes de initWithContext.
Solicitar permissões de push
Em vez de chamarrequestPermission() imediatamente ao abrir o aplicativo, adote uma abordagem mais estratégica. Use uma mensagem in-app para explicar o valor das notificações push antes de solicitar a permissão.
Para melhores práticas e detalhes de implementação, consulte nosso guia Solicitar permissões de push.
Ouvir eventos de push, usuário e in-app
Use listeners do SDK para reagir a ações do usuário e mudanças de estado. Adicione-os na sua classe Application apósOneSignal.initWithContext().
Eventos de notificação push
Mudanças de estado do usuário
Este exemplo usa o observer de push subscription. O observer de estado do usuário e o observer de permissão de notificação estão na Referência do SDK Mobile.Eventos de mensagens in-app
Métodos adicionais de mensagens in-app estão disponíveis na Referência do SDK Mobile.Configuração avançada e recursos
Recursos específicos do Android
- Canais de notificação: Organize notificações em categorias (Android 8.0+)
- Service extensions: Personalização avançada de notificações
- Huawei/HMS: Alternativa ao Google Play Services
Recursos universais
- Deep linking: Navegue os usuários para telas específicas a partir de notificações
- Botões de ação: Adicione botões interativos às notificações
- Verificação de identidade: Identificação segura de usuários
- Rastreamento de localização: Segmentação baseada em localização
- Integrações: Conecte com plataformas de análise e dados
- Mensagens multilíngues: Notificações localizadas
FAQ
Por que o Android Studio não consegue resolver OneSignal?
A dependência do SDK está ausente ou o Gradle não foi sincronizado. Adicione com.onesignal:OneSignal:[5.6.1, 5.99.99] ao build.gradle do módulo do app e use File > Sync Project with Gradle Files.
Por que minha classe Application não é encontrada?
A classe não está registrada no manifest. Adicioneandroid:name=".ApplicationClass" (ou o nome da sua classe) à tag <application> no AndroidManifest.xml.
Por que o emulador diz que o Google Play Services não está disponível?
A imagem do emulador não inclui o Play Services. Use um dispositivo com a Play Store, ou uma imagem de sistema de emulador que inclua as Google APIs.Por que a notificação mostra o ícone padrão do Android?
O ícone pequeno está ausente ou com o nome errado. Adicioneic_stat_onesignal_default a cada pasta de densidade res/drawable-*. Veja Ícones de notificação.
Por que meu dispositivo de teste não recebeu um push?
As credenciais FCM não estão configuradas, ou o dispositivo não está inscrito. Conclua o Passo 0 e confirme que o status da Subscription é Subscribed. Em seguida, veja Push mobile não exibido.Por que as mensagens in-app não estão aparecendo?
As mensagens in-app exigem uma nova sessão. Force o encerramento do aplicativo, ou coloque-o em segundo plano por pelo menos 30 segundos, e depois reabra. Confirme que o dispositivo ainda está no segmento Test Users. Veja Sessões e como as mensagens in-app são exibidas.O que causa Manifest merger failed?
Valores conflitantes de android:name em <application> ou permissões duplicadas. Procure no seu manifest mesclado por uma segunda classe Application e mantenha um único android:name.
Por que as otimizações de bateria bloqueiam notificações?
Alguns fabricantes (OEMs) restringem o trabalho em segundo plano. Peça aos usuários que desativem a otimização de bateria para seu aplicativo se as notificações pararem depois que o dispositivo entrar em modo de suspensão.Como obtenho mais saída de log?
DefinaOneSignal.Debug.logLevel = LogLevel.VERBOSE (Kotlin) ou OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE) (Java), reproduza o problema e capture o logcat. Veja Obtendo um log de debug.
support@onesignal.comPor 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 relevantes