> ## 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 SDK Android
> Adicione notificações push e mensagens in-app ao seu aplicativo Android usando o SDK Android da OneSignal.
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
;
};
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:
```
Integrate the OneSignal Android SDK into this codebase.
Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
```
## 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](./manage-team-members) para configurar o aplicativo. Caso contrário, [cadastre-se para uma conta gratuita](https://onesignal.com) 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](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. Insira os detalhes da sua [Firebase Server Key ou Service Account](./android-firebase-credentials).
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](./mobile-push-setup).
***
## 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](https://github.com/OneSignal/OneSignal-Android-SDK/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.2.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.9.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 OneSignal 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`:
```kotlin app/build.gradle.kts theme={null}
implementation("com.onesignal:OneSignal:[5.6.1, 5.9.99]")
```
```groovy app/build.gradle theme={null}
implementation 'com.onesignal:OneSignal:[5.6.1, 5.9.99]'
```
3. **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)
**Adicione o seguinte código OneSignal à classe Application.**
Substitua `YOUR_APP_ID` pelo seu App ID real da OneSignal em Dashboard > Settings > [Keys & IDs](./keys-and-ids).
```kotlin ApplicationClass.kt theme={null}
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name // Replace with your actual package name
import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel
class ApplicationClass : Application() {
override fun onCreate() {
super.onCreate()
// Enable verbose logging to debug issues (remove in production)
OneSignal.Debug.logLevel = LogLevel.VERBOSE
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID")
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
CoroutineScope(Dispatchers.IO).launch {
OneSignal.Notifications.requestPermission(false)
}
}
}
```
```java ApplicationClass.java theme={null}
// FILE: ApplicationClass.java
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name; // Replace with your actual package name
import android.app.Application;
import com.onesignal.Continue;
import com.onesignal.OneSignal;
import com.onesignal.debug.LogLevel;
public class ApplicationClass extends Application {
@Override
public void onCreate() {
super.onCreate();
// Enable verbose logging to debug issues (remove in production)
OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID");
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
OneSignal.getNotifications().requestPermission(false, Continue.none());
}
}
```
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 ``, adicione `android:name=".ApplicationClass"` (substitua `.ApplicationClass` pelo nome real da sua classe, caso tenha definido um nome diferente).
```xml AndroidManifest.xml theme={null}
```
Verifique se o aplicativo compila e executa sem erros.
### Passo 3. Configure os ícones de notificação padrão (recomendado)
Personalize os [ícones de notificação](./notification-icons) para combinar com a identidade visual do seu aplicativo. Este passo é opcional, mas recomendado para uma aparência profissional.
### Passo 4. Teste a integração
**Verifique a criação da Subscription:**
1. Inicie o aplicativo no dispositivo ou emulador com Google Play Services
2. Verifique no 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"
Você criou com sucesso uma [Subscription mobile](./subscriptions).
As subscriptions mobile são criadas quando os usuários abrem seu aplicativo pela primeira vez em um dispositivo ou se desinstalam e reinstalam o aplicativo no mesmo dispositivo.
#### Crie uma Subscription de teste e um segmento
1. Clique em **⋮** ao lado da Subscription > **Add to Test Users** > dê um nome
2. Vá para **Audience > Segments > New Segment**
3. Nome: `Test Users`, adicione o filtro **Test Users** > **Create Segment**
Você criou com sucesso um segmento de usuários de teste.
Agora podemos testar o envio de mensagens para este dispositivo individual e grupos de usuários de teste.
#### Envie um push de teste via API
1. Navegue até **Settings > [Keys & IDs](./keys-and-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.
```bash theme={null}
curl -X POST 'https://api.onesignal.com/notifications' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Key YOUR_APP_API_KEY' \
-d '{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"name": "Testing basic setup",
"headings": { "en": "👋" },
"contents": {"en": "Hello world!"},
"included_segments": ["Test Users"],
"big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
Verifique se o dispositivo de teste recebeu uma notificação com:
* Seu ícone personalizado (se configurado)
* Imagem grande quando expandida
* Dashboard > **Delivery > Sent Messages** mostra o status "Confirmed" (indisponível em planos gratuitos).
* Não recebeu a notificação? Veja [Push mobile não exibido](./notifications-show-successful-but-are-not-being-shown).
* Sem ícone personalizado? Verifique se o nome do ícone é `onesignal_small_icon_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
Verifique se o dispositivo de teste recebeu uma mensagem in-app. Consulte o guia de [Configuração de mensagens in-app](./in-app-messages-setup) para mais detalhes.
Não está vendo a mensagem?
* Inicie uma nova sessão
* Você deve fechar ou colocar o aplicativo em segundo plano por pelo menos 30 segundos antes de reabrir. Isso garante que uma nova sessão seja iniciada.
* Para mais informações, veja [como as mensagens in-app são exibidas](./in-app-messages-setup#how-are-iams-displayed%3F).
* Ainda está no segmento `Test Users`?
* Se você reinstalou ou trocou de dispositivo, adicione novamente o dispositivo às [Test Users](./test-users) e confirme que ele faz parte do segmento Test Users.
* Está com problemas?
* Siga o guia [Obtendo um Log de Debug](./capturing-a-debug-log) 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.
Você configurou com sucesso o SDK da OneSignal e aprendeu conceitos importantes como:
* Coletar [Subscriptions](./subscriptions), definir [Test Users](./test-users) e criar [Segmentos](./segmentation).
* Enviar [Push](./push) com imagens usando Segmentos e nossa API [Create message](/reference/create-message).
* Enviar [Mensagens in-app](./in-app-messages-setup).
Continue com este guia para identificar usuários no seu aplicativo e configurar recursos adicionais.
### Erros comuns e correções
| Erro / Sintoma | Causa | Correção |
| --------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `Cannot resolve symbol 'OneSignal'` | Dependência do SDK não adicionada ou Gradle não sincronizado | Adicione a dependência ao build.gradle e sincronize o projeto |
| `Application class not found` | Classe Application não registrada no manifest | Adicione `android:name=".ApplicationClass"` à tag `` |
| `Google Play Services not available` | Emulador/dispositivo sem Play Services | Use um dispositivo com Play Store ou emulador com Google APIs |
| Push recebido mas com ícone padrão do Android | Ícone personalizado não configurado ou nome incorreto | Crie o recurso de ícone de notificação com o nome `onesignal_small_icon_default` |
| Nenhuma notificação push recebida | FCM não configurado no OneSignal | Conclua o Passo 0: Configure as credenciais FCM no dashboard do OneSignal |
| Mensagens in-app não aparecem | Sessão não iniciada ou problemas de rede | Feche o aplicativo por mais de 30 segundos, reabra e verifique a conexão com a internet |
| `Manifest merger failed` | Atributos conflitantes no manifest | Verifique se há nomes de aplicativo ou permissões duplicados |
| Otimização de bateria bloqueando notificações | Gerenciamento de energia do dispositivo | Oriente os usuários a desativar a otimização de bateria para seu aplicativo |
| Não consegue diagnosticar o problema | Informações de log insuficientes | Adicione logging verbose e verifique a saída do logcat para erros |
***
## Gerenciamento de usuários
Anteriormente, demonstramos como criar [Subscriptions](./subscriptions) mobile. Agora vamos expandir para identificar [Usuários](./users) 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 garante que suas mensagens permaneçam unificadas entre canais e sistemas de terceiros. Consulte nossa [Referência do SDK Mobile](./mobile-sdk-reference) para mais detalhes e exemplos de código Java.
```kotlin Kotlin theme={null}
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
OneSignal.login(userId)
}
// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
OneSignal.logout()
}
```
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`](./mobile-sdk-reference#login-external-id) no guia de referência do SDK.
### Adicionar Tags e Custom Events
Tags e Custom Events são duas formas de adicionar dados aos seus usuários. Tags são strings `key-value` e geralmente estão associadas a propriedades de usuário (como `username`, `role` ou `status`), enquanto Custom Events possuem formato JSON e geralmente estão associados a ações (como `new_purchase`, `abandoned_cart` e propriedades associadas). Ambos podem ser usados para potencializar [Personalização de Mensagens](./message-personalization) avançada e Journeys. Consulte nossa [Referência do SDK Mobile](./mobile-sdk-reference) para mais detalhes e exemplos de código Java.
```kotlin Kotlin theme={null}
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")
// Create a custom event when user abandoned a cart
val properties = mapOf(
"product_id" to "123456",
"product_name" to "Product Name",
"product_price" to 100,
"product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
```
Mais detalhes sobre como usar Tags e Custom Events nos guias de [Tags](./add-user-data-tags) e [Custom Events](./custom-events).
### Adicionar subscriptions de e-mail e/ou SMS
Você pode alcançar usuários por meio de canais de e-mail e SMS, além de notificações push. Se o endereço de e-mail e/ou número de telefone já existir no aplicativo OneSignal, o SDK o adicionará ao usuário existente — não criará duplicatas. Consulte nossa [Referência do SDK Mobile](./mobile-sdk-reference) para mais detalhes e exemplos de código Java.
```kotlin Kotlin theme={null}
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")
// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
```
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. Consulte nossa [Referência do SDK Mobile](./mobile-sdk-reference) para mais detalhes e exemplos de código Java.
```kotlin Kotlin theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true
// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
```
Consulte nossa documentação de Privacidade e segurança para mais informações sobre:
* [Dados coletados pelo SDK](./data-collected-by-the-onesignal-sdk)
* [Tratamento de dados pessoais](./handling-personal-data)
***
## 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](./prompt-for-push-permissions).
***
## 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
```kotlin Kotlin theme={null}
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
override fun onClick(event: INotificationClickEvent) {
Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
}
}
OneSignal.Notifications.addClickListener(clickListener)
```
### Mudanças de estado do usuário
O exemplo mostra como usar o observer de push subscription. Outros eventos de estado do usuário, como o observer de estado do usuário e o observer de permissão de notificação, estão disponíveis na [Referência do SDK Mobile](./mobile-sdk-reference).
```kotlin Kotlin theme={null}
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
init {
OneSignal.User.pushSubscription.addObserver(this)
}
override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
if (state.current.optedIn) {
println("User is now opted-in with push token: ${state.current.token}")
}
}
}
```
### Eventos de mensagens in-app
Métodos adicionais de mensagens in-app estão disponíveis na [Referência do SDK Mobile](./mobile-sdk-reference).
```kotlin Kotlin theme={null}
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
override fun onClick(event: IInAppMessageClickEvent) {
print(event.result.actionId)
}
}
OneSignal.InAppMessages.addClickListener(clickListener)
```
***
## Configuração avançada e recursos
### Recursos específicos do Android
* **[Canais de Notificação](./mobile-sdk-reference#notification-channels)** — Organize notificações em categorias (Android 8.0+)
* **[Service Extensions](./service-extensions)** — Personalização avançada de notificações
* **[Suporte Huawei/HMS](./huawei-sdk-setup)** — Alternativa ao Google Play Services
### Recursos universais
* [Deep Linking](./deep-linking) — Navegue os usuários para telas específicas a partir de notificações
* [Botões de Ação](./action-buttons) — Adicione botões interativos às notificações
* [Verificação de Identidade](./identity-verification) — Identificação segura de usuários
* [Rastreamento de Localização](./mobile-sdk-reference#location) — Segmentação baseada em localização
* [Integrações](./integrations) — Conecte com plataformas de análise e dados
* [Mensagens Multilíngues](./multi-language-messaging) — Notificações localizadas
Para documentação completa dos métodos do SDK, visite a [Referência do SDK Mobile](./mobile-sdk-reference).
***
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!
***