Notificaciones locales en Android

En esta sección se muestra cómo implementar notificaciones locales en Xamarin.Android. Explica los distintos elementos de la interfaz de usuario de una notificación de Android y describe los elementos de la API implicados en la creación y visualización de una notificación.

Introducción a las notificaciones locales

Android proporciona dos áreas controladas por el sistema para mostrar iconos de notificación e información de notificación al usuario. Cuando se publica una notificación por primera vez, su icono se muestra en el área de notificación, como se muestra en la captura de pantalla siguiente:

Example notification area on a device

Para obtener detalles sobre la notificación, el usuario puede abrir el cajón de notificaciones (que expande cada icono de notificación para mostrar el contenido de la notificación) y realizar cualquier acción asociada a las notificaciones. En la captura de pantalla siguiente se muestra un cajón de notificaciones que corresponde al área de notificación mostrada anteriormente:

Example notification drawer displaying three notifications

Las notificaciones de Android usan dos tipos de diseños:

  • Diseño base : un formato de presentación compacto y fijo.

  • Diseño expandido : un formato de presentación que puede expandirse a un tamaño mayor para mostrar más información.

Cada uno de estos tipos de diseño (y cómo crearlos) se explica en las secciones siguientes.

Nota

Esta guía se centra en las API notificationCompat de la biblioteca de soporte técnico de Android. Estas API garantizarán la compatibilidad máxima con versiones anteriores a Android 4.0 (nivel de API 14).

Diseño base

Todas las notificaciones de Android se basan en el formato de diseño base, que, como mínimo, incluye los siguientes elementos:

  1. Icono de notificación, que representa la aplicación de origen o el tipo de notificación si la aplicación admite diferentes tipos de notificaciones.

  2. El título de la notificación o el nombre del remitente si la notificación es un mensaje personal.

  3. Mensaje de notificación.

  4. Marca de tiempo.

Estos elementos se muestran como se muestra en el diagrama siguiente:

Location of notification elements

Los diseños base están limitados a 64 píxeles independientes de la densidad (dp) en altura. Android crea este estilo de notificación básico de forma predeterminada.

Opcionalmente, las notificaciones pueden mostrar un icono grande que representa la aplicación o la foto del remitente. Cuando se usa un icono grande en una notificación en Android 5.0 y versiones posteriores, el icono de notificación pequeño se muestra como un distintivo sobre el icono grande:

Simple notification photo

A partir de Android 5.0, las notificaciones también pueden aparecer en la pantalla de bloqueo:

Example lock screen notification

El usuario puede pulsar dos veces la notificación de la pantalla de bloqueo para desbloquear el dispositivo y saltar a la aplicación que originó esa notificación, o deslizar el dedo para descartar la notificación. Las aplicaciones pueden establecer el nivel de visibilidad de una notificación para controlar lo que se muestra en la pantalla de bloqueo y los usuarios pueden elegir si desea permitir que el contenido confidencial se muestre en las notificaciones de pantalla de bloqueo.

Android 5.0 introdujo un formato de presentación de notificación de alta prioridad denominado Encabezados. Las notificaciones de encabezado se deslizan hacia abajo desde la parte superior de la pantalla durante unos segundos y, a continuación, retiran la copia de seguridad en el área de notificación:

Example heads-up notification

Las notificaciones de encabezado permiten que la interfaz de usuario del sistema ponga información importante delante del usuario sin interrumpir el estado de la actividad que se está ejecutando actualmente.

Android incluye compatibilidad con metadatos de notificación para que las notificaciones se puedan ordenar y mostrar de forma inteligente. Los metadatos de notificación también controlan cómo se presentan las notificaciones en la pantalla de bloqueo y en formato de encabezado. Las aplicaciones pueden establecer los siguientes tipos de metadatos de notificación:

  • Prioridad : el nivel de prioridad determina cómo y cuándo se presentan las notificaciones. Por ejemplo, en Android 5.0, las notificaciones de alta prioridad se muestran como notificaciones de encabezado.

  • Visibilidad : especifica cuánto contenido de notificación se va a mostrar cuando la notificación aparece en la pantalla de bloqueo.

  • Categoría : informa al sistema de cómo controlar la notificación en diversas circunstancias, como cuando el dispositivo está en modo No molestar .

Nota

La visibilidad y la categoría se introdujeron en Android 5.0 y no están disponibles en versiones anteriores de Android. A partir de Android 8.0, los canales de notificación se usan para controlar cómo se presentan las notificaciones al usuario.

Diseños expandidos

A partir de Android 4.1, las notificaciones se pueden configurar con estilos de diseño expandidos que permiten al usuario expandir el alto de la notificación para ver más contenido. Por ejemplo, en el ejemplo siguiente se muestra una notificación de diseño expandida en modo contratado:

Contracted notification

Cuando se expande esta notificación, se muestra todo el mensaje:

Expanded notification

