Criar uma notificação

As notificações fornecem informações curtas e oportunas sobre eventos no seu app enquanto se ele não estiver em uso. Este documento mostra como criar uma notificação com diversos recursos. Para uma introdução a como as notificações aparecem no Android, consulte a Visão geral de notificações. Para ver um exemplo de código que usa notificações, consulte a seção Pessoas amostra no GitHub.

O código desta página usa NotificationCompat APIs da biblioteca do AndroidX. Essas APIs permitem adicionar recursos disponíveis apenas em versões mais recentes do Android e ainda oferece compatibilidade com o Android 9 (nível 28 da API). No entanto, alguns recursos, como a ação de resposta inline, resultem em um ambiente autônomo em versões anteriores.

Adicionar a biblioteca AndroidX Core

Embora a maioria dos projetos criados com o Android Studio inclua as informações necessárias dependências para usar o NotificationCompat, verifique se o nível do módulo O arquivo build.gradle inclui a seguinte dependência:

dependencies {
    implementation "androidx.core:core:2.2.0"
}

dependencies {
    implementation("androidx.core:core-ktx:2.2.0")
}

Criar uma notificação básica

Uma notificação na sua forma mais básica e compacta, também conhecida como recolhida formulário: exibe um ícone, um título e uma pequena quantidade de texto. Isso mostra como criar uma notificação em que o usuário pode tocar para iniciar uma atividades em seu aplicativo.

Figura 1. Uma notificação com um ícone, um título e um texto.

Para obter mais detalhes sobre cada parte de uma notificação, leia sobre notificações anatomia do corpo.

Declarar a permissão de execução

O Android 13 (nível 33 da API) e versões mais recentes oferecem suporte a uma permissão de execução para postagem não isentas (incluindo de serviços em primeiro plano (FGS, na sigla em inglês)) de um app.

A permissão que você precisa declarar no arquivo de manifesto do app é exibida no seguinte snippet de código:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

Para mais detalhes sobre as permissões de execução, consulte Permissão de execução de notificações.

Definir o conteúdo das notificações

Para começar, defina o conteúdo e o canal da notificação usando um NotificationCompat.Builder objeto. O exemplo a seguir mostra como criar uma notificação com o seguinte:

• Um pequeno ícone, definido por setSmallIcon() Esse é o único conteúdo visível ao usuário necessário.

• Um título, definido por setContentTitle()

• O corpo do texto, definido por setContentText()

• A prioridade da notificação, definida por setPriority() A prioridade determina se a notificação é invasiva no Android 7.1 e antes. Para o Android 8.0 e versões mais recentes, defina a importância do canal como como mostrado na próxima seção.

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

O construtor NotificationCompat.Builder exige que você forneça um valor de ID. Isso é necessário para compatibilidade com o Android 8.0 (API de nível 26) e posteriores, mas é ignorado pelas versões anteriores.

Por padrão, o conteúdo do texto da notificação é truncado para caber em uma única linha. Você pode mostrar informações adicionais criando uma notificação expansível.

Figura 2. Um anúncio expansível de notificação em formulários recolhidos e expandidos.

Se você quiser que sua notificação seja mais longa, ative um anúncio adicionando um modelo de estilo com setStyle() Por exemplo, o código a seguir cria uma área de texto maior:

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(new NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

Para mais informações sobre outros estilos de notificação grandes, incluindo como adicionar uma imagem e controles de reprodução de mídia, consulte Criar um anúncio notificação.

Criar um canal e definir a importância

Antes de entregar a notificação no Android 8.0 e posterior, registre seu canal de notificação do app com o do sistema passando uma instância do NotificationChannel para createNotificationChannel(). O código a seguir está bloqueado por uma condição no Versão do SDK_INT:

private fun createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        val name = getString(R.string.channel_name)
        val descriptionText = getString(R.string.channel_description)
        val importance = NotificationManager.IMPORTANCE_DEFAULT
        val channel = NotificationChannel(CHANNEL_ID, name, importance).apply {
            description = descriptionText
        }
        // Register the channel with the system.
        val notificationManager: NotificationManager =
            getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.createNotificationChannel(channel)
    }
}

private void createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        CharSequence name = getString(R.string.channel_name);
        String description = getString(R.string.channel_description);
        int importance = NotificationManager.IMPORTANCE_DEFAULT;
        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance);
        channel.setDescription(description);
        // Register the channel with the system; you can't change the importance
        // or other notification behaviors after this.
        NotificationManager notificationManager = getSystemService(NotificationManager.class);
        notificationManager.createNotificationChannel(channel);
    }
}

