Notificações

Uma notificação é uma mensagem que pode ser exibida ao usuário fora da IU normal do aplicativo. Quando você diz ao sistema para emitir uma notificação, ela primeiro aparece como um ícone na área de notificação. Para ver os detalhes da notificação, o usuário abre a gaveta de notificação. A área de notificação e a gaveta de notificação são áreas controladas pelo sistema que o usuário pode visualizar a qualquer momento.

Figura 1. Notificações na área de notificação.

Figura 2. Notificações na gaveta de notificação.

Observação: exceto quando notado, este guia menciona a classe NotificationCompat.Builder na versão 4 da Biblioteca de suporte. A classe Notification.Builder foi adicionada no Android 3.0 (API de nível 11).

Considerações de projeto

As notificações, como parte importante da interface do usuário do Android, possuem as próprias diretrizes de projeto. As alterações do Material Design introduzidas no Android 5.0 (API de nível 21) são de importância específica e, por isso, recomenda-se revisar o treinamento do Material Design para obter mais informações. Para saber como projetar notificações e suas interações, leia o guia de projeto Notificações.

Criação de uma notificação

Você especifica as ações e informações da IU para uma notificação no objeto NotificationCompat.Builder. Para criar a própria notificação, chama-se NotificationCompat.Builder.build(), que retorna um objeto Notification contendo suas especificações. Para emitir a notificação, passa-se o objeto Notification ao sistema chamando NotificationManager.notify().

Conteúdo necessário da notificação

Um objeto Notification deve conter o seguinte:

• Um ícone pequeno, definido por setSmallIcon()
• Um título, definido por setContentTitle()
• Texto de detalhes, definido por setContentText()

Configurações e conteúdo opcionais da notificação

Todas as outras configurações e o conteúdo da notificação são opcionais. Para saber mais sobre isso, consulte as documentações de referência de NotificationCompat.Builder.

Ações da notificação

Apesar de serem opcionais, deve-se adicionar pelo menos uma ação à notificação. Uma ação permite que os usuários direcionem-se diretamente da notificação para uma Activity no aplicativo, onde podem visualizar um ou mais eventos ou realizar outros trabalhos.

Uma notificação pode fornecer várias ações. Deve-se sempre definir a ação que será ativada quando o usuário clicar na notificação. Geralmente, esta ação abre uma Activity no aplicativo. É possível também adicionar botões à notificação que realizem ações adicionais, como ativar a soneca de um alarme imediatamente para uma mensagem de texto. Este recurso está disponível a partir do Android 4.1. Se você usar botões de ação adicionais, também deverá disponibilizar a funcionalidade em uma Activity no aplicativo; consulte a seção Tratamento da compatibilidade para obter mais informações.

Dentro de uma Notification, a própria ação é definida por uma PendingIntent contendo uma Intent que inicia uma Activity no aplicativo. Para associar a PendingIntent a um gesto, chame o método adequado de NotificationCompat.Builder. Por exemplo, se quiser iniciar Activity quando o usuário clicar no texto da notificação na gaveta de notificação, deve-se adicionar PendingIntent chamando setContentIntent().

Iniciar uma Activity quando o usuário clica na notificação é o cenário de ação mais comum. É possível também iniciar uma Activity quando o usuário dispensa uma notificação. A partir do Android 4.1, é possível iniciar uma Activity a partir de um botão de ação. Para obter mais informações, leia o guia de referência de NotificationCompat.Builder.

Prioridade da notificação

Se quiser, é possível definir a prioridade de uma notificação. A prioridade age como uma sugestão à IU do dispositivo sobre como a notificação deve ser exibida. Para definir a prioridade de uma notificação, chame NotificationCompat.Builder.setPriority() e passe em uma das constantes de prioridade NotificationCompat. Há cinco níveis de prioridade, de PRIORITY_MIN (-2) a PRIORITY_MAX (2); se não for definida, a prioridade segue o padrão de PRIORITY_DEFAULT (0).

Para obter mais informações sobre como definir um nível de prioridade adequado, Consulte "Definição e gerenciamento corretos da prioridade das notificações" no guia de projeto Notificações.

Criação de uma notificação simples

