> ## 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

> Instale o SDK Android da OneSignal no Android Studio para adicionar push e mensagens in-app, com credenciais FCM, inicialização e testes.

SDK Releases

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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> Se sua empresa já possui uma conta OneSignal, [solicite um convite com função de administrador](https://documentation.onesignal.com/docs/pt-BR/manage-team-members.md) para configurar o aplicativo. Caso contrário, [cadastre-se para uma conta gratuita](https://onesignal.com) para começar.

> [accordion] Passos para configurar seu aplicativo OneSignal.
>
> 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. Faça upload do seu [JSON de FCM Service Account](https://documentation.onesignal.com/docs/pt-BR/android-firebase-credentials.md).
>
> 5. Continue pelo assistente de configuração para obter seu App ID. Ele será usado para inicializar o SDK.
>
> > [!NOTE]
> >
> > Para instruções completas de configuração, consulte nosso guia de [Configuração de push mobile](https://documentation.onesignal.com/docs/pt-BR/mobile-push-setup.md).

***

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

> [!NOTE]
>
> 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.99.99]")
```

```groovy app/build.gradle theme={null}
implementation 'com.onesignal:OneSignal:[5.6.1, 5.99.99]'
```

![build.gradle.kts do app no Android Studio com a dependência de implementação do OneSignal adicionada](https://mintcdn.com/onesignal/dlRpLVMLP5Sd65F4/images/sdk/android-add-onesignal-to-build-gradle.png?fit=max\&auto=format\&n=dlRpLVMLP5Sd65F4\&q=85\&s=a1e031945c35197d41335c7c2956739e)

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

3. **Sincronize o Gradle:** Clique em **Sync Now** no banner que aparece ou vá em **File > Sync Project with Gradle Files**

> [!TIP]
>
> 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](https://mintcdn.com/onesignal/dlRpLVMLP5Sd65F4/images/sdk/android-create-application-class-kotlin.png?fit=max\&auto=format\&n=dlRpLVMLP5Sd65F4\&q=85\&s=7ce9f314acb72ff74311c2695368f5cf)

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](https://documentation.onesignal.com/docs/pt-BR/keys-and-ids.md).

```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 for push permission. fallbackToSettings = false does not send the user
        // to system settings if they previously denied. See the Mobile SDK reference.
        // 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 for push permission. fallbackToSettings = false does not send the user
        // to system settings if they previously denied. See the Mobile SDK reference.
        // In production, consider using an in-app message instead for better opt-in rates.
        OneSignal.getNotifications().requestPermission(false, Continue.none());
    }
}
```

![ApplicationClass.kt no Android Studio mostrando initWithContext e requestPermission do OneSignal](https://mintcdn.com/onesignal/dlRpLVMLP5Sd65F4/images/sdk/android-application-class-kotlin.png?fit=max\&auto=format\&n=dlRpLVMLP5Sd65F4\&q=85\&s=e035c8995472b308f10e42ed82478a0a)

Exemplo do arquivo ApplicationClass.kt.

> [!WARNING]
>
> 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).

```xml AndroidManifest.xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
      </application>

  </manifest>
```

> [!WARNING]
>
> 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](https://mintcdn.com/onesignal/dlRpLVMLP5Sd65F4/images/sdk/android-androidmanifest-application-class.png?fit=max\&auto=format\&n=dlRpLVMLP5Sd65F4\&q=85\&s=289b016975723e22e23d1871457ae21f)

AndroidManifest.xml com o nome .ApplicationClass.

> [!TIP]
>
> 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](https://romannurik.github.io/AndroidAssetStudio/icons-notification.html#source.space.trim=1\&source.space.pad=0\&name=ic_stat_onesignal_default).
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](https://documentation.onesignal.com/docs/pt-BR/notification-icons.md) 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](https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a90c2cc443f5fe9e7c80368c680a16cf1ca6203f7b28a0a6eec212add8510f80-Untitled_design_11.png?fit=max\&auto=format\&n=RWtLFPeffHrC81wI\&q=85\&s=96dbf224b3ae93b3d814712cdc5416ba)

Prompt de permissão de push no Android

![Dashboard mostrando Subscription com status 'Never Subscribed'.](https://mintcdn.com/onesignal/mJXnj6xKtiaVBd7y/images/dashboard/subscription-never-subscribed.png?fit=max\&auto=format\&n=mJXnj6xKtiaVBd7y\&q=85\&s=f6412faa44ca1c0dfbd07dc39e82fc08)

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'.](https://mintcdn.com/onesignal/mJXnj6xKtiaVBd7y/images/dashboard/subscription-subscribed.png?fit=max\&auto=format\&n=mJXnj6xKtiaVBd7y\&q=85\&s=cef79235b64703bc1a1bbffab775366e)

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

Uma [Subscription mobile](https://documentation.onesignal.com/docs/pt-BR/subscriptions.md) é 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](https://mintcdn.com/onesignal/ZcUnlVp78Ic-q_xR/images/dashboard/add-as-test-subscription.png?fit=max\&auto=format\&n=ZcUnlVp78Ic-q_xR\&q=85\&s=7c51e0962a7a0d8c688c0114054b031d)

Adicionar um usuário de teste

![Criar um segmento 'Test Users' com o filtro Test Users.](https://mintcdn.com/onesignal/NCUI56Tiw7V-s0dT/images/dashboard/create-test-users-segment.png?fit=max\&auto=format\&n=NCUI56Tiw7V-s0dT\&q=85\&s=91b8a021be6e83662854e68ec3e1da04)

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](https://documentation.onesignal.com/docs/pt-BR/keys-and-ids.md)**.
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"
  }'
```