Como é preciso criar o canal de notificação antes de publicar notificações no Android 8.0 e versões posteriores, execute esse código assim que seu app começa. É seguro chamar isso repetidamente, porque a criação de um objeto canal de notificação não realiza nenhuma operação.

O construtor NotificationChannel requer um importance, usando um dos das constantes da linha NotificationManager. Isso determina como interromper o usuário para qualquer notificação que pertença para este canal. Defina a prioridade com setPriority() para oferecer suporte ao Android 7.1 e anteriores, como mostrado no exemplo anterior.

Ainda que você deva definir a importância ou prioridade da notificação, conforme exemplo a seguir, o sistema não garante o comportamento do alerta que você recebe. Em em alguns casos, o sistema pode alterar o nível de importância com base em outros fatores, e o usuário pode sempre redefinir o nível de importância de um canal.

Para mais informações sobre o significado dos diferentes níveis, leia sobre importância das notificações níveis.

Definir a ação de toque da notificação

Cada notificação precisa responder a um toque, geralmente para abrir uma atividade no seu aplicativo que corresponde à notificação. Para fazer isso, especifique uma intent de conteúdo definida com um PendingIntent e passá-lo para setContentIntent()

O seguinte snippet mostra como criar uma intent básica para abrir uma atividade quando o usuário toca na notificação:

// Create an explicit intent for an Activity in your app.
val intent = Intent(this, AlertDetails::class.java).apply {
    flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
}
val pendingIntent: PendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE)

val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true)

// Create an explicit intent for an Activity in your app.
Intent intent = new Intent(this, AlertDetails.class);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true);

Esse código chama setAutoCancel(), que remove automaticamente a notificação quando o usuário toca nela.

O método setFlags() mostrado no exemplo anterior preserva a navegação esperada pelo usuário após abrir o app usando a notificação. Talvez você queira usá-lo dependendo do tipo de atividade que você está iniciando, que pode ser um dos o seguinte:

• Uma atividade que existe exclusivamente para respostas à notificação. Não há motivo para o usuário navegar para essa atividade durante o uso normal do app. para que a atividade inicie uma nova tarefa em vez de ser adicionada ao tarefa existente e pilha. Esta é a o tipo de intent criada no exemplo anterior.

• Uma atividade que existe no fluxo regular do seu app. Nesse caso, iniciar a atividade cria uma backstack para que as expectativas do usuário para os botões Voltar e Para cima são preservados.

Para saber mais sobre as diferentes maneiras de configurar o intent da sua notificação, consulte Iniciar uma atividade em uma notificação.

Mostrar a notificação

Para que a notificação seja exibida, chame NotificationManagerCompat.notify(), passando um ID exclusivo para a notificação, e o resultado de NotificationCompat.Builder.build() Isso é mostrado neste exemplo:

with(NotificationManagerCompat.from(this)) {
    if (ActivityCompat.checkSelfPermission(
            this@MainActivity,
            Manifest.permission.POST_NOTIFICATIONS
        ) != PackageManager.PERMISSION_GRANTED
    ) {
        // TODO: Consider calling
        // ActivityCompat#requestPermissions
        // here to request the missing permissions, and then overriding
        // public fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>,
        //                                        grantResults: IntArray)
        // to handle the case where the user grants the permission. See the documentation
        // for ActivityCompat#requestPermissions for more details.

        return@with
    }
    // notificationId is a unique int for each notification that you must define.
    notify(NOTIFICATION_ID, builder.build())
}

with(NotificationManagerCompat.from(this)) {
   if (ActivityCompat.checkSelfPermission(
           this@MainActivity,
           Manifest.permission.POST_NOTIFICATIONS
       ) != PackageManager.PERMISSION_GRANTED
   ) {
       // TODO: Consider calling
       // ActivityCompat#requestPermissions
       // here to request the missing permissions, and then overriding
       // public void onRequestPermissionsResult(int requestCode, String[] permissions,
       //                                        int[] grantResults)
       // to handle the case where the user grants the permission. See the documentation
       // for ActivityCompat#requestPermissions for more details.

       return
   }
   // notificationId is a unique int for each notification that you must define.
   notify(NOTIFICATION_ID, builder.build())
}