O seguinte fragmento ilustra uma notificação simples que especifica uma atividade para abrir quando o usuário clica na notificação. Observe que o código cria um objeto TaskStackBuilder e usa-o para criar a PendingIntent para a ação. Este padrão é explicado com mais detalhes na seção Preservação da navegação ao iniciar uma atividade:

NotificationCompat.Builder mBuilder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!");
// Creates an explicit intent for an Activity in your app
Intent resultIntent = new Intent(this, ResultActivity.class);

// The stack builder object will contain an artificial back stack for the
// started Activity.
// This ensures that navigating backward from the Activity leads out of
// your application to the Home screen.
TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
// Adds the back stack for the Intent (but not the Intent itself)
stackBuilder.addParentStack(ResultActivity.class);
// Adds the Intent that starts the Activity to the top of the stack
stackBuilder.addNextIntent(resultIntent);
PendingIntent resultPendingIntent =
        stackBuilder.getPendingIntent(
            0,
            PendingIntent.FLAG_UPDATE_CURRENT
        );
mBuilder.setContentIntent(resultPendingIntent);
NotificationManager mNotificationManager =
    (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// mId allows you to update the notification later on.
mNotificationManager.notify(mId, mBuilder.build());

É isso. O usuário foi notificado.

Aplicação de um layout expandido a uma notificação

Para que uma notificação apareça em uma vista expandida, cria-se primeiro um objeto NotificationCompat.Builder com as opções de visualização normal desejadas. Em seguida, chama-se Builder.setStyle() com um objeto de layout expandido como o argumento.

Lembre-se de que as notificações expandidas não estão disponíveis em plataformas anteriores ao Android 4.1. Para saber mais sobre como tratar de notificações para Android 4.1 e plataformas anteriores, leia a seção Tratamento da compatibilidade.

Por exemplo, o seguinte fragmento de código demonstra como alterar a notificação criada no fragmento anterior para usar o layout expandido:

NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
    .setSmallIcon(R.drawable.notification_icon)
    .setContentTitle("Event tracker")
    .setContentText("Events received")
NotificationCompat.InboxStyle inboxStyle =
        new NotificationCompat.InboxStyle();
String[] events = new String[6];
// Sets a title for the Inbox in expanded layout
inboxStyle.setBigContentTitle("Event tracker details:");
...
// Moves events into the expanded layout
for (int i=0; i < events.length; i++) {

    inboxStyle.addLine(events[i]);
}
// Moves the expanded layout object into the notification object.
mBuilder.setStyle(inBoxStyle);
...
// Issue the notification here.

Tratamento da compatibilidade

Nem todos os recursos de notificação estão disponíveis para uma versão específica, mesmo se os métodos que os definem estiverem na classe NotificationCompat.Builder da biblioteca de suporte. Por exemplo, botões de ação, que dependem das notificações expandidas, aparecem somente a partir do Android 4.1 ou de posteriores porque as próprias notificações expandidas estão disponíveis somente a partir destas versões.

Para garantir a melhor compatibilidade, crie notificações com NotificationCompat e suas subclasses, particularmente NotificationCompat.Builder. Além disso, siga o processo a seguir ao implementar uma notificação:

1. Forneça toda a funcionalidade da notificação aos usuários, independentemente da versão que estejam usando. Para fazer isto, verifique se toda a disponibilidade está disponível a partir de uma Activity no aplicativo. Pode-se adicionar uma nova Activity para fazer isto.

   Por exemplo, caso queira usar addAction() para fornecer um controle que interrompa e inicie a reprodução de mídia, primeiro implemente este controle em uma Activity no aplicativo.

2. Certifique-se de que todos os usuários possam acessar a funcionalidade na Activity, iniciando-a quando o usuário clicar na notificação. Para fazer isto, crie uma PendingIntent para aActivity. Chame setContentIntent() para adicionar a PendingIntent à notificação.
3. Agora, adicione os recursos de notificação expandidos que deseja usar à notificação. Lembre-se de que qualquer funcionalidade adicionada também deve estar disponível na Activity que é iniciada quando os usuários clicam na notificação.

Gerenciamento de notificações

Quando for necessário emitir uma notificação várias vezes para o mesmo tipo de evento, deve-se evitar criar uma notificação completamente nova. Em vez disso, deve-se considerar atualizar uma notificação anterior, alterando e/ou adicionado alguns valores.

Por exemplo, o Gmail notifica o usuário de que novos e-mails foram recebidos aumentando a contagem de mensagens não lidas e adicionando um resumo de cada e-mail à notificação. Isto é chamado de "acumular" a notificação. Isto é descrito com mais detalhes no guia de projeto Notificações.

Observação: este recurso do Gmail requer o layout expandido da "caixa de entrada", que faz parte do recurso de notificação expandida disponível a partir do Android 4.1.

A seguinte seção descreve como atualizar as notificações e como removê-las.

Atualização de notificações

Para definir uma notificação para que possa ser atualizada, deve-se emiti-la com um ID de notificação chamando NotificationManager.notify(). Para atualizar esta notificação após emiti-la, atualize ou crie um objeto NotificationCompat.Builder, compile um objeto Notification a partir dele e emita a Notification com o mesmo ID usado anteriormente. Se a notificação anterior ainda estiver visível, o sistema a atualizará com o conteúdo do objeto Notification. Se a notificação anterior for dispensada, uma nova notificação será criada.

O seguinte fragmento demonstra uma notificação que é atualizada para refletir o número de eventos que ocorreram. Ele acumula a notificação, exibindo um resumo:

mNotificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// Sets an ID for the notification, so it can be updated
int notifyID = 1;
mNotifyBuilder = new NotificationCompat.Builder(this)
    .setContentTitle("New Message")
    .setContentText("You've received new messages.")
    .setSmallIcon(R.drawable.ic_notify_status)
numMessages = 0;
// Start of a loop that processes data and then notifies the user
...
    mNotifyBuilder.setContentText(currentText)
        .setNumber(++numMessages);
    // Because the ID remains unchanged, the existing notification is
    // updated.
    mNotificationManager.notify(
            notifyID,
            mNotifyBuilder.build());
...

Remoção de notificações

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

• O usuário dispense a notificação individualmente usando "Apagar tudo" (se a notificação puder ser apagada).
• O usuário clique na notificação e chame-se setAutoCancel() quando a notificação é criada.
• Chame-se cancel() para um ID de notificação específico. Este método também exclui notificações contínuas.
• Chame-se cancelAll(), que remove todas as notificações emitidas anteriormente.

Preservação da navegação ao iniciar uma atividade

Ao iniciar uma Activity a partir de uma notificação, deve-se preservar a experiência de navegação esperada pelo usuário. Clicar em Voltar deve levar o usuário de volta pelo fluxo de trabalho normal do aplicativo à tela Inicial, e clicar em Recentes deve exibir a Activity como uma tarefa separada. Para preservar a experiência de navegação, deve-se iniciar a Activity em uma tarefa nova. O modo de definição da PendingIntent para fornecer uma tarefa nova depende da natureza da Activity que está sendo iniciado. Há duas situações gerais:

Atividade comum

Inicia-se uma Activity que faz parte do fluxo de trabalho normal do aplicativo. Nesta situação, defina PendingIntent para iniciar uma tarefa nova e forneça a PendingIntent com uma pilha de retorno que reproduza o comportamento Voltar normal do aplicativo.

As notificações do aplicativo do Gmail demonstram isso. Ao clicar em uma notificação para uma única mensagem de e-mail, a própria mensagem será exibida. Tocar em Voltar faz com que o usuário volte ao Gmail até a tela inicial, como se ele tivesse acessado o Gmail a partir da tela inicial em vez de a partir da notificação.

Isto acontece independentemente do aplicativo que estava em primeiro plano quando a notificação foi tocada. Por exemplo, se você estiver no Gmail escrevendo uma mensagem e clicar em uma notificação de um e-mail, você acessará este e-mail imediatamente. Tocar em Voltar leva você de volta à caixa de entrada e, em seguida, à tela inicial, em vez de levar à mensagem que estava escrevendo.

Atividade especial

O usuário vê apenas esta Activity se for iniciada a partir de uma notificação. De certo modo, a Activity estende a notificação fornecendo informações que seriam difíceis de exibir na própria notificação. Para estas situações, defina a PendingIntent para iniciar em uma tarefa nova. Não há necessidade de criar uma pilha de retorno, pois a Activity iniciada não faz parte do fluxo de atividades do aplicativo. Clicar em Voltar ainda levará o usuário à tela inicial.

Definição de uma atividade PendingIntent comum

Para definir uma PendingIntent que inicia uma Activity de entrada direta, siga estas etapas:

1. Defina a hierarquia de Activity do aplicativo no manifesto.
   1. Adicione compatibilidade com Android 4.0.3 e mais antigos. Para fazer isto, especifique o pai da Activity que está iniciando adicionando um elemento <meta-data> como o filho de <activity>.

      Para este elemento, defina android:name="android.support.PARENT_ACTIVITY". Defina android:value="<parent_activity_name>", onde <parent_activity_name> é o valor de android:name para o elemento <activity> pai. Veja o XML a seguir para ver um exemplo.

   2. Adicione também compatibilidade com Android 4.1 e mais recentes. Para fazer isto, adicione o atributo android:parentActivityName ao elemento <activity> da Activity que estiver iniciando.

   O XML final deve parecer-se com isto:

   <activity
       android:name=".MainActivity"
       android:label="@string/app_name" >
       <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
       </intent-filter>
   </activity>
   <activity
       android:name=".ResultActivity"
       android:parentActivityName=".MainActivity">
       <meta-data
           android:name="android.support.PARENT_ACTIVITY"
           android:value=".MainActivity"/>
   </activity>
   

2. Crie uma pilha de retorno com base na Intent que inicia a Activity:
   1. Crie a Intent para iniciar aActivity.
   2. Crie um compilador de pilhas chamando TaskStackBuilder.create().
   3. Adicione a pilha de retorno ao compilador de pilha chamando addParentStack(). Para cada Activity na hierarquia definida no manifesto, a pilha de retorno conterá um objeto Intent que inicia a Activity. Este método adiciona sinalizadores que iniciam a pilha em uma tarefa nova.

      Observação: Apesar de o argumento de addParentStack() ser uma referência para a Activity iniciada, a chamada do método não adiciona a Intent que inicia a Activity. Em vez disso, lidamos com isto na próxima etapa.

   4. Adicione a Intent que inicia a Activity a partir da notificação chamando addNextIntent(). Passe a Intent criada na primeira etapa como o argumento para addNextIntent().
   5. Se for necessário, adicione argumentos para os objetos Intent na pilha chamando TaskStackBuilder.editIntentAt(). Às vezes, isto é necessário para garantir que a Activity alvo exiba dados significantes quando o usuário navegar a ela usando Voltar.
   6. Adquira uma PendingIntent para esta pilha de retorno chamando getPendingIntent(). É possível usar esta PendingIntent como o argumento para setContentIntent().

O seguinte fragmento de código demonstra o processo:

...
Intent resultIntent = new Intent(this, ResultActivity.class);
TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
// Adds the back stack
stackBuilder.addParentStack(ResultActivity.class);
// Adds the Intent to the top of the stack
stackBuilder.addNextIntent(resultIntent);
// Gets a PendingIntent containing the entire back stack
PendingIntent resultPendingIntent =
        stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT);
