preview/features/notification-updates.jd

page.title=Notificaciones
page.tags=notifications
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 incluye lo siguiente:</h2>
<ol>
  <li><a href="#direct">Respuesta directa</a></li>
  <li><a href="#bundle">Notificaciones integradas</a></li>
  <li><a href="#custom">Vistas personalizadas</a></li>
  <li><a href="#style">Estilo de mensajera</a></li>
</ol>

</div>
</div>

<p>Android N presenta varias API nuevas que permiten a las aplicaciones publicar
notificaciones altamente visibles e interactivas.</p>

<p>Android N ampla la API de notificacin existente {@link android.support.v4.app.RemoteInput}
para admitir respuestas en lnea en telfonos celulares. Esta funcin permite a los usuarios
 responder rpidamente desde el panel de notificaciones sin tener que visitar tu aplicacin.</p>

<p>
  Android N tambin te permite agrupar notificaciones similares para que
  aparezcan como una sola notificacin. Para que esto sea posible, Android N usa el mtodo existente {@link
  android.support.v4.app.NotificationCompat.Builder#setGroup
  NotificationCompat.Builder.setGroup()}. Los usuarios pueden expandir cada una de las
  notificaciones y realizar acciones como responder e ignorar en cada una
  de ellas, de forma individual desde el panel de notificaciones.
</p>

<p>Por ltimo, Android N tambin suma nuevas API que te permiten aprovechar las decoraciones
del sistema en las vistas de notificacin personalizadas de tu aplicacin. Estas API ayudan a
garantizar que las vistas de notificaciones compartan una presentacin acorde a las
plantillas estndar.</p>

<p>En este documento se destacan algunos de los cambios clave que puedes tener en cuenta
 al usar las nuevas funciones de notificacin en tus aplicaciones.</p>

<h2 id="direct">Respuesta directa</h2>

<p>Con la funcin de respuesta directa en Android N, los usuarios pueden responder
rpidamente mensajes de texto o actualizar listas de tareas directamente dentro de la interfaz de
notificacin. En un dispositivo porttil, la accin de respuesta en lnea aparece como un botn adicional
 anexado a la notificacin. Cuando un usuario responde mediante el teclado, el sistema adjunta
 la respuesta de texto a la intent
 que especificaste para la accin de notificacin y enva la intencin a tu
 aplicacin para dispositivos porttiles.


<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> Android N agrega el botn de accin <strong>Reply</strong>
.
</p>

<h3>Adicin de acciones de respuesta en lnea</h3>

<p>Para crear una accin de notificacin que admita respuesta directa:
</p>

<ol>
<li>Crea una instancia de {@link android.support.v4.app.RemoteInput.Builder}
  que puedas agregar a tu accin de
notificacin. El constructor de esta clase acepta una cadena que el sistema usa como clave
 para la insercin de texto. Luego, tu aplicacin para dispositivos porttiles usar esa clave para recuperar el texto
  de la 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>Adjunta el objeto {@link android.support.v4.app.RemoteInput}
 a una accin 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>Aplica la accin a una notificacin y emite la notificacin.

<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> Cuando se active la accin de notificacin,
el sistema le solicitar al usuario que ingrese una respuesta. </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> El usuario ingresa texto desde el panel de notificaciones.
</p>

<h3>
  Recuperacin de entradas del usuario a partir de la respuesta en lnea
</h3>

<p>
  Para recibir entradas del usuario de la interfaz de notificacin a la actividad que
 declaraste en la intent de la accin de respuesta:
</p>

<ol>
  <li>Llama a {@link android.support.v4.app.RemoteInput#getResultsFromIntent
  getResultsFromIntent()} pasando la intent de la accin de notificacin como
 el parmetro de entrada. Este mtodo devuelve un {@link android.os.Bundle} que
 contiene la respuesta de texto.

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

  <li>Consulta el paquete con la clave de resultado (proporcionada al constructor {@link
  android.support.v4.app.RemoteInput.Builder}). Puedes completar
 este proceso y recuperar el texto de entrada mediante la creacin de un mtodo, como en el
 siguiente fragmento de cdigo:

    <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>Crea y emite otra notificacin, utilizando la misma ID de notificacin que
 proporcionaste para la notificacin anterior. El indicador de progreso
 desaparece de la interfaz de notificacin para informarles a los usuarios que la respuesta
 fue exitosa. Al trabajar con esta nueva notificacin, usa el contexto que se
 pasa al mtodo {@code onReceive()} del 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>
  En el caso de las aplicaciones interactivas, como los chats, podra ser til incluir
 contexto adicional cuando se administra texto recuperado. Por ejemplo, en estas aplicaciones, se podran mostrar
 mltiples lneas de historial de chat. Cuando el usuario responde a travs de {@link
  android.support.v4.app.RemoteInput}, puedes actualizar el historial de respuestas
 por medio del mtodo {@code setRemoteInputHistory()}.