Salve o ID da notificação que você transmitir para NotificationManagerCompat.notify(). porque é necessário para atualizar ou remover o notificação.

Além disso, para testar notificações básicas em dispositivos executados em No Android 13 e versões mais recentes, ative as notificações manualmente ou crie uma caixa de diálogo para: notificações de solicitações.

Adicionar botões de ação

Uma notificação pode oferecer até três botões de ação que permitem ao usuário responder rapidamente, por exemplo, para adiar um lembrete ou responder a uma mensagem de texto. Mas esses os botões de ação não devem duplicar a ação executada quando o usuário toca no notificação.

Figura 3. Uma notificação com um botão de ação.

Para adicionar um botão de ação, transmita um PendingIntent para o addAction() . Esse processo é semelhante a configurar a ação de toque padrão da notificação, exceto pelo fato de que em vez de iniciar uma atividade, você pode fazer outras coisas, como iniciar uma BroadcastReceiver que executa um job em segundo plano para que a ação não interrompa o app. que já está aberto.

Por exemplo, o seguinte código mostra como enviar uma transmissão a um receptor específico:

val ACTION_SNOOZE = "snooze"

val snoozeIntent = Intent(this, MyBroadcastReceiver::class.java).apply {
    action = ACTION_SNOOZE
    putExtra(EXTRA_NOTIFICATION_ID, 0)
}
val snoozePendingIntent: PendingIntent =
    PendingIntent.getBroadcast(this, 0, snoozeIntent, 0)</span>
val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent)

String ACTION_SNOOZE = "snooze"

Intent snoozeIntent = new Intent(this, MyBroadcastReceiver.class);
snoozeIntent.setAction(ACTION_SNOOZE);
snoozeIntent.putExtra(EXTRA_NOTIFICATION_ID, 0);
PendingIntent snoozePendingIntent =
        PendingIntent.getBroadcast(this, 0, snoozeIntent, 0);</span>

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent);

Para saber mais sobre como criar um BroadcastReceiver para executar em segundo plano funcionar, consulte a Visão geral de transmissões.

Se você estiver tentando criar uma notificação com botões de reprodução de mídia, como pausar e pular faixas, confira como criar uma notificação com mídia controles de segurança.

Adicionar uma ação de resposta direta

A ação de resposta direta, introduzida no Android 7.0 (API de nível 24), permite que os usuários digitar o texto diretamente na notificação. O texto é entregue sem abrir uma atividade. Por exemplo, você pode usar uma ação de resposta direta para permitir que os usuários respondam a mensagens de texto ou atualizem listas de tarefas no notificação.

Figura 4. Tocar em "Responder" abre a entrada de texto.

A ação de "Resposta direta" aparece como um outro botão na notificação que abre uma entrada de texto. Quando o usuário termina de digitar, o sistema anexa o texto resposta para a intent especificada para a ação de notificação e envia a para seu app.

Adicionar o botão de resposta

Para criar uma ação de notificação compatível com a resposta direta, siga estas etapas:

1. Crie uma instância de RemoteInput.Builder que você pode adicionar à sua ação de notificação. O construtor dessa classe aceita uma string que o sistema usa como chave para a entrada de texto. Seu app mais tarde usa essa chave para recuperar o texto da entrada.

   Kotlin

     // Key for the string that's delivered in the action's intent.
     private val KEY_TEXT_REPLY = "key_text_reply"
     var replyLabel: String = resources.getString(R.string.reply_label)
     var remoteInput: RemoteInput = RemoteInput.Builder(KEY_TEXT_REPLY).run {
         setLabel(replyLabel)
         build()
     }
     

   Java

     // Key for the string that's delivered in the action's intent.
     private static final String KEY_TEXT_REPLY = "key_text_reply";
   
     String replyLabel = getResources().getString(R.string.reply_label);
     RemoteInput remoteInput = new RemoteInput.Builder(KEY_TEXT_REPLY)
             .setLabel(replyLabel)
             .build();
     

2. Crie uma PendingIntent para a ação de resposta.

   Kotlin

     // Build a PendingIntent for the reply action to trigger.
     var replyPendingIntent: PendingIntent =
         PendingIntent.getBroadcast(applicationContext,
             conversation.getConversationId(),
             getMessageReplyIntent(conversation.getConversationId()),
             PendingIntent.FLAG_UPDATE_CURRENT)
     

   Java

     // Build a PendingIntent for the reply action to trigger.
     PendingIntent replyPendingIntent =
             PendingIntent.getBroadcast(getApplicationContext(),
                     conversation.getConversationId(),
                     getMessageReplyIntent(conversation.getConversationId()),
                     PendingIntent.FLAG_UPDATE_CURRENT);
     

