preview/features/notification-updates.jd

page.title=Notificaes
page.tags=notificaes
helpoutsWidget=true
page.image=/preview/images/notifications-card.png

trainingnavtop=true

@jd:body

<div id="qv-wrapper">
<div id="qv">

<!-- table of contents -->
<h2>Este documento inclui</h2>
<ol>
  <li><a href="#direct">Resposta direta</a></li>
  <li><a href="#bundle">Notificaes empacotadas</a></li>
  <li><a href="#custom">Visualizaes personalizadas</a></li>
  <li><a href="#style">Estilo de mensagem</a></li>
</ol>

</div>
</div>

<p>O Android N introduz diversas APIs novas que permitem que aplicativos publiquem
 notificaes altamente visveis e interativas.</p>

<p>O Android N estende a API de notificao {@link android.support.v4.app.RemoteInput}
 atual para permitir respostas em linha em celulares. Esse recurso permite que os usurios
 respondam rapidamente na aba de notificaes sem acessar o aplicativo.</p>

<p>
  O Android N permite empacotar notificaes semelhantes para
 exibio como nica notificao. Para que isso seja possvel, o Android N usa o mtodo {@link
  android.support.v4.app.NotificationCompat.Builder#setGroup
  NotificationCompat.Builder.setGroup()} existente. Os usurios podem expandir todas as
 notificaes, executando aes como responder e descartar em cada uma
 delas individualmente na aba de notificaes.
</p>

<p>Por fim, o Android N tambm adiciona vrias APIs que permitem usar decoraes
 do sistema nas visualizaes de notificao personalizadas do aplicativo. Essas APIs ajudam
 a garantir que as visualizaes de notificao compartilhem uma apresentao consistente com os
 modelos padro.</p>

<p>Este documento destaca algumas principais mudanas que voc deve considerar
 ao usar os novos recursos de notificao em aplicativos.</p>

<h2 id="direct">Resposta direta</h2>

<p>Com o recurso de resposta direta no Android N, os usurios podem responder
 rapidamente a mensagens de texto ou atualizar listas de tarefas diretamente na interface de
 notificao. Em um dispositivo porttil, a ao de resposta em linha aparece como boto adicional
 anexado  notificao. Quando um usurio responde pelo teclado, o sistema anexa
 a resposta de texto  inteno especificada como ao de notificao e envia a inteno ao aplicativo no dispositivo.


<img id="fig-reply-button" src="{@docRoot}preview/images/inline-reply.png" srcset="{@docRoot}preview/images/inline-reply.png 1x,
  {@docRoot}preview/images/inline-reply_2x.png 2x" width="400">
<p class="img-caption">
  <strong>Figura 1.</strong>O Android N adiciona o boto de ao <strong>Reply</strong>
.
</p>

<h3>Adio de aes de resposta em linha</h3>

<p>Para criar uma ao de notificao com suporte  resposta direta:
</p>

<ol>
<li>Crie uma instncia de {@link android.support.v4.app.RemoteInput.Builder}
 que possa ser adicionada  ao de
 notificao. O construtor dessa classe aceita uma string, usada pelo sistema como chave
 da entrada de texto. Posteriormente, o aplicativo no dispositivo usar essa chave para recuperar o texto
 da entrada.

<pre>
// 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();
</pre>
</li>
<li>Anexe o objeto {@link android.support.v4.app.RemoteInput}
 a uma ao usando <code>addRemoteInput()</code>.

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

<li>Aplique a ao a uma notificao e emita a notificao.

<pre>
// Build the notification and add the action.
Notification newMessageNotification =
        new Notification.Builder(mContext)
                .setSmallIcon(R.drawable.ic_message)
                .setContentTitle(getString(R.string.title))
                .setContentText(getString(R.string.content))
                .addAction(action))
                .build();

// Issue the notification.
NotificationManager notificationManager =
        NotificationManager.from(mContext);
notificationManager.notify(notificationId, newMessageNotification);

</pre>
</li>

</ol>


<p> O sistema solicita que o usurio informe uma resposta quando acionar a
 ao de notificao. </p>

<img id="fig-user-input" src="{@docRoot}preview/images/inline-type-reply.png" srcset="{@docRoot}preview/images/inline-type-reply.png 1x,
    {@docRoot}preview/images/inline-type-reply_2x.png 2x" width="300">
<p class="img-caption">
  <strong>Figura 2.</strong> O usurio insere texto na aba de notificaes.
</p>

<h3>
  Recuperao da entrada do usurio na resposta em linha
</h3>

<p>
  Para receber a entrada do usurio da interface de notificao para a atividade
 declarada na inteno de ao de resposta:
</p>

