As notificações fornecem informações curtas e oportunas sobre eventos no seu app enquanto ele não está em uso. Este documento mostra como criar uma notificação com vários recursos. Para uma introdução de como as notificações aparecem no Android, consulte a Visão geral das notificações. Para ver o exemplo de código que usa notificações, consulte o exemplo de pessoas (link em inglês) no GitHub.
O código desta página usa as APIs
NotificationCompat
da Biblioteca AndroidX. Essas APIs permitem que você adicione recursos disponíveis apenas
em versões mais recentes do Android e também oferecem compatibilidade com o Android
9 (nível 28 da API). No entanto, alguns recursos, como a ação de resposta in-line, resultam 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 dependências
necessárias para usar o NotificationCompat
, verifique se o arquivo
build.gradle
no nível do módulo inclui a seguinte dependência:
Groovy
dependencies { implementation "androidx.core:core:2.2.0" }
Kotlin
dependencies { implementation("androidx.core:core-ktx:2.2.0") }
Criar uma notificação básica
Uma notificação na forma mais básica e compacta, também conhecida como forma recolhida, exibe um ícone, um título e uma pequena quantidade de texto. Esta seção mostra como criar uma notificação que o usuário pode tocar para iniciar uma atividade no app.
Para mais detalhes sobre cada parte de uma notificação, leia sobre a anatomia da notificação.
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 postar notificações não isentas (incluindo serviços em primeiro plano (FGS)) de um app.
A permissão que precisa ser declarada no arquivo de manifesto do app aparece no snippet de código abaixo:
<manifest ...> <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> <application ...> ... </application> </manifest>
Para mais detalhes sobre permissões de execução, consulte Permissão de execução de notificação.
Definir o conteúdo das notificações
Para começar, defina o conteúdo e o canal da notificação usando um objeto
NotificationCompat.Builder
. O exemplo a seguir mostra como criar uma notificação com o
seguinte:
Um ícone pequeno, definido por
setSmallIcon()
. Esse é o único conteúdo visível ao usuário necessário.Um título, definido por
setContentTitle()
.O texto do corpo, definido por
setContentText()
.A prioridade da notificação, definida por
setPriority()
. A prioridade determina se a notificação será intrusiva ou não no Android 7.1 e versões anteriores. Para o Android 8.0 e versões mais recentes, defina a importância do canal conforme mostrado na próxima seção.
Kotlin
var builder = NotificationCompat.Builder(this, CHANNEL_ID) .setSmallIcon(R.drawable.notification_icon) .setContentTitle(textTitle) .setContentText(textContent) .setPriority(NotificationCompat.PRIORITY_DEFAULT)
Java
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 ID
do canal. Isso é necessário para que haja compatibilidade com o Android 8.0 (API de nível 26) e
versões mais recentes, 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.
Para que sua notificação seja mais longa, é possível ativar uma notificação
expandível adicionando um modelo de estilo com
setStyle()
.
Por exemplo, o código a seguir cria uma área de texto maior:
Kotlin
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)
Java
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 saber mais sobre outros estilos de notificação grandes, incluindo como adicionar uma imagem e controles de reprodução de mídia, consulte Criar uma notificação expansível.
Criar um canal e definir a importância
Antes de enviar a notificação no Android 8.0 e versões mais recentes, registre o
canal de notificação do seu app no
sistema transmitindo uma instância de
NotificationChannel
para
createNotificationChannel()
.
O código a seguir é bloqueado por uma condição na
versão SDK_INT
:
Kotlin
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) } }
Java
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 é necessário criar o canal de notificação antes de postar notificações no Android 8.0 e versões mais recentes, execute esse código assim que o app for iniciado. Não há problemas em chamar isso repetidamente, porque a criação de um canal de notificação já existente não realiza uma operação.
O construtor NotificationChannel
exige uma importance
, usando uma das
constantes da
classe NotificationManager
. Esse
parâmetro determina como interromper o usuário para mostrar uma notificação que pertença
a esse canal. Defina a prioridade com setPriority()
para oferecer suporte ao Android 7.1
e versões anteriores, conforme mostrado no exemplo anterior.
Ainda que você precise definir a importância ou prioridade da notificação, como mostrado no exemplo abaixo, o sistema não garante o comportamento do alerta. Em alguns casos, o sistema pode mudar o nível de importância com base em outros fatores, e o usuário pode sempre redefinir o nível de importância para determinado canal.
Para saber mais sobre o significado dos diferentes níveis, leia sobre os níveis de importância da notificação.
Definir a ação de toque da notificação
Toda notificação precisa responder a um toque, geralmente para abrir uma atividade no
app correspondente à notificação. Para fazer isso, especifique uma intent de conteúdo
definida com um objeto PendingIntent
e transmita-a para
setContentIntent()
.
O seguinte snippet mostra como criar uma intent básica para abrir uma atividade quando o usuário toca na notificação:
Kotlin
// 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)
Java
// 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 a notificação automaticamente quando o usuário toca nela.
O método setFlags()
mostrado no exemplo anterior preserva a experiência de navegação esperada pelo usuário
depois que ele abre o app usando a notificação. Talvez seja necessário
usá-lo dependendo do tipo de atividade que você está iniciando, que pode ser uma das
seguintes:
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. Portanto, a atividade inicia uma nova tarefa, em vez de ser adicionada à tarefa e à pilha de retorno existentes no seu app. Esse é o tipo de intent criado no exemplo anterior.
Uma atividade que existe no fluxo regular do seu app. Nesse caso, o início da atividade cria uma backstack para que as expectativas do usuário para os botões Voltar e Para cima sejam preservadas.
Para saber mais sobre as diferentes maneiras de configurar a intent da sua notificação, consulte Iniciar uma atividade a partir de uma notificação.
Mostrar a notificação
Para que a notificação apareça, chame
NotificationManagerCompat.notify()
,
transmitindo um ID exclusivo para a notificação e o resultado de
NotificationCompat.Builder.build()
.
Isso é mostrado neste exemplo:
Kotlin
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()) }
Java
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ê transmite para NotificationManagerCompat.notify()
,
porque você vai precisar dele para atualizar ou remover a
notificação.
Além disso, para testar notificações básicas em dispositivos com o Android 13 e versões mais recentes, ative as notificações manualmente ou crie uma caixa de diálogo para solicitar notificaçõ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, como adiar um lembrete ou responder a uma mensagem de texto. No entanto, esses botões de ação não podem duplicar a ação realizada quando o usuário toca na notificação.
Para adicionar um botão de ação, transmita uma PendingIntent
para o
método
addAction()
. É como configurar a ação de toque padrão da notificação, exceto
que, em vez de iniciar uma atividade, você pode fazer outras coisas, como iniciar um
BroadcastReceiver
que
execute 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:
Kotlin
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) 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)
Java
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); 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 um trabalho
em segundo plano, consulte a Visão geral de transmissões.
Se você estiver tentando criar uma notificação com os botões de reprodução de mídia (por exemplo, pausar e pular faixas), consulte como criar uma notificação com controles de mídia.
Adicionar uma ação de resposta direta
A ação de resposta direta, introduzida no Android 7.0 (nível 24 da API), permite que os usuários insiram texto diretamente na notificação. O texto é enviado ao seu app 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 na notificação.
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 a resposta de texto à intent especificada para a ação de notificação e envia a intent ao app.
Adicionar o botão de resposta
Para criar uma ação de notificação compatível com a resposta direta, siga estas etapas:
- Crie uma instância de
RemoteInput.Builder
que possa ser adicionada à ação de notificação. O construtor dessa classe aceita uma string que o sistema usa como chave para a entrada de texto. O app vai usar 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();
- 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);
- Anexe o
objeto
RemoteInput
a uma ação usandoaddRemoteInput()
.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();
- 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 informe uma resposta quando a ação de notificação é acionada, conforme mostrado na Figura 4.
Recuperar entrada do usuário na resposta
Para receber a entrada do usuário da interface de resposta da notificação, chame
RemoteInput.getResultsFromIntent()
,
transmitindo o Intent
recebido pelo BroadcastReceiver
:
Kotlin
private fun getMessageText(intent: Intent): CharSequence? { return RemoteInput.getResultsFromIntent(intent)?.getCharSequence(KEY_TEXT_REPLY) }
Java
private CharSequence getMessageText(Intent intent) { Bundle remoteInput = RemoteInput.getResultsFromIntent(intent); if (remoteInput != null) { return remoteInput.getCharSequence(KEY_TEXT_REPLY); } return null; }
Depois de processar o 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
foi recebida e processada corretamente.
Kotlin
// 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) }
Java
// 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 é transmitido para o
método
onReceive()
do receptor.
Anexe a resposta à parte inferior da notificação chamando
setRemoteInputHistory()
.
No entanto, se você estiver criando um app de mensagens, crie uma notificação em estilo de
mensagem e anexe a nova mensagem à conversa.
Para mais orientações 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.
Se for possível estimar quanto da operação já foi concluída em determinado momento, use a
forma "determinada" do indicador, como mostrado na Figura 5, chamando
setProgress(max, progress,
false)
.
O primeiro parâmetro é o valor "completo", como 100. O segundo é
o quanto está concluído. O último indica que esta é uma barra de progresso
determinada.
À 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
mostrado no exemplo a seguir.
Kotlin
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()) }
Java
... 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
. É possível deixar a
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)
.
Para exibir uma barra de progresso indeterminada (uma barra que não indique a porcentagem
de conclusão), chame setProgress(0, 0, true)
. O resultado é um indicador com
o mesmo estilo da barra de progresso anterior, exceto que é uma animação
contínua que não indica a conclusão. A animação do progresso é executada até que
você chame setProgress(0, 0, false)
e atualize 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 de todo o sistema para determinar se o usuário receberá uma notificação específica quando ele ativar o modo Não perturbe.
Se a notificação se enquadra em uma das categorias definidas em
NotificationCompat
, como
CATEGORY_ALARM
,
CATEGORY_REMINDER
,
CATEGORY_EVENT
ou
CATEGORY_CALL
, declare-a
dessa forma transmitindo a categoria adequada a
setCategory()
:
Kotlin
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)
Java
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 da notificação para tomar
decisões sobre como mostrá-la quando o dispositivo estiver no modo "Não
perturbar". No entanto, você não precisa definir uma categoria para todo o sistema. Faça isso
apenas se as notificações corresponderem a uma das categorias definidas em
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 uma intent de tela cheia à sua notificação.
Quando a notificação é invocada, os usuários veem um dos seguintes itens, dependendo do 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:
Kotlin
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)
Java
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,
chame
setVisibility()
e especifique um dos seguintes valores:
VISIBILITY_PUBLIC
: o conteúdo completo da notificação aparece 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 título do conteúdo, são mostradas na tela de bloqueio. O conteúdo completo da notificação não é exibido.
Ao definir VISIBILITY_PRIVATE
, também é possível fornecer uma versão alternativa do
conteúdo da notificação que oculta determinados detalhes. Por exemplo, um app de SMS
pode mostrar uma notificação que mostre "Você tem três novas mensagens de texto", mas
oculte o conteúdo e o remetente das mensagens. Para fornecer essa notificação
alternativa, comece criando-a com
NotificationCompat.Builder
, como normalmente. Em seguida, anexe a notificação alternativa
à notificação normal com
setPublicVersion()
.
O usuário sempre tem o controle final sobre a exibição de notificações na tela de bloqueio e pode controlar isso com base nos canais de notificação do app.
Atualizar uma notificação
Para atualizar uma notificação após emiti-la, chame
NotificationManagerCompat.notify()
novamente, transmitindo o mesmo ID usado
anteriormente. Se a notificação anterior for dispensada, uma nova notificação será criada.
Você também pode chamar
setOnlyAlertOnce()
para que a notificação interrompa o usuário (com som, vibração ou dicas
visuais) apenas na primeira vez que aparecer, e não nas atualizações
posteriores.
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()
ao criar a notificação. - Você chama
cancel()
para um ID de notificação específico. Esse método também exclui notificações contínuas. - Você chama
cancelAll()
, que remove todas as notificações emitidas anteriormente. - A duração especificada expira se você definir um tempo limite ao criar a
notificação usando
setTimeoutAfter()
. Se necessário, você pode cancelar uma notificação antes do término do tempo limite especificado.
Práticas recomendadas para apps de mensagens
Considere as práticas recomendadas listadas aqui ao criar notificações para seus apps de mensagens e bate-papo.
Usar MessagingStyle
A partir do Android 7.0 (nível 24 da API), o Android oferece um modelo de estilo
de notificação especificamente para o conteúdo de mensagens. Usando a classe
NotificationCompat.MessagingStyle
,
você pode mudar vários rótulos exibidos na notificação,
incluindo o título da conversa, outras mensagens 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
.
Kotlin
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()
Java
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 (nível 28 da API), também é necessário usar a classe
Person
para renderizar
da melhor forma possível a notificação e os avatares dela.
Ao usar NotificationCompat.MessagingStyle
, faça o seguinte:
- Chame
MessagingStyle.setConversationTitle()
para definir um título para chats em grupo com mais de duas pessoas. Um bom título para uma conversa pode ser o nome do chat em grupo ou, se ele não tiver um nome, uma lista dos participantes da conversa. Sem isso, a mensagem pode ser entendida como uma conversa individual com o remetente da mensagem mais recente da conversa. - Use o método
MessagingStyle.setData()
para incluir mensagens de mídia, como imagens. Os tipos MIME do padrão image/* são compatíveis.
Usar a resposta direta
O recurso "Resposta direta" permite que um usuário responda inline a uma mensagem.
- Depois que um usuário responder com a ação de resposta inline, use
MessagingStyle.addMessage()
para atualizar a notificaçãoMessagingStyle
e não retire nem cancele a notificação. O não cancelamento da notificação permite que o usuário envie várias respostas a partir dela. - Para tornar a ação de resposta in-line compatível com o Wear OS, chame
Action.WearableExtender.setHintDisplayInlineAction(true)
. - Use o método
addHistoricMessage()
para fornecer contexto a uma conversa de resposta direta, adicionando mensagens históricas à notificação.
Ativar a Resposta inteligente
- Para ativar o recurso "Resposta inteligente", chame
setAllowGeneratedResponses(true)
na ação de resposta. Isso faz com que as respostas do recurso "Resposta inteligente" estejam disponíveis aos usuários quando a notificação é conectada a um dispositivo Wear OS. As respostas da Resposta inteligente são geradas por um modelo de aprendizado de máquina no próprio relógio, usando o contexto fornecido pela notificaçãoNotificationCompat.MessagingStyle
, e nenhum dado é enviado para a Internet para gerar as respostas.
Adicionar metadados de notificação
- Atribua metadados de notificação para informar ao sistema como processar as notificações
do app quando o dispositivo estiver no
Do Not Disturb mode
. Por exemplo, use o métodoaddPerson()
ousetCategory(Notification.CATEGORY_MESSAGE)
para substituir o "Não perturbe".