</p>

<p>
  La notificacin se debe actualizar o cancelar luego de que la aplicacin haya
 recibido entradas remotas. Cuando el usuario responde a una actualizacin remota
 por medio de la respuesta directa,
 no canceles la notificacin. En cambio, actualiza la notificacin para mostrar la respuesta del usuario.
En el caso de las notificaciones que utilizan {@code MessagingStyle}, debes agregar
la respuesta como el mensaje ms reciente. Cuando se utilizan otras plantillas, puedes
agregar la respuesta del usuario al historial de entradas remotas.
</p>

<h2 id="bundle">Notificaciones integradas</h2>

<p>Android N ofrece a los desarrolladores una nueva manera de representar
 una cola de notificaciones: <i>notificaciones integradas</i>. Esto es similar a la funcin
  <a href="{@docRoot}training/wearables/notifications/stacks.html">Pilas de
  notificaciones</a> en Android Wear. Por ejemplo, si tu aplicacin crea notificaciones
  para los mensajes recibidos, cuando se recibe ms de un mensaje, agrupa las
 notificaciones en un solo paquete. Puedes
 usar el mtodo existente {@link android.support.v4.app.NotificationCompat.Builder#setGroup
Builder.setGroup()} para agrupar notificaciones similares.</p>

<p>
  El grupo de notificaciones impone una jerarqua en las notificaciones que lo integran.
  En la parte superior de esa jerarqua se encuentra una notificacin principal que muestra informacin
  resumida para el grupo. El usuario puede expandir
  progresivamente el grupo de notificaciones, y el sistema muestra ms informacin a medida que el
  usuario contina indagando. Cuando el usuario expande el paquete, el sistema revela ms
  informacin para todas sus notificaciones secundarias; cuando el usuario
  expande una de esas notificaciones, el sistema revela todo su contenido.
</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> El usuario puede expandir progresivamente el grupo de
 notificaciones.
</p>

<p class="note">
  <strong>Nota:</strong> Si la misma aplicacin enva cuatro o ms notificaciones
 y no se especifica un grupo, el
 sistema las agrupa automticamente.
</p>

<p>Para obtener informacin acerca de cmo agregar notificaciones a un grupo, consulta
<a href="{@docRoot}training/wearables/notifications/stacks.html#AddGroup">Agregar
cada notificacin a un grupo</a>.</p>


<h3 id="best-practices">Prcticas recomendadas para las notificaciones integradas</h3>
<p>Esta seccin proporciona pautas acerca de cundo usar grupos de notificaciones en lugar
de las notificaciones {@link android.app.Notification.InboxStyle InboxStyle}
que estaban disponibles en versiones anteriores de la
plataforma Android.</p>

<h3>Cundo usar notificaciones integradas</h3>

<p>Solo debes usar grupos de notificaciones si se cumplen todas las siguientes condiciones
para tu caso de uso:</p>

<ul>
  <li>Las notificaciones secundarias son notificaciones completas y se pueden mostrar
   individualmente sin la necesidad de un resumen del grupo.</li>
  <li>El aislamiento de notificaciones secundarias de forma individual tiene un beneficio. Por
  ejemplo:
  </li>
  <ul>
    <li>Son interactivas, con acciones especficas para cada notificacin secundaria.</li>
    <li>Hay ms informacin sobre la notificacin secundaria que el usuario quiere leer.</li>
  </ul>
</ul>

<p>Algunos ejemplos de buenos casos de uso para grupos de notificaciones incluyen: una aplicacin de mensajera
que exhiba una lista de mensajes entrantes, o una aplicacin de correo electrnico que exhiba una lista de
correos electrnicos recibidos.</p>