Android admite tres estilos de diseño expandidos para las notificaciones de un solo evento:

  • Texto grande : en modo contratado, muestra un extracto de la primera línea del mensaje seguido de dos puntos. En el modo expandido, muestra todo el mensaje (como se muestra en el ejemplo anterior).

  • Bandeja de entrada : en modo contratado, muestra el número de mensajes nuevos. En el modo expandido, muestra el primer mensaje de correo electrónico o una lista de los mensajes de la bandeja de entrada.

  • Imagen : en modo contratado, muestra solo el texto del mensaje. En el modo expandido, muestra el texto y una imagen.

Más allá de la notificación básica (más adelante en este artículo) se explica cómo crear notificaciones de texto grande, bandeja de entrada e imagen .

Canales de notificación

A partir de Android 8.0 (Oreo), puede usar la característica de canales de notificación para crear un canal personalizable por el usuario para cada tipo de notificación que quiera mostrar. Los canales de notificación permiten agrupar las notificaciones para que todas las notificaciones publicadas en un canal muestren el mismo comportamiento. Por ejemplo, puede tener un canal de notificación destinado a las notificaciones que requieran atención inmediata y un canal "más silencioso" independiente que se usa para los mensajes informativos.

La aplicación de YouTube que se instala con Android Oreo enumera dos categorías de notificación: Descargar notificaciones y notificaciones generales:

Notification screens for YouTube in Android Oreo

Cada una de estas categorías corresponde a un canal de notificación. La aplicación youTube implementa un canal de notificaciones de descarga y un canal de notificaciones generales . El usuario puede pulsar Descargar notificaciones, que muestra la pantalla de configuración del canal de notificaciones de descarga de la aplicación:

Download notifications screen for the YouTube app

En esta pantalla, el usuario puede modificar el comportamiento del canal Descargar notificaciones haciendo lo siguiente:

  • Establezca el nivel De importancia en Urgente, Alto, Medio o Bajo, que configura el nivel de interrupción sonora y visual.

  • Active o desactive el punto de notificación.

  • Enciende o desactiva la luz parpadeante.

  • Mostrar u ocultar notificaciones en la pantalla de bloqueo.

  • Invalide la configuración No molestar .

El canal de notificaciones generales tiene una configuración similar:

General notifications screen for the YouTube app

Tenga en cuenta que no tiene control absoluto sobre cómo interactúan los canales de notificación con el usuario: el usuario puede modificar la configuración de cualquier canal de notificación en el dispositivo, como se muestra en las capturas de pantalla anteriores. Sin embargo, puede configurar los valores predeterminados (como se describe a continuación). Como se muestra en estos ejemplos, la nueva característica de canales de notificación le permite proporcionar a los usuarios un control específico sobre diferentes tipos de notificaciones.

Creación de notificaciones

Para crear una notificación en Android, use la clase NotificationCompat.Builder del paquete de NuGet de Xamarin.Android.Support.v4. Esta clase permite crear y publicar notificaciones en versiones anteriores de Android. NotificationCompat.Builder también se analiza.

NotificationCompat.Builder proporciona métodos para establecer las distintas opciones de una notificación, como:

  • El contenido, incluido el título, el texto del mensaje y el icono de notificación.

  • Estilo de la notificación, como Texto grande, Bandeja de entrada o Estilo de imagen .

  • Prioridad de la notificación: mínimo, bajo, predeterminado, alto o máximo. En Android 8.0 y versiones posteriores, la prioridad se establece a través de un canal de notificación.

  • Visibilidad de la notificación en la pantalla de bloqueo: pública, privada o secreta.

  • Metadatos de categoría que ayudan a Android a clasificar y filtrar la notificación.

  • Una intención opcional que indica una actividad que se va a iniciar cuando se pulsa la notificación.

  • Identificador del canal de notificación en el que se publicará la notificación (Android 8.0 y versiones posteriores).

Después de establecer estas opciones en el generador, se genera un objeto de notificación que contiene la configuración. Para publicar la notificación, pase este objeto de notificación al Administrador de notificaciones. Android proporciona la clase NotificationManager , que es responsable de publicar notificaciones y mostrarlas al usuario. Se puede obtener una referencia a esta clase desde cualquier contexto, como una actividad o un servicio.

Creación de un canal de notificación

Las aplicaciones que se ejecutan en Android 8.0 deben crear un canal de notificación para sus notificaciones. Un canal de notificación requiere los tres fragmentos de información siguientes:

  • Cadena de identificador que es única para el paquete que identificará el canal.
  • Nombre del canal que se mostrará al usuario. El nombre debe tener entre uno y 40 caracteres.
  • La importancia del canal.

Las aplicaciones deberán comprobar la versión de Android en la que se ejecutan. Los dispositivos que ejecutan versiones anteriores a Android 8.0 no deben crear un canal de notificación. El método siguiente es un ejemplo de cómo crear un canal de notificación en una actividad:

void CreateNotificationChannel()
{
    if (Build.VERSION.SdkInt < BuildVersionCodes.O)
    {
        // Notification channels are new in API 26 (and not a part of the
        // support library). There is no need to create a notification
        // channel on older versions of Android.
        return;
    }

    var channelName = Resources.GetString(Resource.String.channel_name);
    var channelDescription = GetString(Resource.String.channel_description);
    var channel = new NotificationChannel(CHANNEL_ID, channelName, NotificationImportance.Default)
                  {
                      Description = channelDescription
                  };

    var notificationManager = (NotificationManager) GetSystemService(NotificationService);
    notificationManager.CreateNotificationChannel(channel);
}

