Skip to main content
Este guia orienta você na adição do OneSignal ao seu aplicativo Android usando o Android Studio. Você instalará nosso SDK, configurará notificações push e mensagens in-app, e enviará mensagens de teste para confirmar que tudo está funcionando. Se esta é a primeira vez que você usa o OneSignal, siga os passos na ordem. Se você já tem experiência, fique à vontade para ir diretamente às seções que precisar.
Usando um assistente de codificação com IA? Para instalação orientada por IA, use este prompt:

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.
Se sua empresa já possui uma conta OneSignal, solicite um convite com função de administrador para configurar o aplicativo. Caso contrário, cadastre-se para uma conta gratuita para começar.
Estes passos conectam seu aplicativo OneSignal ao Firebase Cloud Messaging (FCM). Você só precisa fazer isso uma vez por aplicativo.
  1. Faça login em https://onesignal.com e crie ou selecione seu App.
  2. Navegue até Settings > Push & In-App.
  3. Selecione Google Android (FCM) e clique em Continue para prosseguir pelo assistente de configuração.
  4. Faça upload do seu JSON de FCM Service Account.
  5. Continue pelo assistente de configuração para obter seu App ID. Ele será usado para inicializar o SDK.
Para instruções completas de configuração, consulte nosso guia de Configuração de push mobile.

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
Se você pulou o Passo 0 (Configuração do FCM no OneSignal), ainda pode concluir a configuração do Android Studio abaixo. Conclua o Passo 0 antes de testar ou enviar notificações push.

Passo 1. Adicione o SDK da OneSignal

  1. No Android Studio, abra o arquivo build.gradle.kts (Module: app) ou build.gradle (Module: app)
  2. Adicione o OneSignal à seção dependencies:
build.gradle.kts do app no Android Studio com a dependência de implementação do OneSignal adicionada

O exemplo mostra como adicionar o OneSignal ao arquivo build.gradle.kts do seu App.

  1. Sincronize o Gradle: Clique em Sync Now no banner que aparece ou vá em File > Sync Project with Gradle Files
Verifique se a sincronização do Gradle foi concluída com sucesso e sem conflitos de dependências.

Passo 2. Crie e configure a classe Application

A prática recomendada é inicializar o OneSignal no método onCreate 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:
  1. File > New > Kotlin Class/File (ou Java Class)
  2. Nome: ApplicationClass (ou o nome de sua preferência)
Diálogo New Kotlin Class do Android Studio com ApplicationClass como nome

O exemplo mostra a criação de uma nova classe Kotlin chamada ApplicationClass.

Adicione o seguinte código OneSignal à classe Application. Substitua YOUR_APP_ID pelo seu App ID real da OneSignal em Dashboard > Settings > Keys & IDs.
ApplicationClass.kt no Android Studio mostrando initWithContext e requestPermission do OneSignal

Exemplo do arquivo ApplicationClass.kt.

Inicializar em uma Activity (como MainActivity) não é recomendado porque ela pode não ser chamada em cold-starts do aplicativo a partir de deep links ou notificações. Sempre inicialize o OneSignal na sua classe Application para garantir confiabilidade.
Registre a classe Application:
  1. Abra o AndroidManifest.xml do seu aplicativo
  2. Na tag <application>, adicione android:name=".ApplicationClass" (substitua .ApplicationClass pelo nome real da sua classe, caso tenha definido um nome diferente).
AndroidManifest.xml
Verifique se a tag <application> tem tools:node="replace". Esse marcador remove os componentes mesclados das bibliotecas, incluindo o PermissionsActivity do OneSignal. O fluxo de permissão de notificações então falha com ActivityNotFoundException. Remova tools:node="replace". Se você só precisa substituir um único atributo, use tools:replace="android:theme" (ou o atributo que você está alterando).
Tag application do AndroidManifest.xml com android:name definido como .ApplicationClass

AndroidManifest.xml com o nome .ApplicationClass.

Verifique se o aplicativo compila e executa sem erros.

Passo 3. Configure os ícones de notificação padrão (recomendado)

Substitua o ícone de sino padrão por um ícone pequeno chamado ic_stat_onesignal_default. Use uma silhueta monocromática em fundo transparente, ou o Android renderizará um quadrado branco.
  1. Gere as densidades com o Android Asset Studio.
  2. Coloque ic_stat_onesignal_default em cada pasta de densidade: de res/drawable-mdpi/ (24×24) até res/drawable-xxxhdpi/ (96×96).
Veja Ícones de notificação para ícones grandes, cor de destaque e o comportamento do ícone do launcher no Android 17.

Passo 4. Teste a integração

Verifique a criação da Subscription:
  1. Inicie o aplicativo em um dispositivo ou emulador com Google Play Services.
  2. Verifique em Dashboard > Audience > Subscriptions. O status mostra Never Subscribed.
  3. Aceite o prompt de permissão quando ele aparecer.
  4. Atualize o dashboard. O status muda para Subscribed.
Prompt de permissão de push no Android pedindo para permitir notificações

Prompt de permissão de push no Android

Dashboard mostrando Subscription com status 'Never Subscribed'.

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