<ol>
  <li>Chame {@link android.support.v4.app.RemoteInput#getResultsFromIntent
 getResultsFromIntent()} passando a inteno da ao de notificao como
 parmetro de entrada. Esse mtodo retorna um {@link android.os.Bundle} que
 contm a resposta de texto.

    <pre>
Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
</pre>
  </li>

  <li>Consulte a resposta usando a chave de resultado (fornecida ao construtor {@link
 android.support.v4.app.RemoteInput.Builder}). Voc pode concluir
 este processo e recuperar o texto de entrada criando um mtodo, como no
 snippet de cdigo a seguir:

    <pre>
// Obtain the intent that started this activity by calling
// Activity.getIntent() and pass it into this method to
// get the associated string.

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

  <li>Crie e emita outra notificao usando o mesmo cdigo que
 voc forneceu para a notificao anterior. O indicador de progresso
 desaparece da interface de notificao para informar os usurios que houve uma resposta
 bem-sucedida. Ao trabalhar com esta nova notificao, use o contexto que  passado
 ao mtodo {@code onReceive()} do receptor.

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

// Issue the new notification.
NotificationManager notificationManager =
        NotificationManager.from(context);
notificationManager.notify(notificationId, repliedNotification);
</pre>
  </li>
</ol>

<p>
  Para aplicativos interativos, como bate-papos, pode ser til incluir contexto
 adicional ao lidar com texto recebido. Por exemplo, estes aplicativos podem exibir
 vrias linhas de histrico de bate-papo. Quando o usurio responde por {@link
 android.support.v4.app.RemoteInput}, voc pode atualizar o histrico de respostas
 usando o mtodo {@code setRemoteInputHistory()}.
</p>

<p>
  A notificao precisar ser atualizada ou cancelada depois que o aplicativo tiver
 recebido a entrada remota. Quando o usurio responde a uma atualizao remota
 usando uma Resposta direta,
 no cancele a notificao. Em vez disso, atualize a notificao para exibir a resposta do usurio.
Para notificaes que usam {@code MessagingStyle}, adicione
 a resposta como ltima mensagem. Ao usar outros modelos, voc pode
anexar a resposta do usurio ao histrico da entrada remota.
</p>

<h2 id="bundle">Notificaes empacotadas</h2>

<p>O Android N oferece aos desenvolvedores uma nova forma de representar
 uma fila de notificaes: <i>notificaes empacotadas</i>. Essa forma  semelhante ao recurso
  <a href="{@docRoot}training/wearables/notifications/stacks.html">Pilhas
 de Notificaes</a> no Android Wear. Por exemplo, se o aplicativo criar notificaes
 para mensagens recebidas, quando mais de uma mensagem for recebida, empacote as
 notificaes como um nico grupo. Voc pode
 usar o mtodo existente {@link android.support.v4.app.NotificationCompat.Builder#setGroup
Builder.setGroup()} para empacotar notificaes semelhantes.</p>

<p>
  Um grupo de notificaes impe uma hierarquia nas notificaes que o compe.
  Na parte superior dessa hierarquia, est a notificao pai, que exibe informaes
 resumidas para o grupo. O usurio pode expandir
 progressivamente o grupo de notificaes e o sistema mostra mais informaes  medida que o
 usurio aumenta o detalhamento. Quando o usurio expande o pacote, o sistema revela
 mais informaes para todas as notificaes filhas. Quando o usurio
 expande uma das notificaes, o sistema revela todo o seu contedo.
</p>

<img id="fig-bundles" src="{@docRoot}preview/images/bundles.png" srcset="{@docRoot}preview/images/bundles.png 1x,
          {@docRoot}preview/images/bundles_2x.png 2x" width="300">
<p class="img-caption">
  <strong>Figura 3.</strong> O usurio pode expandir progressivamente o grupo
 de notificaes.
</p>

<p class="note">
  <strong>Observao:</strong> Se o mesmo aplicativo enviar quatro ou mais notificaes
 e no especificar um agrupamento, o
 sistema as agrupar automaticamente.
</p>

<p>Para saber como adicionar notificaes a um grupo, consulte
<a href="{@docRoot}training/wearables/notifications/stacks.html#AddGroup">Adicionar
cada notificao a um grupo</a>.</p>


<h3 id="best-practices">Prticas recomendadas para notificaes empacotadas</h3>
<p>Esta seo oferece diretrizes sobre quando usar grupos de notificaes em vez
 de notificaes {@link android.app.Notification.InboxStyle InboxStyle}
 que foram disponibilizadas em verses anteriores da
 plataforma Android.</p>

<h3>Quando usar notificaes empacotadas</h3>

<p>Voc deve usar grupos de notificaes apenas quando todas as condies a seguir forem
 verdadeiras para o seu caso de uso:</p>

<ul>
  <li>As notificaes filhas so notificaes completas e podem ser exibidas
 individualmente sem necessidade de um resumo do grupo.</li>
  <li>A exibio individual de notificaes filhas pode ser vantajosa. Por
 exemplo:
  </li>
  <ul>
    <li>Elas so acionveis, sem aes especficas para cada filha.</li>
    <li>H mais informaes na filha que as que o usurio quer ler.</li>
  </ul>