El canal de notificación se debe crear cada vez que se crea la actividad. Para el CreateNotificationChannel método , se debe llamar al OnCreate método de una actividad.

Creación y publicación de una notificación

Para generar una notificación en Android, siga estos pasos:

  1. Cree una instancia de un objeto NotificationCompat.Builder.

  2. Llame a varios métodos en el NotificationCompat.Builder objeto para establecer las opciones de notificación.

  3. Llame al método Build del NotificationCompat.Builder objeto para crear una instancia de un objeto de notificación.

  4. Llame al método Notify del administrador de notificaciones para publicar la notificación.

Debe proporcionar al menos la siguiente información para cada notificación:

  • Un icono pequeño (tamaño de 24 x 24 dp)

  • Título corto

  • Texto de la notificación

En el ejemplo de código siguiente se muestra cómo usar NotificationCompat.Builder para generar una notificación básica. Observe que NotificationCompat.Builder los métodos admiten el encadenamiento de métodos; es decir, cada método devuelve el objeto builder para que pueda usar el resultado de la última llamada al método para invocar la siguiente llamada al método:

// Instantiate the builder and set notification elements:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

En este ejemplo, se crea una instancia de un nuevo NotificationCompat.Builder objeto denominado builder , junto con el identificador del canal de notificación que se va a usar. El título y el texto de la notificación se establecen y el icono de notificación se carga desde Resources/drawable/ic_notification.png. La llamada al método del generador de Build notificaciones crea un objeto de notificación con esta configuración. El siguiente paso es llamar al Notify método del administrador de notificaciones. Para buscar el administrador de notificaciones, llame a GetSystemService, como se muestra anteriormente.

El Notify método acepta dos parámetros: el identificador de notificación y el objeto de notificación. El identificador de notificación es un entero único que identifica la notificación a la aplicación. En este ejemplo, el identificador de notificación se establece en cero (0); sin embargo, en una aplicación de producción, querrá asignar a cada notificación un identificador único. La reutilización del valor de identificador anterior en una llamada a Notify hace que se sobrescriba la última notificación.

Cuando este código se ejecuta en un dispositivo Android 5.0, genera una notificación similar al ejemplo siguiente:

Notification result for the sample code

El icono de notificación se muestra en el lado izquierdo de la notificación: esta imagen de un círculo "i" tiene un canal alfa para que Android pueda dibujar un fondo circular gris detrás de ella. También puede proporcionar un icono sin un canal alfa. Para mostrar una imagen fotográfica como un icono, vea Formato de icono grande más adelante en este tema.

La marca de tiempo se establece automáticamente, pero puede invalidar esta configuración llamando al método SetWhen del generador de notificaciones. Por ejemplo, en el ejemplo de código siguiente se establece la marca de tiempo en la hora actual:

builder.SetWhen (Java.Lang.JavaSystem.CurrentTimeMillis());

Habilitar sonido y vibración

Si desea que la notificación también reproduzca un sonido, puede llamar al método SetDefaults del generador de notificaciones y pasar la NotificationDefaults.Sound marca :

// Instantiate the notification builder and enable sound:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetDefaults (NotificationDefaults.Sound)
    .SetSmallIcon (Resource.Drawable.ic_notification);

Esta llamada a SetDefaults hará que el dispositivo reproduzca un sonido cuando se publique la notificación. Si quieres que el dispositivo vibra en lugar de reproducir un sonido, puedes pasar NotificationDefaults.Vibrate a SetDefaults. Si quieres que el dispositivo reproduzca un sonido y vibrar el dispositivo, puedes pasar ambas marcas a SetDefaults:

builder.SetDefaults (NotificationDefaults.Sound | NotificationDefaults.Vibrate);

Si habilita el sonido sin especificar un sonido para reproducir, Android usa el sonido de notificación del sistema predeterminado. Sin embargo, puede cambiar el sonido que se reproducirá llamando al método SetSound del generador de notificaciones. Por ejemplo, para reproducir el sonido de alarma con su notificación (en lugar del sonido de notificación predeterminado), puede obtener el URI del sonido de alarma del RingtoneManager y pasarlo a SetSound:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Alarm));

Como alternativa, puede usar el sonido de tono de llamada predeterminado del sistema para la notificación:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Ringtone));

Después de crear un objeto de notificación, es posible establecer las propiedades de notificación en el objeto de notificación (en lugar de configurarlas de antemano a través NotificationCompat.Builder de métodos). Por ejemplo, en lugar de llamar al método para habilitar la SetDefaults vibración en una notificación, puede modificar directamente la marca de bits de la propiedad Defaults de la notificación:

// Build the notification:
Notification notification = builder.Build();

// Turn on vibrate:
notification.Defaults |= NotificationDefaults.Vibrate;

En este ejemplo, el dispositivo vibra cuando se publica la notificación.

Actualización de una notificación