3. Anexe o RemoteInput objeto para uma ação usando addRemoteInput().

   Kotlin

     // Create the reply action and add the remote input.
     var action: NotificationCompat.Action =
         NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
             getString(R.string.label), replyPendingIntent)
             .addRemoteInput(remoteInput)
             .build()
     

   Java

     // Create the reply action and add the remote input.
     NotificationCompat.Action action =
             new NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
                     getString(R.string.label), replyPendingIntent)
                     .addRemoteInput(remoteInput)
                     .build();
     

4. Aplique a ação a uma notificação e emita a notificação.

   Kotlin

     // Build the notification and add the action.
     val newMessageNotification = Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build()
   
     // Issue the notification.
     with(NotificationManagerCompat.from(this)) {
         notificationManager.notify(notificationId, newMessageNotification)
     }
     

   Java

     // Build the notification and add the action.
     Notification newMessageNotification = new Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build();
   
     // Issue the notification.
     NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
     notificationManager.notify(notificationId, newMessageNotification);
     

O sistema solicita que o usuário insira uma resposta quando acionar o ação de notificação, como mostrado na Figura 4.

Recuperar entrada do usuário na resposta

Para receber a entrada do usuário a partir da interface de resposta da notificação, chame RemoteInput.getResultsFromIntent(), transmitindo o Intent recebido pelo BroadcastReceiver:

private fun getMessageText(intent: Intent): CharSequence? {
    return RemoteInput.getResultsFromIntent(intent)?.getCharSequence(KEY_TEXT_REPLY)
}

private CharSequence getMessageText(Intent intent) {
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
    if (remoteInput != null) {
        return remoteInput.getCharSequence(KEY_TEXT_REPLY);
    }
    return null;
 }

Depois de processar a mensagem de texto, atualize a notificação chamando NotificationManagerCompat.notify() com o mesmo ID e tag, se usados. Isso é necessário para ocultar a interface de "Resposta direta" e confirmar ao usuário que a resposta sejam recebidas e processadas corretamente.

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
val repliedNotification = Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build()

// Issue the new notification.
NotificationManagerCompat.from(this).apply {
    notificationManager.notify(notificationId, repliedNotification)
}

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
Notification repliedNotification = new Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build();

// Issue the new notification.
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
notificationManager.notify(notificationId, repliedNotification);

Ao trabalhar com essa nova notificação, use o contexto que é passado para o do destinatário onReceive() .

Anexe a resposta na parte inferior da notificação chamando setRemoteInputHistory() No entanto, se você estiver criando um aplicativo de mensagens, crie um estilo de mensagem notificação e anexe o nova mensagem à conversa.

Para mais dicas sobre notificações de apps de mensagens, consulte a seção sobre práticas recomendadas para apps de mensagens.

Adicionar uma barra de progresso

As notificações podem incluir um indicador de progresso animado que mostra aos usuários o status de uma operação em andamento.

Figura 5. A barra de progresso durante uma operação.

Se você puder estimar quanto da operação já foi concluído a qualquer momento, use o "determinar" forma do indicador (como mostrado na figura 5), chamando setProgress(max, progress, false) O primeiro parâmetro é o que o valor "complete" como 100. O segundo é quanto está completo. O último indica que este é um progresso determinado barra.

À medida que a operação prossegue, chame continuamente setProgress(max, progress, false) com um valor atualizado para progress e emita novamente a notificação, conforme como mostrado no exemplo a seguir.

val builder = NotificationCompat.Builder(this, CHANNEL_ID).apply {
    setContentTitle("Picture Download")
    setContentText("Download in progress")
    setSmallIcon(R.drawable.ic_notification)
    setPriority(NotificationCompat.PRIORITY_LOW)
}
val PROGRESS_MAX = 100
val PROGRESS_CURRENT = 0
NotificationManagerCompat.from(this).apply {
    // Issue the initial notification with zero progress.
    builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false)
    notify(notificationId, builder.build())

    // Do the job that tracks the progress here.
    // Usually, this is in a worker thread.
    // To show progress, update PROGRESS_CURRENT and update the notification with:
    // builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
    // notificationManager.notify(notificationId, builder.build());

    // When done, update the notification once more to remove the progress bar.
    builder.setContentText("Download complete")
            .setProgress(0, 0, false)
    notify(notificationId, builder.build())
}