</ul>

<p>Os exemplos de bons casos de uso para grupos de notificaes incluem: um aplicativo de mensagens
 exibindo uma lista de mensagens recebidas ou um aplicativo de e-mail exibindo uma lista de
 e-mails recebidos.</p>

<p>
Os exemplos de casos em que uma nica notificao  prefervel
 incluem mensagens individuais de uma nica pessoa ou uma representao em lista
 de itens de texto com uma nica linha. Voc pode usar
({@link android.app.Notification.InboxStyle InboxStyle} ou
 {@link android.app.Notification.BigTextStyle BigTextStyle}) para
 isso.
</p>

<h3 id ="post">Exibio de notificaes empacotadas</h3>

<p>
  O aplicativo deve sempre publicar um resumo do grupo, mesmo se o grupo tiver apenas uma
 nica filha. O sistema suprimir o resumo e exibir diretamente a
 notificao filha se ela contiver apenas uma nica notificao. Isso garante
 que o sistema possa oferecer uma experincia consistente quando o usurio deslizar por
 filhas de um grupo.
</p>

<p class="note">
  <strong>Observao:</strong> esta verso do Android N ainda no
 elimina o resumo de grupos de notificaes contendo uma nica filha. Essa
 funcionalidade ser adicionada em uma verso posterior do Android N.
</p>

<h3>Observao de notificaes</h3>

<p>Embora o sistema normalmente exiba notificaes filhas como grupo, voc pode
 configur-las para exibio temporria como
 <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#Heads-up">
 notificaes heads-up</a>. Esse recurso  particularmente til porque permite
 acesso imediato  filha mais recente e a suas aes associadas.
</p>


<h3>Compatibilidade com verses anteriores</h3>

<p>
  Os grupos de notificaes e as entradas remotas fazem parte da API {@link
  android.app.Notification} desde o Android 5.0 (nvel da API 21) para oferecer suporte a
 dispositivos Android Wear. Se voc j criou notificaes com essas APIs,
 a nica ao necessria  verificar se o comportamento do aplicativo corresponde
 s diretrizes descritas acima e considerar a implementao de {@code
  setRemoteInputHistory()}.
</p>

<p>
  Para compatibilidade com verses anteriores, as mesmas APIs esto disponveis com
 a classe {@link android.support.v4.app.NotificationCompat} da biblioteca de suporte,
 permitindo criar notificaes que funcionem em verses anteriores do
 Android. Em celulares e tablets, os usurios somente visualizam as notificaes resumidas.
 Portanto, um aplicativo deve ter uma notificao no estilo de caixa de entrada ou equivalente,
 representativa de todo o contedo de informaes do grupo. Como os dispositivos Android
 Wear permitem que os usurios vejam todas as notificaes filhas, mesmo em nveis
 de plataforma antigos, voc deve criar notificaes filhas independentemente do nvel
 da API.
</p>

<h2 id="custom"> Visualizaes personalizadas</h2>
<p>Comeando com o Android N,  possvel personalizar visualizaes de notificao e
 continuar obtendo decoraes de sistema, como cabealhos de notificao, aes e layouts
 expansveis.</p>

<p>Para ativar esses recursos, o Android N adiciona as seguintes APIs para aplicar estilo
 visualizao personalizada:</p>

<dl>
<dt>
{@code DecoratedCustomViewStyle()}</dt>
<dd> Aplica estilo a notificaes que no sejam notificaes
 de mdia.</dd>
<dt>
{@code DecoratedMediaCustomViewStyle()}</dt>
<dd> Aplica estilo a notificaes de mdia.</dd>
</dl>

<p>Para usar essa nova API, chame o mtodo {@code setStyle()}, passando o
 estilo de visualizao personalizada desejado.</p>

<p>O snippet mostra como construir um objeto de notificao personalizada com o mtodo
{@code DecoratedCustomViewStyle()}.</p>

<pre>
Notification notification = new Notification.Builder()
           .setSmallIcon(R.drawable.ic_stat_player)
           .setLargeIcon(albumArtBitmap))
           .setCustomContentView(contentView);
           .setStyle(new Notification.DecoratedCustomViewStyle())
           .build();

</pre>

<h2 id="style">Estilo de mensagens</h2>
<p>
  O Android N traz uma nova API para personalizao do estilo de uma notificao.
  Usando a classe <code>MessageStyle</code>, voc pode alterar vrios
rtulos exibidos na notificao, incluindo o ttulo da conversa,
 mensagens adicionais e a visualizao de contedo para a notificao.
</p>

<p>
  O seguinte snippet de cdigo demonstra como personalizar o estilo de uma
 notificao usando a classe <code>MessageStyle</code>.
</p>

<pre>
  Notification notification = new Notification.Builder()
             .setStyle(new Notification.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"));
</pre>