Si desea actualizar el contenido de una notificación una vez publicada, puede reutilizar el objeto existente NotificationCompat.Builder para crear un nuevo objeto de notificación y publicar esta notificación con el identificador de la última notificación. Por ejemplo:

// Update the existing notification builder content:
builder.SetContentTitle ("Updated Notification");
builder.SetContentText ("Changed to this message.");

// Build a notification object with updated content:
notification = builder.Build();

// Publish the new notification with the existing ID:
notificationManager.Notify (notificationId, notification);

En este ejemplo, el objeto existente NotificationCompat.Builder se usa para crear un nuevo objeto de notificación con un título y un mensaje diferentes. El nuevo objeto de notificación se publica mediante el identificador de la notificación anterior y actualiza el contenido de la notificación publicada anteriormente:

Updated notification

El cuerpo de la notificación anterior se reutiliza: solo el título y el texto de la notificación cambia mientras la notificación se muestra en el cajón de notificaciones. El texto del título cambia de "Notificación de ejemplo" a "Notificación actualizada" y el texto del mensaje cambia de "Hola mundo! Esta es mi primera notificación!" a "Cambiado a este mensaje".

Una notificación permanece visible hasta que se produzca una de estas tres cosas:

  • El usuario descarta la notificación (o pulsa Borrar todo).

  • La aplicación realiza una llamada a NotificationManager.Cancel, pasando el identificador de notificación único que se asignó cuando se publicó la notificación.

  • La aplicación llama a NotificationManager.CancelAll.

Para obtener más información sobre cómo actualizar las notificaciones de Android, consulte Modificar una notificación.

Inicio de una actividad desde una notificación

En Android, es habitual que una notificación se asocie a una acción : una actividad que se inicia cuando el usuario pulsa la notificación. Esta actividad puede residir en otra aplicación o incluso en otra tarea. Para agregar una acción a una notificación, cree un objeto PendingIntent y asócielo PendingIntent a la notificación. Un PendingIntent es un tipo especial de intención que permite a la aplicación de destinatario ejecutar un fragmento predefinido de código con los permisos de la aplicación de envío. Cuando el usuario pulsa la notificación, Android inicia la actividad especificada por .PendingIntent

En el fragmento de código siguiente se muestra cómo crear una notificación con un PendingIntent que iniciará la actividad de la aplicación de origen, MainActivity:

// Set up an intent so that tapping the notifications returns to this app:
Intent intent = new Intent (this, typeof(MainActivity));

// Create a PendingIntent; we're only using one PendingIntent (ID = 0):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    PendingIntent.GetActivity (this, pendingIntentId, intent, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

Este código es muy similar al código de notificación de la sección anterior, salvo que se agrega un PendingIntent elemento al objeto de notificación. En este ejemplo, PendingIntent está asociado a la actividad de la aplicación de origen antes de pasarla al método SetContentIntent del generador de notificaciones. La PendingIntentFlags.OneShot marca se pasa al PendingIntent.GetActivity método para que PendingIntent se use una sola vez. Cuando se ejecuta este código, se muestra la siguiente notificación:

First action notification

Al pulsar esta notificación, el usuario vuelve a la actividad de origen.

En una aplicación de producción, la aplicación debe controlar la pila trasera cuando el usuario presiona el botón Atrás dentro de la actividad de notificación (si no está familiarizado con las tareas de Android y la pila de retroceso, consulte Tareas y Pila atrás). En la mayoría de los casos, navegar hacia atrás de la actividad de notificación debe devolver al usuario fuera de la aplicación y volver a la pantalla inicio. Para administrar la pila de retroceso, la aplicación usa la clase TaskStackBuilder para crear un PendingIntent con una pila trasera.

Otra consideración real es que la actividad de origen puede necesitar enviar datos a la actividad de notificación. Por ejemplo, la notificación puede indicar que ha llegado un mensaje de texto y la actividad de notificación (una pantalla de visualización de mensajes), requiere el identificador del mensaje para mostrar el mensaje al usuario. La actividad que crea PendingIntent puede usar el método Intent.PutExtra para agregar datos (por ejemplo, una cadena) a la intención para que estos datos se pasen a la actividad de notificación.

En el ejemplo de código siguiente se muestra cómo usar TaskStackBuilder para administrar la pila de retroceso e incluye un ejemplo de cómo enviar una sola cadena de mensaje a una actividad de notificación denominada SecondActivity:

// Setup an intent for SecondActivity:
Intent secondIntent = new Intent (this, typeof(SecondActivity));

// Pass some information to SecondActivity:
secondIntent.PutExtra ("message", "Greetings from MainActivity!");

// Create a task stack builder to manage the back stack:
TaskStackBuilder stackBuilder = TaskStackBuilder.Create(this);

// Add all parents of SecondActivity to the stack:
stackBuilder.AddParentStack (Java.Lang.Class.FromType (typeof (SecondActivity)));

// Push the intent that starts SecondActivity onto the stack:
stackBuilder.AddNextIntent (secondIntent);

// Obtain the PendingIntent for launching the task constructed by
// stackbuilder. The pending intent can be used only once (one shot):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    stackBuilder.GetPendingIntent (pendingIntentId, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including
// the pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my second action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

