Escolar Documentos
Profissional Documentos
Cultura Documentos
Embora a maioria dos projetos criados com o Android Studio inclua as dependências necessárias
para usar NotificationCompat, verifique se o arquivo build.gradle no nível de módulo inclui a seguinte
dependência:
dependencies {
implementation "com.android.support:support-compat:28.0.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 do conteúdo. Nesta seção, você
aprenderá como criar uma notificação em que o usuário pode clicar para iniciar uma atividade no seu
app.
Para começar, você precisa configurar 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 corpo do texto, definido por setContentText().
A prioridade de 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, você precisa definir a importância do canal, mostrada na próxima seção.
KotlinJava
var builder = NotificationCompat.Builder(this, CHANNEL_ID)
.setSmallIcon(R.drawable.notification_icon)
.setContentTitle(textTitle)
.setContentText(textContent)
.setPriority(NotificationCompat.PRIORITY_DEFAULT)
Por padrão, o conteúdo do texto da notificação é truncado para caber em uma única linha. Para que
sua notificação seja mais longa, é possível ativar uma notificação expansível ao adicionar um modelo
de estilo com setStyle(). Por exemplo, o código a seguir cria uma área de texto maior:
KotlinJava
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)
Criar um canal e definir a importância
Antes de entregar a notificação no Android 8.0 e versões mais recentes, você precisa registrar o
canal de notificação do seu app no sistema, transmitindo uma instância de NotificationChannel para
createNotificationChannel(). Portanto, o código a seguir é bloqueado por uma condição na versão
SDK_INT:
KotlinJava
private fun createNotificationChannel() {
// Create the NotificationChannel, but only on API 26+ because
// the NotificationChannel class is new and 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)
}
}
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 chamá-lo
repetidamente, porque a criação de um canal de notificação já existente não realiza uma operação.
Observe que 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. Mas ainda é necessário definir a prioridade com
setPriority() para oferecer compatibilidade ao Android 7.1 e versões anteriores (como mostrado
acima).
Ainda que você precise definir a importância/prioridade da notificação, conforme mostrado aqui, 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.
Toda notificação precisa responder a um toque, geralmente para abrir uma atividade no seu app
correspondente à notificação. Para fazer isso, especifique uma intent de conteúdo definida com um
objeto PendingIntent e a transmita para setContentIntent().
O seguinte snippet mostra como criar uma intent básica para abrir uma atividade quando o usuário
toca na notificação:
KotlinJava
// 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, 0)
O método setFlags() mostrado acima ajuda a manter a experiência de navegação esperada pelo
usuário depois dele abrir o app pela notificação, mas o uso desse método depende do tipo de
atividade 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 acima.
Uma atividade que existe no fluxo regular do seu app. Nesse caso, o início da atividade
precisa criar uma pilha de retorno 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, leia Iniciar
uma atividade a partir de uma notificação.
Mostrar a notificação
KotlinJava
with(NotificationManagerCompat.from(this)) {
// notificationId is a unique int for each notification that you must define
notify(notificationId, builder.build())
}
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 até mesmo responder a uma mensagem de texto. Mas
esses botões de ação não podem duplicar a ação executada quando o usuário toca na notificação.
Para adicionar um botão de ação, transmita uma PendingIntent para o método addAction(). Esse
processo é parecido com configurar a ação de toque padrão da notificação, exceto que, em vez de
iniciar uma atividade, você pode fazer várias outras coisas, como iniciar um BroadcastReceiver que
execute um job em segundo plano para a ação não interromper o app que já está aberto.
Por exemplo, o seguinte código mostra como enviar uma transmissão a um receptor específico:
KotlinJava
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)
Se você estiver tentando criar uma notificação com os botões de reprodução de mídia (por exemplo,
pausar e pular faixas), veja como criar uma notificação com controles de mídia.
Observação: no Android 10 (API de nível 29) e versões mais recentes, a plataforma gera botões de
ação de notificação de forma automática quando um app não faz isso. Se você não quiser que as
notificações do seu app mostrem respostas ou ações sugeridas, desative as respostas e ações
geradas pelo sistema usando setAllowGeneratedReplies() e
setAllowSystemGeneratedContextualActions().
Adicionar uma ação de resposta direta
A ação de "Resposta direta", introduzida no Android 7.0 (API de nível 24), permite aos usuários
inserir texto diretamente na notificação, que é entregue 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 um 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 seu app.
1. Crie uma instância de RemoteInput.Builder que possa ser adicionada à ação de notificação. O
construtor dessa classe aceita uma string, usada pelo sistema como chave da entrada de
texto. Mais tarde, o app para dispositivos portáteis usará essa chave para recuperar o texto da
entrada.
KotlinJava
// 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 ()
}
Cuidado: se você reutilizar uma PendingIntent, um usuário poderá responder a uma conversa
diferente daquela que imaginava. Forneça um código de solicitação que seja diferente para cada
conversa ou uma intent que não retorne true quando você chama equals() na intent de resposta de
qualquer outra conversa. O ID da conversa é, com frequência, transmitido como parte do pacote
extra da intent, mas é ignorado quando você chama equals().
O sistema solicita que o usuário informe uma resposta quando a ação de notificação é acionada,
conforme mostrado na figura 3.
KotlinJava
private fun getMessageText(intent: Intent): CharSequence? {
return RemoteInput.getResultsFromIntent(intent)?.getCharSequence(KEY_TEXT_REPLY)
}
KotlinJava
// 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()
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ído em determinado momento, use a forma
"determinada" do indicador chamando setProgress(max, progress, false). O primeiro parâmetro é o
valor "completo" (por exemplo, 100), o segundo é a quantidade que está concluída no momento e o
último indica que se trata de uma barra de progresso determinada.
À medida que sua operação prossegue, chame continuamente setProgress(max, progress, false)
com um valor atualizado para progress e emita novamente a notificação.
KotlinJava
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
here that tracks the progress.
// Usually,
this should be 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 one more time to remove the progress bar
builder.setContentText("Download complete")
.setProgress(0, 0, false)
notify(notificationId, builder.build())
}
No término da operação, progress precisa ser igual a max. É possível deixar a barra de progresso
em exibição ou removê-la quando a operação for concluída. Em ambos os casos, lembre-se de
atualizar 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).
Observação: como a barra de progresso exige que seu app atualize a notificação de forma
contínua, esse código normalmente é executado em um serviço em segundo plano.
Para exibir uma barra de progresso indeterminada (uma barra que não indique a porcentagem
concluída), chame setProgress(0, 0, true). O resultado é um indicador com o mesmo estilo que a
barra de progresso acima, com a diferença de que a animação dele é contínua e não indica o
término. 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.
O Android usa algumas categorias predefinidas do sistema para determinar se o usuário receberá
uma notificação específica quando ele ativar o modo Não perturbe.
KotlinJava
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)
Essas informações sobre a categoria da notificação são usadas pelo sistema para tomar decisões
sobre a exibição da notificação quando o dispositivo está no modo Não perturbe.
No entanto, você não precisa definir uma categoria para todo o sistema. É necessário fazer isso
apenas se suas notificações corresponderem a uma das categorias definidas em NotificationCompat.
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.
Cuidado: notificações que contêm intents de tela cheia são significativamente invasivas. Portanto, é
importante usar esse tipo de notificação apenas para as mensagens mais urgentes e com limite de
tempo.
Observação: se o app for destinado ao Android 10 (API de nível 29) ou versões mais recentes, será
necessário solicitar a permissão USE_FULL_SCREEN_INTENT no arquivo de manifesto do app
para que o sistema inicie a atividade em tela cheia associada à notificação com limite de tempo.
O snippet de código a seguir demonstra como associar sua notificação a uma intent de tela cheia:
KotlinJava
val fullScreenIntent = Intent(this, ImportantActivity::class.java)
val fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT)
Para controlar o nível visível de detalhes da notificação na tela de bloqueio, chame setVisibility() e
especifique um dos seguintes valores:
No entanto, 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 seu app.
Cuidado: o Android aplica uma limitação de taxa ao atualizar uma notificação. Se você postar
atualizações para uma notificação com muita frequência (várias em menos de um segundo), o
sistema poderá ignorar algumas delas.
Remover uma notificação
Use as práticas recomendadas listadas aqui como uma referência rápida ao criar notificações para
seus apps de mensagens e bate-papo.
Usar MessagingStyle
A partir do Android 7.0 (API de nível 24), o Android fornece um modelo de estilo de notificação
especificamente para o conteúdo de mensagens. Ao usar 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.
KotlinJava
var notification = NotificationCompat.Builder(this, CHANNEL_ID)
.setStyle(NotificationCompat.MessagingStyle("Me")
.setConversationTitle("Team lunch")
.addMessage("Hi", timestamp1, null) // Pass in null for user.
.addMessage("What's up?", timestamp2, "Coworker")
.addMessage("Not much", timestamp3, null)
.addMessage("How about lunch?", timestamp4, "Coworker"))
.build()
A partir do Android 8.0 (API de nível 26), as notificações que usam a classe
NotificationCompat.MessagingStyle exibem mais conteúdo na forma recolhida. Você também pode
usar o método addHistoricMessage() para fornecer contexto a uma conversa, adicionando
mensagens históricas às notificações relacionadas a mensagens.
Ao usar NotificationCompat.MessagingStyle:
O recurso "Resposta direta" permite que um usuário responda in-line a uma mensagem.
Depois que um usuário responder com uma 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 um usuário envie várias
respostas a partir 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 método addHistoricMessage() para fornecer contexto a uma conversa de "Resposta
direta", adicionando mensagens históricas à notificação.