...
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID);
builder.setContentTitle("Picture Download")
        .setContentText("Download in progress")
        .setSmallIcon(R.drawable.ic_notification)
        .setPriority(NotificationCompat.PRIORITY_LOW);

// Issue the initial notification with zero progress.
int PROGRESS_MAX = 100;
int PROGRESS_CURRENT = 0;
builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
notificationManager.notify(notificationId, builder.build());

// Do the job that tracks the progress here.
// Usually, this is in a worker thread.
// To show progress, update PROGRESS_CURRENT and update the notification with:
// builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
// notificationManager.notify(notificationId, builder.build());

// When done, update the notification once more to remove the progress bar.
builder.setContentText("Download complete")
        .setProgress(0,0,false);
notificationManager.notify(notificationId, builder.build());

No final da operação, progress precisa ser igual a max. Você pode deixar barra de progresso para mostrar que a operação foi concluída ou removê-la. Em ambos os casos, atualize o texto da notificação para mostrar que a operação foi concluída. Para remover a barra de progresso, chame setProgress(0, 0, false).

Exibir uma barra de progresso indeterminada (uma barra que não indica a conclusão) porcentagem), chame setProgress(0, 0, true). O resultado é um indicador do mesmo estilo da barra de progresso anterior, exceto por ser uma barra de progresso animação que não indica conclusão. A animação do progresso é executada até você chama setProgress(0, 0, false) e atualiza a notificação para remover o indicador de atividade.

Lembre-se de mudar o texto da notificação para indicar que a operação foi concluída.

Definir uma categoria para todo o sistema

O Android usa categorias predefinidas do sistema para determinar se isso deve perturbar o usuário a uma determinada notificação quando ele ativar o Não perturbe .

Caso sua notificação se enquadre em uma das categorias de notificação definidas no NotificationCompat, como CATEGORY_ALARM, CATEGORY_REMINDER, CATEGORY_EVENT, ou CATEGORY_CALL: declarar dessa forma passando a categoria apropriada para setCategory():

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setCategory(NotificationCompat.CATEGORY_MESSAGE)

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setCategory(NotificationCompat.CATEGORY_MESSAGE);

O sistema usa essas informações sobre a categoria de notificação para tomar decisões sobre a exibição da notificação quando o dispositivo está em Perturbe. No entanto, você não precisa definir uma categoria para todo o sistema. Apenas faça isso caso suas notificações correspondam a uma das categorias definidas no NotificationCompat:

Mostrar uma mensagem urgente

Seu app pode precisar exibir uma mensagem urgente e com limite de tempo, por exemplo, para uma chamada telefônica recebida ou um alarme tocando. Nessas situações, você pode associar um intent para tela cheia com sua notificação.

Quando a notificação é invocada, os usuários veem uma das seguintes opções, dependendo da o status de bloqueio do dispositivo:

• Se o dispositivo do usuário estiver bloqueado, uma atividade de tela cheia será exibida, cobrindo a tela de bloqueio;
• Se o dispositivo do usuário estiver desbloqueado, a notificação aparecerá de forma estendida, incluindo opções para interagir ou descartar a notificação.

O snippet de código a seguir demonstra como associar sua notificação a uma intent de tela cheia:

val fullScreenIntent = Intent(this, ImportantActivity::class.java)
val fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
    fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT)

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true)

Intent fullScreenIntent = new Intent(this, ImportantActivity.class);
PendingIntent fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
        fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true);

Definir a visibilidade da tela de bloqueio

Para controlar o nível de detalhes visível na notificação na tela de bloqueio, faça o seguinte: ligar setVisibility() e especifique um dos seguintes valores:

• VISIBILITY_PUBLIC: o conteúdo completo da notificação é exibido na tela de bloqueio.

• VISIBILITY_SECRET: nenhuma parte da notificação aparece na tela de bloqueio.

• VISIBILITY_PRIVATE: apenas informações básicas, como o ícone da notificação e o conteúdo aparece na tela de bloqueio. O conteúdo completo da notificação não show.