En este ejemplo de código, la aplicación consta de dos actividades: MainActivity (que contiene el código de notificación anterior) y SecondActivity, la pantalla que el usuario ve después de pulsar la notificación. Cuando se ejecuta este código, se presenta una notificación simple (similar al ejemplo anterior). Al pulsar en la notificación, el usuario se lleva a la SecondActivity pantalla:

Second activity screenshot

El mensaje de cadena (pasado al método de PutExtra la intención) se recupera mediante SecondActivity esta línea de código:

// Get the message from the intent:
string message = Intent.Extras.GetString ("message", "");

Este mensaje recuperado, "Greetings from MainActivity!", se muestra en la SecondActivity pantalla, como se muestra en la captura de pantalla anterior. Cuando el usuario presiona el botón Atrás mientras está en SecondActivity, la navegación sale de la aplicación y vuelve a la pantalla anterior al inicio de la aplicación.

Para obtener más información sobre cómo crear intenciones pendientes, consulte PendingIntent.

Más allá de la notificación básica

Las notificaciones tienen como valor predeterminado un formato de diseño base simple en Android, pero puede mejorar este formato básico realizando llamadas a métodos adicionales NotificationCompat.Builder . En esta sección, aprenderá a agregar un icono de foto grande a la notificación y verá ejemplos de cómo crear notificaciones de diseño expandidas.

Formato de icono grande

Las notificaciones de Android suelen mostrar el icono de la aplicación de origen (en el lado izquierdo de la notificación). Sin embargo, las notificaciones pueden mostrar una imagen o una foto (un icono grande) en lugar del icono pequeño estándar. Por ejemplo, una aplicación de mensajería podría mostrar una foto del remitente en lugar del icono de la aplicación.

Este es un ejemplo de una notificación básica de Android 5.0: muestra solo el icono de aplicación pequeña:

Example normal notification

Y esta es una captura de pantalla de la notificación después de modificarla para mostrar un icono grande: usa un icono creado a partir de una imagen de un mono de código de Xamarin:

Example large icon notification

Observe que cuando se presenta una notificación en formato de icono grande, el icono de aplicación pequeña se muestra como un distintivo en la esquina inferior derecha del icono grande.

Para usar una imagen como un icono grande en una notificación, llame al método SetLargeIcon del generador de notificaciones y pase un mapa de bits de la imagen. A diferencia de SetSmallIcon, SetLargeIcon solo acepta un mapa de bits. Para convertir un archivo de imagen en un mapa de bits, use la clase BitmapFactory . Por ejemplo:

builder.SetLargeIcon (BitmapFactory.DecodeResource (Resources, Resource.Drawable.monkey_icon));

Este código de ejemplo abre el archivo de imagen en Resources/drawable/monkey_icon.png, lo convierte en un mapa de bits y pasa el mapa de bits resultante a NotificationCompat.Builder. Normalmente, la resolución de la imagen de origen es mayor que el icono pequeño, pero no mucho mayor. Una imagen demasiado grande podría provocar operaciones de cambio de tamaño innecesarias que podrían retrasar la publicación de la notificación.

Estilo de texto grande

El estilo de texto grande es una plantilla de diseño expandida que se usa para mostrar mensajes largos en las notificaciones. Al igual que todas las notificaciones de diseño expandidas, la notificación de texto grande se muestra inicialmente en un formato de presentación compacto:

Example Big Text notification

En este formato, solo se muestra un extracto del mensaje, terminado por dos puntos. Cuando el usuario se arrastra hacia abajo en la notificación, se expande para mostrar todo el mensaje de notificación:

Expanded Big Text notification

Este formato de diseño expandido también incluye texto de resumen en la parte inferior de la notificación. El alto máximo de la notificación de texto grande es de 256 dp.

Para crear una notificación de texto grande , cree una instancia de un NotificationCompat.Builder objeto, como antes, y, a continuación, cree una instancia de un objeto BigTextStyle al NotificationCompat.Builder objeto . A continuación se muestra un ejemplo:

// Instantiate the Big Text style:
Notification.BigTextStyle textStyle = new Notification.BigTextStyle();

// Fill it with text:
string longTextMessage = "I went up one pair of stairs.";
longTextMessage += " / Just like me. ";
//...
textStyle.BigText (longTextMessage);

// Set the summary text:
textStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (textStyle);

// Create the notification and publish it ...

En este ejemplo, el texto del mensaje y el texto de resumen se almacenan en el BigTextStyle objeto (textStyle) antes de pasarlo a NotificationCompat.Builder.

Estilo de imagen

El estilo imagen (también denominado estilo de imagen grande ) es un formato de notificación expandido que puede usar para mostrar una imagen en el cuerpo de una notificación. Por ejemplo, una aplicación de captura de pantalla o una aplicación de fotos puede usar el estilo de notificación imagen para proporcionar al usuario una notificación de la última imagen capturada. Tenga en cuenta que el alto máximo de la notificación de imagen es 256 dp: Android cambiará el tamaño de la imagen para ajustarse a esta restricción máxima de alto, dentro de los límites de memoria disponible.