![As imagens nas notificações push aparecem pequenas na visualização recolhida. Expanda a notificação para ver a imagem completa.](https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/e4e3e812eb6841ff11795a6ee0ea36eff483920ea9266733d6948ed34df3def3-Untitled_design_9.png?fit=max\&auto=format\&n=Z6xkXGfmy814If53\&q=85\&s=9bf6f4a73e38ec424b8cfec75a474a26)

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).](https://mintcdn.com/onesignal/r7d-mmGxYBGknd0e/images/dashboard/delivery-stats-confirmed-delivery.png?fit=max\&auto=format\&n=r7d-mmGxYBGknd0e\&q=85\&s=9949b389aec0cc2e08fc338eaad941de)

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.

> [!WARNING]
>
> * Não recebeu a notificação? Veja [Push mobile não exibido](https://documentation.onesignal.com/docs/pt-BR/notifications-show-successful-but-are-not-being-shown.md).
> * 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.](https://mintcdn.com/onesignal/mJXnj6xKtiaVBd7y/images/dashboard/targeting-test-users-segment-with-in-app-message.png?fit=max\&auto=format\&n=mJXnj6xKtiaVBd7y\&q=85\&s=4f2e70263b932745cf929bad9030c819)

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

![Exemplo de personalização da mensagem in-app de boas-vindas.](https://mintcdn.com/onesignal/r7d-mmGxYBGknd0e/images/dashboard/example-customization-of-in-app-welcome-message.png?fit=max\&auto=format\&n=r7d-mmGxYBGknd0e\&q=85\&s=3decc127e575020980828a95eb7f96ce)

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

![Opções de agendamento de mensagens in-app.](https://mintcdn.com/onesignal/r7d-mmGxYBGknd0e/images/dashboard/in-app-message-scheduling-options.png?fit=max\&auto=format\&n=r7d-mmGxYBGknd0e\&q=85\&s=d7a46112e5ac3e12bc83b4f8e408159e)

Opções de agendamento de mensagens in-app

![Mensagem in-app de boas-vindas exibida nos dispositivos.](https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a7ed4bb02be56900a65d2519e3d69f9c9b2c2a1c65fe740f07789e4ffe79cd67-Untitled_design_10.png?fit=max\&auto=format\&n=RWtLFPeffHrC81wI\&q=85\&s=6f692b569706ca39df0b4cc2b70f3de2)

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](https://documentation.onesignal.com/docs/pt-BR/in-app-messages-setup.md) para mais detalhes.

> [!WARNING]
>
> 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](https://documentation.onesignal.com/docs/en/sessions.md).
>   * Para mais informações, veja [como as mensagens in-app são exibidas](https://documentation.onesignal.com/docs/pt-BR/in-app-messages-setup.md#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](https://documentation.onesignal.com/docs/pt-BR/test-users.md) e confirme que ele faz parte do segmento Test Users.
> * Está com problemas?
>   * Siga o guia [Obtendo um Log de Debug](https://documentation.onesignal.com/docs/pt-BR/capturing-a-debug-log.md) 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](https://documentation.onesignal.com/docs/pt-BR/subscriptions.md), [Test Users](https://documentation.onesignal.com/docs/pt-BR/test-users.md) e um [Segmento](https://documentation.onesignal.com/docs/pt-BR/segmentation.md). Você enviou um [push](https://documentation.onesignal.com/docs/pt-BR/push.md) com imagem via a API [Create message](https://documentation.onesignal.com/reference/create-message.md) e uma [mensagem in-app](https://documentation.onesignal.com/docs/pt-BR/in-app-messages-setup.md). Continue abaixo para identificar usuários e adicionar mais recursos.

> [!TIP]
>
> Você configurou com sucesso o SDK da OneSignal e aprendeu conceitos importantes como:
>
> * Coletar [Subscriptions](https://documentation.onesignal.com/docs/pt-BR/subscriptions.md), definir [Test Users](https://documentation.onesignal.com/docs/pt-BR/test-users.md) e criar [Segmentos](https://documentation.onesignal.com/docs/pt-BR/segmentation.md).
> * Enviar [Push](https://documentation.onesignal.com/docs/pt-BR/push.md) com imagens usando Segmentos e nossa API [Create message](https://documentation.onesignal.com/reference/create-message.md).
> * Enviar [Mensagens in-app](https://documentation.onesignal.com/docs/pt-BR/in-app-messages-setup.md).
>
> 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 `<application>` |
| `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 `ic_stat_onesignal_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 |
| `ActivityNotFoundException` para `PermissionsActivity` | `tools:node="replace"` em `<application>` removeu a activity do SDK do manifest mesclado | Remova `tools:node="replace"` de `<application>`. Em vez disso, substitua um atributo específico com `tools:replace`. Confirme que `com.onesignal.core.activities.PermissionsActivity` está em `app/build/intermediates/merged_manifests`. |
| 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](https://documentation.onesignal.com/docs/pt-BR/subscriptions.md) mobile. Agora vamos expandir para identificar [Usuários](https://documentation.onesignal.com/docs/pt-BR/users.md) 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.

```kotlin Kotlin theme={null}
// Call when user logs in or is identified. Safe to call multiple times.
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

fun onUserLoggedOut() {
    OneSignal.logout()
}
```

```java Java theme={null}
// Call when user logs in or is identified. Safe to call multiple times.
public void onUserAuthenticated(String userId) {
    OneSignal.login(userId);
}

public void onUserLoggedOut() {
    OneSignal.logout();
}
```

> [!NOTE]
>
> 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) 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](https://documentation.onesignal.com/docs/pt-BR/message-personalization.md) e Journeys.

```kotlin Kotlin theme={null}
OneSignal.User.addTag("username", "john_doe")

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

```java Java theme={null}
import java.util.HashMap;
import java.util.Map;

OneSignal.getUser().addTag("username", "john_doe");

Map<String, Object> properties = new HashMap<>();
properties.put("product_id", "123456");
properties.put("product_name", "Product Name");
properties.put("product_price", 100);
properties.put("product_quantity", 1);
OneSignal.getUser().trackEvent("abandoned_cart", properties);
```

> [!NOTE]
>
> Veja [Tags](https://documentation.onesignal.com/docs/pt-BR/add-user-data-tags.md) e [Custom Events](https://documentation.onesignal.com/docs/pt-BR/custom-events.md) 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.

```kotlin Kotlin theme={null}
OneSignal.User.addEmail("user@example.com")
OneSignal.User.addSms("+15551234567")
```

```java Java theme={null}
OneSignal.getUser().addEmail("user@example.com");
OneSignal.getUser().addSms("+15551234567");
```

![Um perfil de usuário com subscriptions de push, e-mail e SMS unificadas por External ID.](https://mintcdn.com/onesignal/mJXnj6xKtiaVBd7y/images/dashboard/user-profile-with-push-email-and-sms-subscriptions-unified-by-external-id.png?fit=max\&auto=format\&n=mJXnj6xKtiaVBd7y\&q=85\&s=3e7d5ed8763acb24e0afa5c4ff8f0d81)

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

> [!NOTE]
>
> 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`.

```kotlin Kotlin theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
OneSignal.consentRequired = true

// Later, after the user grants consent
OneSignal.consentGiven = true
```

```java Java theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
OneSignal.setConsentRequired(true);

// Later, after the user grants consent
OneSignal.setConsentGiven(true);
```

> [!NOTE]
>
> Veja [Dados coletados pelo SDK](https://documentation.onesignal.com/docs/pt-BR/data-collected-by-the-onesignal-sdk.md) e [Tratamento de dados pessoais](https://documentation.onesignal.com/docs/pt-BR/handling-personal-data.md).

***

## 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](https://documentation.onesignal.com/docs/pt-BR/prompt-for-push-permissions.md).

***

## 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}
import android.util.Log
import com.onesignal.OneSignal
import com.onesignal.notifications.INotificationClickEvent
import com.onesignal.notifications.INotificationClickListener

val clickListener = object : INotificationClickListener {
    override fun onClick(event: INotificationClickEvent) {
        Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
    }
}
OneSignal.Notifications.addClickListener(clickListener)
```

```java Java theme={null}
import android.util.Log;
import com.onesignal.OneSignal;
import com.onesignal.notifications.INotificationClickEvent;
import com.onesignal.notifications.INotificationClickListener;

OneSignal.getNotifications().addClickListener(new INotificationClickListener() {
    @Override
    public void onClick(INotificationClickEvent event) {
        Log.d("OneSignal", "Notification clicked: " + event.getNotification().getTitle());
    }
});
```

### 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](https://documentation.onesignal.com/docs/pt-BR/mobile-sdk-reference.md).

```kotlin Kotlin theme={null}
import com.onesignal.OneSignal
import com.onesignal.user.subscriptions.IPushSubscriptionObserver
import com.onesignal.user.subscriptions.PushSubscriptionChangedState

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}")
        }
    }
}
```

```java Java theme={null}
import com.onesignal.OneSignal;
import com.onesignal.user.subscriptions.IPushSubscriptionObserver;
import com.onesignal.user.subscriptions.PushSubscriptionChangedState;

public class MyObserver implements IPushSubscriptionObserver {
    public MyObserver() {
        OneSignal.getUser().getPushSubscription().addObserver(this);
    }

    @Override
    public void onPushSubscriptionChange(PushSubscriptionChangedState state) {
        if (state.getCurrent().getOptedIn()) {
            android.util.Log.d("OneSignal", "User is now opted-in with push token: " + state.getCurrent().getToken());
        }
    }
}
```

### Eventos de mensagens in-app

Métodos adicionais de mensagens in-app estão disponíveis na [Referência do SDK Mobile](https://documentation.onesignal.com/docs/pt-BR/mobile-sdk-reference.md).

```kotlin Kotlin theme={null}
import com.onesignal.OneSignal
import com.onesignal.inAppMessages.IInAppMessageClickEvent
import com.onesignal.inAppMessages.IInAppMessageClickListener

val clickListener = object : IInAppMessageClickListener {
    override fun onClick(event: IInAppMessageClickEvent) {
        println(event.result.actionId)
    }
}
OneSignal.InAppMessages.addClickListener(clickListener)
```

```java Java theme={null}
import com.onesignal.OneSignal;
import com.onesignal.inAppMessages.IInAppMessageClickEvent;
import com.onesignal.inAppMessages.IInAppMessageClickListener;

OneSignal.getInAppMessages().addClickListener(new IInAppMessageClickListener() {
    @Override
    public void onClick(IInAppMessageClickEvent event) {
        android.util.Log.d("OneSignal", String.valueOf(event.getResult().getActionId()));
    }
});
```

***

## Configuração avançada e recursos

### Recursos específicos do Android

* **[Canais de notificação](https://documentation.onesignal.com/docs/pt-BR/mobile-sdk-reference.md#notification-channels):** Organize notificações em categorias (Android 8.0+)
* **[Service extensions](https://documentation.onesignal.com/docs/pt-BR/service-extensions.md):** Personalização avançada de notificações
* **[Huawei/HMS](https://documentation.onesignal.com/docs/pt-BR/huawei-sdk-setup.md):** Alternativa ao Google Play Services

### Recursos universais

* [Deep linking](https://documentation.onesignal.com/docs/pt-BR/deep-linking.md): Navegue os usuários para telas específicas a partir de notificações
* [Botões de ação](https://documentation.onesignal.com/docs/pt-BR/action-buttons.md): Adicione botões interativos às notificações
* [Verificação de identidade](https://documentation.onesignal.com/docs/pt-BR/identity-verification.md): Identificação segura de usuários
* [Rastreamento de localização](https://documentation.onesignal.com/docs/pt-BR/mobile-sdk-reference.md#location): Segmentação baseada em localização
* [Integrações](https://documentation.onesignal.com/docs/pt-BR/integrations.md): Conecte com plataformas de análise e dados
* [Mensagens multilíngues](https://documentation.onesignal.com/docs/pt-BR/multi-language-messaging.md): Notificações localizadas

Para documentação completa dos métodos do SDK, consulte a [Referência do SDK Mobile](https://documentation.onesignal.com/docs/pt-BR/mobile-sdk-reference.md).

***

## 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](https://documentation.onesignal.com/docs/pt-BR/notification-icons.md).

### 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](#step-0-configure-fcm-in-onesignal-required-to-deliver-push) e confirme que o status da Subscription é **Subscribed**. Em seguida, veja [Push mobile não exibido](https://documentation.onesignal.com/docs/pt-BR/notifications-show-successful-but-are-not-being-shown.md).

### 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](https://documentation.onesignal.com/docs/en/sessions.md) e [como as mensagens in-app são exibidas](https://documentation.onesignal.com/docs/pt-BR/in-app-messages-setup.md#how-are-iams-displayed%3F).

### 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](https://documentation.onesignal.com/docs/pt-BR/capturing-a-debug-log.md).

***

> [!NOTE]
>
> 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](https://documentation.onesignal.com/docs/pt-BR/capturing-a-debug-log.md) relevantes
>
> Estamos felizes em ajudar!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.