...
NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
builder.setContentIntent(resultPendingIntent);
NotificationManager mNotificationManager =
    (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mNotificationManager.notify(id, builder.build());

Definição de uma atividade PendingIntent especial

A seção a seguir descreve como definir uma atividade PendingIntent especial.

Uma Activity especial não precisa de uma pilha de retorno, então não é necessário definir sua hierarquia de Activity no manifesto e chamar addParentStack() para compilar uma pilha de retorno. Em vez disso, use o manifesto para definir as opções de tarefa da Activity e crie a PendingIntent chamando getActivity():

1. No manifesto, adicione os seguintes atributos ao elemento <activity> para a Activity

   android:name="activityclass"

   O nome da classe completamente qualificado da atividade.

   android:taskAffinity=""

   Combinado com o sinalizador FLAG_ACTIVITY_NEW_TASK que foi definido no código, isto garante que esta Activity não acesse a tarefa padrão do aplicativo. Tarefas existentes que tiverem a afinidade padrão do aplicativo não serão afetadas.

   android:excludeFromRecents="true"

   Exclui a nova tarefa de Recentespara que o usuário não navegue acidentalmente de volta.

   Este fragmento mostra o elemento:

   <activity
       android:name=".ResultActivity"
   ...
       android:launchMode="singleTask"
       android:taskAffinity=""
       android:excludeFromRecents="true">
   </activity>
   ...
   

2. Compilar e emitir a notificação:
   1. Crie uma Intent que inicie a Activity.
   2. Defina a Activity para iniciar em uma tarefa nova e vazia chamando setFlags() com os sinalizadores FLAG_ACTIVITY_NEW_TASK e FLAG_ACTIVITY_CLEAR_TASK.
   3. Defina quaisquer outras opções necessárias para a Intent.
   4. Crie uma PendingIntent a partir da Intent chamando getActivity(). É possível usar esta PendingIntent como o argumento para setContentIntent().

   O seguinte fragmento de código demonstra o processo:

   // Instantiate a Builder object.
   NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
   // Creates an Intent for the Activity
   Intent notifyIntent =
           new Intent(this, ResultActivity.class);
   // Sets the Activity to start in a new, empty task
   notifyIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK
                           | Intent.FLAG_ACTIVITY_CLEAR_TASK);
   // Creates the PendingIntent
   PendingIntent notifyPendingIntent =
           PendingIntent.getActivity(
           this,
           0,
           notifyIntent,
           PendingIntent.FLAG_UPDATE_CURRENT
   );
   
   // Puts the PendingIntent into the notification builder
   builder.setContentIntent(notifyPendingIntent);
   // Notifications are issued by sending them to the
   // NotificationManager system service.
   NotificationManager mNotificationManager =
       (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
   // Builds an anonymous Notification object from the builder, and
   // passes it to the NotificationManager
   mNotificationManager.notify(id, builder.build());
   

Exibição do progresso em uma notificação

As notificações podem incluir um indicador de progresso animado que exibe aos usuários o status de uma operação em andamento. Se for possível estimar a duração da operação e o quanto dela já foi concluído em um determinado momento, use a forma "determinada" do indicador (uma barra de progresso). Se não for possível estimar a duração da operação, use a forma "indeterminada" do indicador (um indicador de atividade).

Os indicadores de progresso são exibidos com a implementação da plataforma da classe ProgressBar.

Para usar o indicador de progresso em plataformas a partir do Android 4.0, chame setProgress(). Para versões mais antigas, deve-se criar o próprio layout personalizado de notificação que inclua uma vista de ProgressBar.

As seguintes seções descrevem como exibir o progresso em uma notificação usando setProgress().

Exibição de um indicador de progresso de duração fixa

Para exibir uma determinada barra de progresso, adicione a barra à notificação chamando setProgress(max, progress, false) e, em seguida, emitindo a notificação. À medida que a operação prosseguir, incremente progress e atualize a notificação. No término da operação, progress deve ser igual a max. Uma maneira comum de chamar setProgress() é definir max como 100 e, em seguida, incrementar progress como um valor "percentual completo" para a operação.

É 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 exibir que a operação foi concluída. Para remover a barra de progresso, chame setProgress(0, 0, false). Por exemplo:

...
mNotifyManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mBuilder = new NotificationCompat.Builder(this);
mBuilder.setContentTitle("Picture Download")
    .setContentText("Download in progress")
    .setSmallIcon(R.drawable.ic_notification);
// Start a lengthy operation in a background thread
new Thread(
    new Runnable() {
        @Override
        public void run() {
            int incr;
            // Do the "lengthy" operation 20 times
            for (incr = 0; incr <= 100; incr+=5) {
                    // Sets the progress indicator to a max value, the
                    // current completion percentage, and "determinate"
                    // state
                    mBuilder.setProgress(100, incr, false);
                    // Displays the progress bar for the first time.
                    mNotifyManager.notify(0, mBuilder.build());
                        // Sleeps the thread, simulating an operation
                        // that takes time
                        try {
                            // Sleep for 5 seconds
                            Thread.sleep(5*1000);
                        } catch (InterruptedException e) {
                            Log.d(TAG, "sleep failure");
                        }
            }
            // When the loop is finished, updates the notification
            mBuilder.setContentText("Download complete")
            // Removes the progress bar
                    .setProgress(0,0,false);
            mNotifyManager.notify(ID, mBuilder.build());
        }
    }
// Starts the thread by calling the run() method in its Runnable
).start();

Exibição de um indicador de atividade contínua

Para exibir um indicador de atividade indeterminado, adicione-o à notificação com setProgress(0, 0, true) (os dois primeiros argumentos são ignorados) e emita a notificação. O resultado é um indicador que tem o mesmo estilo que uma barra de progresso, exceto que sua animação é contínua.

Emita a notificação no início da operação. A animação será executada até que a notificação seja modificada. Quando a operação for concluída, chame setProgress(0, 0, false) e, em seguida, atualize a notificação para remover o indicador de atividade. Sempre faça isso. Caso contrário, a animação será executada mesmo quando a operação for concluída. Lembre-se também de alterar o texto da notificação para indicar que a operação foi concluída.

Para ver como os indicadores de atividade funcionam, consulte o fragmento anterior. Localize as seguintes linhas:

// Sets the progress indicator to a max value, the current completion
// percentage, and "determinate" state
mBuilder.setProgress(100, incr, false);
// Issues the notification
mNotifyManager.notify(0, mBuilder.build());

Substitua as linhas encontradas pelas seguintes linhas:

 // Sets an activity indicator for an operation of indeterminate length
mBuilder.setProgress(0, 0, true);
// Issues the notification
mNotifyManager.notify(0, mBuilder.build());

Metadados de notificação

As notificações podem ser classificadas de acordo com os metadados atribuídos com os seguintes métodos NotificationCompat.Builder:

• setCategory() diz ao sistema como lidar com as notificações do aplicativo quando o dispositivo estiver no modo de Prioridade (por exemplo: se a notificação representar uma chamada recebida, mensagem instantânea ou alarme).
• setPriority() faz com que as notificações com o campo de prioridade definido para PRIORITY_MAX ou PRIORITY_HIGH apareçam em uma pequena janela flutuante se a notificação também tiver som ou vibração.
• addPerson() permite a adição de uma lista de pessoas a uma notificação. O aplicativo pode usar isto para sinalizar ao sistema que ele deve agrupar as notificações de pessoas específicas, ou classificar notificações destas pessoas como sendo mais importantes.

Notificação de informações prévias

Com o Android 5.0 (API de nível 21), as notificações podem aparecer em uma pequena janela flutuante (também chamada de notificação de informações prévias) quando o dispositivo estiver ativo (ou seja, com o dispositivo desbloqueado e a tela ativada). Essas notificações aparecem de maneira semelhante à forma compacta da notificação, exceto que a notificação de informações prévias também exibe botões de ação. Os usuários podem agir ou dispensar a notificação de informações prévias sem deixar o aplicativo atual.

Exemplos de condições que podem ativar uma notificação de informações prévias incluem:

• A atividade do usuário estar no modo de tela cheia (o aplicativo usar fullScreenIntent) ou
• A notificação tem alta prioridade e usa toques ou vibrações

Notificações da tela de bloqueio

Com o lançamento do Android 5.0 (API de nível 21), as notificações podem aparecer na tela de bloqueio. O aplicativo pode usar esta funcionalidade para fornecer controles de reprodução de mídia e outras ações comuns. Os usuários podem escolher, acessando Configurações, se querem exibir notificações na tela de bloqueio e é possível designar se uma notificação do aplicativo será visível na tela de bloqueio.

Configuração de visibilidade

O aplicativo pode controlar o nível de detalhe visível nas notificações exibidas em uma tela de bloqueio segura. Chama-se setVisibility() e especifica-se um dos seguintes valores:

• VISIBILITY_PUBLIC exibe o conteúdo completo da notificação.
• VISIBILITY_SECRET não exibe parte alguma desta notificação na tela de bloqueio.
• VISIBILITY_PRIVATE exibe informações básicas, como o ícone e o título do conteúdo da notificação, mas oculta o conteúdo completo.

Quando VISIBILITY_PRIVATE é definido, é possível fornecer também uma versão alternativa do conteúdo da notificação que oculta determinados detalhes. Por exemplo, um aplicativo de SMS pode exibir uma notificação que exiba Você tem 3 novas mensagens de texto, mas oculte o conteúdo e o remetente das mensagens. Para fornecer esta notificação alternativa, cria-se primeiro uma notificação de substituição usando NotificationCompat.Builder. Ao criar o objeto de notificação privada, anexe a notificação de substituição a ele usando o método setPublicVersion() .

Controle de reprodução de mídia na tela de bloqueio

No Android 5.0 (API de nível 21), a tela de bloqueio deixa de exibir controles de mídia com base em RemoteControlClient, que foi reprovado. Em vez disso, usa-se o modelo Notification.MediaStyle com o método addAction(), que converte as ações em ícones clicáveis.

Observação: o modelo e o método addAction() não estão incluídos na biblioteca de suporte. Portanto, esses recursos funcionam somente no Android 5.0 e em versões mais recentes.

Para exibir os controles de reprodução de mídia na tela de bloqueio no Android 5.0, defina a visibilidade como VISIBILITY_PUBLIC, como descrito acima. Em seguida, adicione as ações e defina o modelo Notification.MediaStyle, como descrito no seguinte exemplo de código:

Notification notification = new Notification.Builder(context)
    // Show controls on lock screen even when user hides sensitive content.
    .setVisibility(Notification.VISIBILITY_PUBLIC)
    .setSmallIcon(R.drawable.ic_stat_player)
    // Add media control buttons that invoke intents in your media service
    .addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0
    .addAction(R.drawable.ic_pause, "Pause", pausePendingIntent)  // #1
    .addAction(R.drawable.ic_next, "Next", nextPendingIntent)     // #2
    // Apply the media style template
    .setStyle(new Notification.MediaStyle()
    .setShowActionsInCompactView(1 /* #1: pause button */)
    .setMediaSession(mMediaSession.getSessionToken())
    .setContentTitle("Wonderful music")
    .setContentText("My Awesome Band")
    .setLargeIcon(albumArtBitmap)
    .build();

Observação: a reprovação de RemoteControlClient tem mais implicações para o controle de mídia. Consulte Controle de reprodução de mídia para obter mais informações sobre as novas APIs para gerenciar a sessão de mídia e o controle de reprodução.

Layouts de notificação personalizados

A estrutura das notificações permite que um layout de notificação personalizado seja definido, o que define a aparência da notificação em um objeto RemoteViews. As notificações de layout personalizado são parecidas com notificações normais, mas baseiam-se em um RemoteViews definido em um arquivo de layout XML.

A altura disponível para um layout de notificação personalizado depende da vista da notificação. Layouts de vista normal são limitados a 64 dp, e layouts de vista expandida são limitados a 256 dp.

Para definir um layout de notificação personalizada, comece instanciando um objeto RemoteViews que infle um arquivo de layout XML. Em seguida, em vez de chamar métodos como setContentTitle(), chame setContent(). Para definir os detalhes do conteúdo na notificação personalizada, use os métodos em RemoteViews para definir os valores dos filhos da vista:

1. Crie um layout XML para a notificação em um arquivo separado. É possível usar o nome de arquivo que desejar, mas deve-se usar a extensão .xml
2. No aplicativo, use métodos RemoteViews para definir os ícones e o texto da notificação. Coloque este objeto RemoteViews em NotificationCompat.Builder chamando setContent(). Evite definir um Drawable de segundo plano no objeto RemoteViews, pois a cor do texto pode torná-lo ilegível.

A classe RemoteViews também inclui métodos que podem ser usados para adicionar facilmente um Chronometer ou uma ProgressBar ao layout da notificação. Para obter mais informações sobre como criar layouts personalizados para a notificação, consulte a documentação de referência de RemoteViews.

Atenção: ao usar um layout personalizado de notificação, certifique-se de garantir que ele funcione com diferentes orientações e resoluções do dispositivo. Enquanto este aviso aplica-se a todos os layouts de vistas, é muito importante para as notificações, pois o espaço na gaveta da notificação é muito restrito. Não torne o layout personalizado muito complexo e certifique-se de testá-lo em várias configurações.

Uso de recursos de estilo para texto de notificação personalizada

Sempre use recursos de estilo para o texto de uma notificação personalizada A cor de fundo da notificação pode variar dentre vários dispositivos e versões e o uso de recursos de estilo ajuda a lidar com isto. A partir do Android 2.3, o sistema definiu um estilo para o texto do layout de notificação padrão. Se usar o mesmo estilo nos aplicativos que usam Android 2.3 ou mais recentes, você garantirá que o texto esteja visível em relação ao fundo da exibição.