Al igual que todas las notificaciones de diseño expandidas, las notificaciones de imagen se muestran primero en un formato compacto que muestra un extracto del texto del mensaje adjunto:

Compact image notification shows no image

Cuando el usuario se arrastra hacia abajo en la notificación imagen , se expande para mostrar una imagen. Por ejemplo, esta es la versión expandida de la notificación anterior:

Expanded image notification reveals image

Observe que cuando la notificación se muestra en formato compacto, muestra texto de notificación (el texto que se pasa al método del SetContentText generador de notificaciones, como se muestra anteriormente). Sin embargo, cuando la notificación se expande para mostrar la imagen, muestra texto de resumen encima de la imagen.

Para crear una notificación image , cree una instancia de un NotificationCompat.Builder objeto como antes y, a continuación, cree e inserte un objeto BigPictureStyle en el NotificationCompat.Builder objeto . Por ejemplo:

// Instantiate the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Convert the image to a bitmap before passing it into the style:
picStyle.BigPicture (BitmapFactory.DecodeResource (Resources, Resource.Drawable.x_bldg));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create the notification and publish it ...

Al igual que el SetLargeIcon método de NotificationCompat.Builder, el método BigPicture de BigPictureStyle requiere un mapa de bits de la imagen que desea mostrar en el cuerpo de la notificación. En este ejemplo, el método DecodeResource de lee el archivo de BitmapFactory imagen ubicado en Resources/drawable/x_bldg.png y lo convierte en un mapa de bits.

También puede mostrar imágenes que no están empaquetadas como un recurso. Por ejemplo, el código de ejemplo siguiente carga una imagen de la tarjeta SD local y la muestra en una notificación de imagen :

// Using the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Read an image from the SD card, subsample to half size:
BitmapFactory.Options options = new BitmapFactory.Options();
options.InSampleSize = 2;
string imagePath = "/sdcard/Pictures/my-tshirt.jpg";
picStyle.BigPicture (BitmapFactory.DecodeFile (imagePath, options));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("Check out my new T-Shirt!");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create notification and publish it ...

En este ejemplo, el archivo de imagen ubicado en /sdcard/Pictures/my-tshirt.jpg se carga, cambia de tamaño a la mitad de su tamaño original y, a continuación, se convierte en un mapa de bits para su uso en la notificación:

Example T-shirt image in notification

Si no conoce el tamaño del archivo de imagen de antemano, es recomendable encapsular la llamada a BitmapFactory.DecodeFile en un controlador de excepciones; es posible que se produzca una OutOfMemoryError excepción si la imagen es demasiado grande para que Android cambie el tamaño.

Para obtener más información sobre cómo cargar y descodificar imágenes de mapa de bits de gran tamaño, vea Cargar mapas de bits grandes de forma eficaz.

Estilo de bandeja de entrada

El formato Bandeja de entrada es una plantilla de diseño expandida destinada a mostrar líneas de texto independientes (como un resumen de bandeja de entrada de correo electrónico) en el cuerpo de la notificación. La notificación de formato Bandeja de entrada se muestra primero en un formato compacto:

Example compact inbox notification

Cuando el usuario se arrastra hacia abajo en la notificación, se expande para mostrar un resumen de correo electrónico, como se muestra en la captura de pantalla siguiente:

Example inbox notification expanded

Para crear una notificación bandeja de entrada, cree una instancia de un NotificationCompat.Builder objeto, como antes, y agregue un objeto InboxStyle a .NotificationCompat.Builder A continuación se muestra un ejemplo:

// Instantiate the Inbox style:
Notification.InboxStyle inboxStyle = new Notification.InboxStyle();

// Set the title and text of the notification:
builder.SetContentTitle ("5 new messages");
builder.SetContentText ("chimchim@xamarin.com");

// Generate a message summary for the body of the notification:
inboxStyle.AddLine ("Cheeta: Bananas on sale");
inboxStyle.AddLine ("George: Curious about your blog post");
inboxStyle.AddLine ("Nikko: Need a ride to Evolve?");
inboxStyle.SetSummaryText ("+2 more");

// Plug this style into the builder:
builder.SetStyle (inboxStyle);

Para agregar nuevas líneas de texto al cuerpo de la notificación, llame al método Addline del InboxStyle objeto (el alto máximo de la notificación bandeja de entrada es 256 dp). Tenga en cuenta que, a diferencia del estilo de texto grande , el estilo bandeja de entrada admite líneas individuales de texto en el cuerpo de la notificación.

También puede usar el estilo Bandeja de entrada para cualquier notificación que necesite mostrar líneas de texto individuales en un formato expandido. Por ejemplo , el estilo de notificación bandeja de entrada se puede usar para combinar varias notificaciones pendientes en una notificación de resumen: puede actualizar una única notificación de estilo bandeja de entrada con nuevas líneas de contenido de notificación (consulte Actualización de una notificación anterior), en lugar de generar un flujo continuo de notificaciones nuevas, principalmente similares.

Configuración de metadatos