Ao definir VISIBILITY_PRIVATE, também é possível fornecer uma versão alternativa do o conteúdo da notificação que oculta determinados detalhes. Por exemplo, um app de SMS pode exibir uma notificação que mostre: "Você tem três novas mensagens de texto", mas oculta o conteúdo e os remetentes das mensagens. Para oferecer essa alternativa, crie uma notificação alternativa com NotificationCompat.Builder normalmente. Em seguida, anexe a notificação alternativa à notificação normal setPublicVersion()

Tenha em mente que o usuário sempre tem o controle final sobre notificações são visíveis na tela de bloqueio e pode controlá-las com base no seu canais de notificação do seu app.

Atualizar uma notificação

Para atualizar uma notificação depois de emiti-la, chame NotificationManagerCompat.notify() novamente, transmitindo o mesmo ID usado antes. Se a notificação anterior for dispensada, uma nova notificação será criada como alternativa.

Também é possível chamar setOnlyAlertOnce() de forma que sua notificação interrompa o usuário, seja por som, vibração ou vídeo pistas: somente na primeira vez que a notificação aparecer, e não para mais tarde atualizações.

Remover uma notificação

As notificações permanecem visíveis até que um dos seguintes casos aconteça:

• o usuário dispense a notificação;
• O usuário toca na notificação. Se você chamar setAutoCancel() quando crie a notificação.
• Você liga cancel() para um ID de notificação específico. Esse método também exclui notificações.
• Você liga cancelAll(), que remove todas as notificações emitidas anteriormente.
• A duração especificada decorrerá se você definir um tempo limite ao criar o notificação, usando setTimeoutAfter() Se necessário, é possível cancelar uma notificação antes do tempo limite especificado decorrido.

Práticas recomendadas para apps de mensagens

Considere as práticas recomendadas listadas aqui ao criar notificações para seus aplicativos de mensagens e bate-papo.

Usar MessagingStyle

A partir do Android 7.0 (API de nível 24), o Android oferece um estilo de notificação especificamente para conteúdo de mensagens. Usar o NotificationCompat.MessagingStyle é possível alterar vários rótulos exibidos na notificação, incluindo o título da conversa, as mensagens adicionais e a visualização de conteúdo para a notificação.

O snippet de código a seguir demonstra como personalizar o estilo de uma notificação. usando a classe MessagingStyle.

val user = Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build()

val notification = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with $sender")
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build()

Person user = new Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build();

Notification notification = new NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with " + sender)
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(new NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build();

A partir do Android 9.0 (API de nível 28), também é necessário usar o Person para ter um renderização ideal da notificação e seus avatares.

Ao usar NotificationCompat.MessagingStyle, faça o seguinte:

• Ligação MessagingStyle.setConversationTitle() para definir um título para grupos de chat com mais de duas pessoas. Uma boa o título da conversa pode ser o nome do bate-papo em grupo ou, caso não seja, ter um nome, uma lista dos participantes da conversa. Sem isso, a mensagem pode ser interpretada como pertencente a uma conversa individual com o remetente da mensagem mais recente da conversa.
• Use o MessagingStyle.setData() para incluir mensagens de mídia, como imagens. Tipos MIME do padrão image/* são suportados.

Usar a resposta direta

O recurso "Resposta direta" permite que o usuário responda inline a uma mensagem.

• Depois que um usuário responder com a ação de resposta in-line, use MessagingStyle.addMessage() para atualizar a notificação MessagingStyle e não retire nem cancele a notificação. O não cancelamento da notificação permite que o usuário envie vários respostas da notificação.
• Para tornar a ação de resposta in-line compatível com o Wear OS, chame Action.WearableExtender.setHintDisplayInlineAction(true)
• Use o addHistoricMessage() para fornecer contexto a uma conversa de resposta direta adicionando histórico à notificação.

Ativar a Resposta inteligente

• Para ativar a Resposta inteligente, ligue setAllowGeneratedResponses(true) na ação de resposta. Isso faz com que as respostas da Resposta inteligente sejam disponibilizadas para aos usuários quando a notificação é conectada a um dispositivo Wear OS. Resposta inteligente as respostas são geradas por um modelo de machine learning no próprio relógio, usando o contexto fornecido pelo NotificationCompat.MessagingStyle e nenhum dado é enviado à Internet para gerar a de resposta.

Adicionar metadados de notificação

• Atribua metadados de notificação para informar ao sistema como lidar com seu app notificações quando o dispositivo estiver no Do Not Disturb mode. Por exemplo: use o método addPerson() ou setCategory(Notification.CATEGORY_MESSAGE) para substituir o modo Não perturbe.