<p>
Algunos ejemplos de casos en los que se prefiere una sola notificacin
 incluyen mensajes individuales de una sola persona, o una lista de
 elementos de texto de una sola lnea. Para lograr esto, puedes usar
({@link android.app.Notification.InboxStyle InboxStyle} o
{@link android.app.Notification.BigTextStyle BigTextStyle})
.
</p>

<h3 id ="post">Visualizacin de notificaciones integradas</h3>

<p>
  La aplicacin siempre debe publicar un resumen del grupo, an si el grupo contiene una sola
 notificacin secundaria. Si contiene una sola notificacin, el sistema suprimir el resumen y mostrar directamente la
  notificacin secundaria. Esto garantiza
  que el sistema pueda proporcionar una experiencia uniforme cuando el usuario quita con un gesto de "deslizar" notificaciones
  secundarias de un grupo.
</p>

<p class="note">
  <strong>Nota:</strong> Esta versin de Android N an no
  suprime el resumen para los grupos de notificaciones que contienen una sola notificacin secundaria. Esta
  funcionalidad se agregar en una versin posterior de Android N.
</p>

<h3>Inspeccin de notificaciones</h3>

<p>Si bien el sistema generalmente muestra las notificaciones secundarias como un grupo, puedes configurarlas
 para que aparezcan temporalmente como
 <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#Heads-up">
 notificaciones emergentes</a>. Esta funcin es especialmente til porque permite
  el acceso inmediato a la notificacin secundaria ms reciente y a las acciones asociadas a ella.
</p>


<h3>Compatibilidad con versiones anteriores</h3>

<p>
  Tanto los grupos de notificaciones como las entradas remotas han formado parte de la API {@link
  android.app.Notification} desde Android 5.0 (API nivel 21) para soportar dispositivos
  con Android Wear. Si ya compilaste notificaciones con esas API,
  lo nico que debes hacer es verificar que el comportamiento de la aplicacin concuerde
  las pautas antes descritas y considerar la implementacin de {@code
  setRemoteInputHistory()}.
</p>

<p>
  Para poder ser compatible con versiones anteriores, estn disponibles las mismas API con
  la clase {@link android.support.v4.app.NotificationCompat}
  de la biblioteca de soporte, que te permite crear notificaciones que funcionan en versiones de Android
  anteriores. En dispositivos porttiles y tablets, los usuarios solo ven la notificacin de resumen
  de modo que una aplicacin an debe tener un estilo de bandeja de entrada o una notificacin equivalente
  que represente todo el contenido del grupo. Dado que los dispositivos con Android
  Wear permiten a los usuarios ver todas las notificaciones secundarias incluso en
  niveles anteriores de la plataforma, debes crear notificaciones secundarias independientemente del nivel de
  API.
</p>

<h2 id="custom"> Vistas personalizadas</h2>
<p>A partir de la versin Android N, puedes personalizar vistas de notificaciones y
an obtener decoraciones del sistema, como encabezados de notificaciones, acciones y diseos
expandibles.</p>

<p>Para habilitar esta caracterstica, Android N suma las siguientes API para que puedas disear tu
  vista personalizada:</p>

<dl>
<dt>
{@code DecoratedCustomViewStyle()}</dt>
<dd> Permite disear notificaciones que no sean notificaciones
de medios.</dd>
<dt>
{@code DecoratedMediaCustomViewStyle()}</dt>
<dd> Permite disear notificaciones de medios.</dd>
</dl>

<p>Para usar esta nueva API, llama al mtodo {@code setStyle()} y psale
el estilo de la vista personalizada que hayas elegido.</p>

<p>Este fragmento muestra cmo crear un objeto de notificacin personalizada con el 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 mensajera</h2>
<p>
  Android N presenta una nueva API para personalizar el estilo de una notificacin.
  Por medio de la clase <code>MessageStyle</code>, puedes modificar varias de las
 etiquetas que aparecen en la notificacin, incluidos el ttulo de la conversacin,
 mensajes adicionales y la vista de contenido para la notificacin.
</p>

<p>
  El siguiente fragmento de cdigo demuestra cmo personalizar el estilo
 de una notificacin mediante la clase <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>