NotificationCompat.Builder incluye métodos a los que puede llamar para establecer metadatos sobre la notificación, como prioridad, visibilidad y categoría. Android usa esta información , junto con la configuración de preferencias del usuario, para determinar cómo y cuándo mostrar las notificaciones.

Configuración de prioridad

Las aplicaciones que se ejecutan en Android 7.1 y versiones inferiores deben establecer la prioridad directamente en la propia notificación. La configuración de prioridad de una notificación determina dos resultados cuando se publica la notificación:

  • Donde aparece la notificación en relación con otras notificaciones. Por ejemplo, las notificaciones de prioridad alta se presentan por encima de las notificaciones de menor prioridad en el cajón de notificaciones, independientemente de cuándo se publique cada notificación.

  • Indica si la notificación se muestra en el formato de notificación de encabezado (Android 5.0 y versiones posteriores). Solo se muestran las notificaciones de prioridad máxima y alta como notificaciones de encabezado.

Xamarin.Android define las siguientes enumeraciones para establecer la prioridad de notificación:

  • NotificationPriority.Max : alerta al usuario de una condición urgente o crítica (por ejemplo, una llamada entrante, indicaciones paso a paso o una alerta de emergencia). En dispositivos Android 5.0 y versiones posteriores, las notificaciones de prioridad máxima se muestran en formato de encabezado.

  • NotificationPriority.High – Informa al usuario de eventos importantes (como correos electrónicos importantes o la llegada de mensajes de chat en tiempo real). En dispositivos Android 5.0 y versiones posteriores, las notificaciones de prioridad alta se muestran en formato de encabezado.

  • NotificationPriority.Default – Notifica al usuario de condiciones que tienen un nivel medio de importancia.

  • NotificationPriority.Low – Para obtener información no urgente de la que el usuario debe informar (por ejemplo, avisos de actualización de software o actualizaciones de redes sociales).

  • NotificationPriority.Min – Para obtener información en segundo plano que el usuario note solo al ver las notificaciones (por ejemplo, información meteorológica o de ubicación).

Para establecer la prioridad de una notificación, llame al método SetPriority del NotificationCompat.Builder objeto, pasando el nivel de prioridad. Por ejemplo:

builder.SetPriority (NotificationPriority.High);

En el ejemplo siguiente, la notificación de prioridad alta, "Un mensaje importante" aparece en la parte superior del cajón de notificaciones:

Example high-priority notification

Dado que se trata de una notificación de alta prioridad, también se muestra como una notificación de encabezado por encima de la pantalla de actividad actual del usuario en Android 5.0:

Example Heads-up notification

En el ejemplo siguiente, la notificación "Thought for the day" de prioridad baja se muestra en una notificación de nivel de batería de prioridad superior:

Example low-priority notification

Dado que la notificación "Pensado para el día" es una notificación de prioridad baja, Android no la mostrará en formato de encabezado.

Nota

En Android 8.0 y versiones posteriores, la prioridad del canal de notificación y la configuración del usuario determinarán la prioridad de la notificación.

Configuración de visibilidad

A partir de Android 5.0, la configuración de visibilidad está disponible para controlar la cantidad de contenido de notificación que aparece en la pantalla de bloqueo seguro. Xamarin.Android define las enumeraciones siguientes para establecer la visibilidad de las notificaciones:

  • NotificationVisibility.Public – El contenido completo de la notificación se muestra en la pantalla de bloqueo seguro.

  • NotificationVisibility.Private – Solo se muestra información esencial en la pantalla de bloqueo segura (como el icono de notificación y el nombre de la aplicación que lo publicó), pero el resto de los detalles de la notificación están ocultos. Todas las notificaciones de forma predeterminada son NotificationVisibility.Private.

  • NotificationVisibility.Secret – No se muestra nada en la pantalla de bloqueo seguro, ni siquiera el icono de notificación. El contenido de la notificación solo está disponible después de que el usuario desbloquee el dispositivo.

Para establecer la visibilidad de una notificación, las aplicaciones llaman al SetVisibility método del NotificationCompat.Builder objeto y pasan la configuración de visibilidad. Por ejemplo, esta llamada a SetVisibility realiza la notificación Private:

builder.SetVisibility (NotificationVisibility.Private);

Cuando se publica una Private notificación, solo se muestra el nombre y el icono de la aplicación en la pantalla de bloqueo seguro. En lugar del mensaje de notificación, el usuario ve "Desbloquear el dispositivo para ver esta notificación":

Unlock your device notification message

En este ejemplo, NotificationsLab es el nombre de la aplicación de origen. Esta versión redactada de la notificación solo aparece cuando la pantalla de bloqueo es segura (es decir, protegida mediante PIN, patrón o contraseña), si la pantalla de bloqueo no es segura, el contenido completo de la notificación está disponible en la pantalla de bloqueo.

Configuración de categoría