Após permitir as permissões de push, atualize o dashboard para ver o status da Subscription mudar para 'Subscribed'

Uma Subscription mobile é criada quando o usuário abre seu aplicativo pela primeira vez em um dispositivo, ou se desinstala e reinstala no mesmo dispositivo. Depois que ele aceitar o prompt de permissão, o status no dashboard deve mostrar Subscribed.

Crie um usuário de teste e um segmento

  1. Ao lado da Subscription, selecione Options > Add as test user e insira um nome.
  2. Vá para Audience > Segments > New Segment.
  3. Nome: Test Users, adicione o filtro Test Users > Create Segment.
Menu Options em um registro de subscription com Add as test user destacado

Adicionar um usuário de teste

Criar um segmento 'Test Users' com o filtro Test Users.

Criar um segmento 'Test Users' com o filtro Test Users

Agora você pode enviar mensagens de teste para este dispositivo e para o segmento Test Users.

Envie um push de teste via API

  1. Navegue até Settings > Keys & IDs.
  2. No código fornecido, substitua YOUR_APP_API_KEY e YOUR_APP_ID no código abaixo pelas suas chaves reais. Este código usa o segmento Test Users que criamos anteriormente.
As imagens nas notificações push aparecem pequenas na visualização recolhida. Expanda a notificação para ver a imagem completa.

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

Estatísticas de entrega mostrando recebimento confirmado (indisponível em planos gratuitos)

Confirme se o dispositivo de teste recebeu uma notificação com seu ícone personalizado (se configurado) e a imagem grande quando expandida. Em planos pagos, Dashboard > Delivery > Sent Messages pode mostrar o recebimento confirmado.
  • Não recebeu a notificação? Veja Push mobile não exibido.
  • Sem ícone personalizado? Verifique se o nome do ícone é ic_stat_onesignal_default e se está nas pastas drawable corretas.
  • Está com problemas? Copie e cole a requisição da API e um log do início ao fim da inicialização do aplicativo em um arquivo .txt. Em seguida, compartilhe ambos com support@onesignal.com.

Teste mensagens in-app

  1. Feche o aplicativo por mais de 30 segundos
  2. Dashboard > Messages > In-App > New In-App > selecione o template Welcome
  3. Público: segmento Test Users
  4. Gatilho: On app open
  5. Agendamento: Every time trigger conditions are satisfied
  6. Clique em Make Message Live
  7. Abra o aplicativo
Direcionando o segmento 'Test Users' com uma mensagem in-app.

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

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

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

Opções de agendamento de mensagens in-app.

Opções de agendamento de mensagens in-app

Mensagem in-app de boas-vindas exibida nos dispositivos.

Mensagem in-app de boas-vindas exibida nos dispositivos

O dispositivo de teste deve exibir a mensagem in-app de boas-vindas. Consulte Configuração de mensagens in-app para mais detalhes.
Não está vendo a mensagem?
  • Inicie uma nova sessão
    • Force o encerramento e reabra o aplicativo, ou feche/coloque-o em segundo plano por pelo menos 30 segundos antes de reabrir. Qualquer uma das opções garante que uma nova sessão seja iniciada. Consulte Sessões.
    • Para mais informações, veja como as mensagens in-app são exibidas.
  • Ainda está no segmento Test Users?
    • Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo às Test Users e confirme que ele faz parte do segmento Test Users.
  • Está com problemas?
    • Siga o guia Obtendo um Log de Debug enquanto reproduz os passos acima. Isso gerará logs adicionais que você pode compartilhar com support@onesignal.com e nós ajudaremos a investigar o que está acontecendo.
Agora você tem Subscriptions, Test Users e um Segmento. Você enviou um push com imagem via a API Create message e uma mensagem in-app. Continue abaixo para identificar usuários e adicionar mais recursos.
Você configurou com sucesso o SDK da OneSignal e aprendeu conceitos importantes como:Continue com este guia para identificar usuários no seu aplicativo e configurar recursos adicionais.

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.
O OneSignal gera IDs exclusivos somente leitura para Subscriptions (Subscription ID) e Usuários (OneSignal ID).Definir o External ID via nosso SDK é altamente recomendado para identificar usuários em todas as suas subscriptions, independentemente de como foram criadas.Saiba mais sobre o método login na referência do SDK.

Adicionar Tags e Custom Events

Tags e Custom Events adicionam dados aos usuários. Tags são strings key-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.
Veja Tags e Custom Events para mais detalhes.

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. Chame login() 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.

Um perfil de usuário com subscriptions de push, e-mail e SMS unificadas por External ID

Melhores práticas para comunicação multicanal
  • 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. Chame consentRequired antes de initWithContext.

Solicitar permissões de push

Em vez de chamar requestPermission() 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ós OneSignal.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

Recursos universais

Para documentação completa dos métodos do SDK, consulte a Referência do SDK Mobile.

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. Adicione android: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. Adicione ic_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?

Defina OneSignal.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.
Precisa de ajuda?Converse com nossa equipe de Suporte ou envie email para 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
Estamos felizes em ajudar!