A partir de Android 5.0, las categorías predefinidas están disponibles para las notificaciones de clasificación y filtrado. Xamarin.Android proporciona las siguientes enumeraciones para estas categorías:

  • Notification.CategoryCall – Llamada telefónica entrante.

  • Notification.CategoryMessage – Mensaje de texto entrante.

  • Notification.CategoryAlarm – Una condición de alarma o expiración del temporizador.

  • Notification.CategoryEmail – Mensaje de correo electrónico entrante.

  • Notification.CategoryEvent : un evento de calendario.

  • Notification.CategoryPromo – Un mensaje promocional o anuncio.

  • Notification.CategoryProgress : progreso de una operación en segundo plano.

  • Notification.CategorySocial – Actualización de redes sociales.

  • Notification.CategoryError – Error de una operación en segundo plano o proceso de autenticación.

  • Notification.CategoryTransport – Actualización de reproducción multimedia.

  • Notification.CategorySystem – Reservado para uso del sistema (estado del sistema o dispositivo).

  • Notification.CategoryService : indica que se está ejecutando un servicio en segundo plano.

  • Notification.CategoryRecommendation : mensaje de recomendación relacionado con la aplicación que se está ejecutando actualmente.

  • Notification.CategoryStatus – Información sobre el dispositivo.

Cuando se ordenan las notificaciones, la prioridad de la notificación tiene prioridad sobre su configuración de categoría. Por ejemplo, una notificación de prioridad alta se mostrará como Encabezado, incluso si pertenece a la Promo categoría. Para establecer la categoría de una notificación, llame al SetCategory método del NotificationCompat.Builder objeto y pase la configuración de categoría. Por ejemplo:

builder.SetCategory (Notification.CategoryCall);

La característica No molestar (nueva en Android 5.0) filtra las notificaciones en función de las categorías. Por ejemplo, la pantalla No molestar en Configuración permite al usuario excluir las notificaciones de llamadas telefónicas y mensajes:

Do not disturb screen switches

Cuando el usuario configura No molestar para bloquear todas las interrupciones excepto las llamadas telefónicas (como se muestra en la captura de pantalla anterior), Android permite que las notificaciones con una configuración de categoría de Notification.CategoryCall se presenten mientras el dispositivo está en modo No molestar . Tenga en cuenta que Notification.CategoryAlarm las notificaciones nunca se bloquean en el modo No molestar .

En el ejemplo LocalNotifications se muestra cómo usar NotificationCompat.Builder para iniciar una segunda actividad desde una notificación. Este código de ejemplo se explica en el tutorial Uso de notificaciones locales en Xamarin.Android .

Estilos de notificación

Para crear notificaciones de estilo de texto grande, imagen o bandeja de entrada con NotificationCompat.Builder, la aplicación debe usar las versiones de compatibilidad de estos estilos. Por ejemplo, para usar el estilo de texto grande , cree una NotificationCompat.BigTextstyleinstancia de :

NotificationCompat.BigTextStyle textStyle = new NotificationCompat.BigTextStyle();

// Plug this style into the builder:
builder.SetStyle (textStyle);

Del mismo modo, la aplicación puede usar NotificationCompat.InboxStyle y NotificationCompat.BigPictureStyle para los estilos Bandeja de entrada e Imagen , respectivamente.

Prioridad y categoría de notificación

NotificationCompat.Builder admite el SetPriority método (disponible a partir de Android 4.1). Sin embargo, el SetCategory método no es compatible porque NotificationCompat.Builder las categorías forman parte del nuevo sistema de metadatos de notificación que se introdujo en Android 5.0.

Para admitir versiones anteriores de Android, donde SetCategory no está disponible, el código puede comprobar el nivel de API en tiempo de ejecución para llamar SetCategory condicionalmente cuando el nivel de API sea igual o mayor que Android 5.0 (nivel de API 21):

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetCategory (Notification.CategoryEmail);
}

En este ejemplo, la plataforma de destino de la aplicación se establece en Android 5.0 y la versión mínima de Android se establece en Android 4.1 (nivel de API 16). Dado SetCategory que está disponible en el nivel de API 21 y versiones posteriores, este código de ejemplo llamará SetCategory solo cuando esté disponible, no llamará SetCategory cuando el nivel de API sea inferior a 21.

Visibilidad de la pantalla de bloqueo

Dado que Android no admitía notificaciones de pantalla de bloqueo antes de Android 5.0 (nivel de API 21), NotificationCompat.Builder no admite el SetVisibility método . Como se explicó anteriormente para SetCategory, el código puede comprobar el nivel de API en tiempo de ejecución y llamar SetVisiblity solo cuando esté disponible:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetVisibility (Notification.Public);
}

Resumen

En este artículo se explica cómo crear notificaciones locales en Android. Describe la anatomía de una notificación, explica cómo usar NotificationCompat.Builder para crear notificaciones, cómo aplicar estilo a las notificaciones en formatos de icono grande, texto grande, imagen e bandeja de entrada , cómo establecer la configuración de metadatos de notificación, como prioridad, visibilidad y categoría, y cómo iniciar una actividad desde una notificación. En este artículo también se describe cómo funcionan estas configuraciones de notificación con las nuevas características de bloqueo, pantalla de bloqueo y No molestar introducidas en Android 5.0. Por último, ha aprendido a usar NotificationCompat.Builder para mantener la compatibilidad de notificaciones con versiones anteriores de Android.

Para obtener instrucciones sobre cómo diseñar notificaciones para Android, consulte Notificaciones.