Notificaciones locales en AndroidLocal notifications on Android

En esta sección se muestra cómo implementar notificaciones locales en Xamarin. Android. Se explican los distintos elementos de la interfaz de usuario de una notificación de Android y se describen las API implicadas en la creación y visualización de una notificación.This section shows how to implement local notifications in Xamarin.Android. It explains the various UI elements of an Android notification and discusses the API's involved with creating and displaying a notification.

Información general sobre las notificaciones localesLocal notifications overview

Android proporciona dos áreas controladas por el sistema para mostrar los iconos de notificación y la información de notificación al usuario.Android provides two system-controlled areas for displaying notification icons and notification information to the user. Cuando se publica una notificación por primera vez, su icono se muestra en el área de notificación, tal como se muestra en la siguiente captura de pantalla:When a notification is first published, its icon is displayed in the notification area, as shown in the following screenshot:

Ejemplo de área de notificación en un dispositivo

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 las acciones asociadas a las notificaciones.To obtain details about the notification, the user can open the notification drawer (which expands each notification icon to reveal notification content) and perform any actions associated with the notifications. En la captura de pantalla siguiente se muestra un cajón de notificaciones que se corresponde con el área de notificación mostrada anteriormente:The following screenshot shows a notification drawer that corresponds to the notification area displayed above:

cajón de notificaciones de ejemplo que muestra tres notificacionesExample notification drawer displaying three notifications

Las notificaciones de Android usan dos tipos de diseños:Android notifications use two types of layouts:

  • El diseño Base – un formato de presentación compacto y fijo.Base layout – a compact, fixed presentation format.

  • El diseño expandido – un formato de presentación que se puede expandir hasta un tamaño mayor para mostrar más información.Expanded layout – a presentation format that can expand to a larger size to reveal more information.

En las secciones siguientes se explica cada uno de estos tipos de diseño (y cómo crearlos).Each of these layout types (and how to create them) is explained in the following sections.

Nota

Esta guía se centra en las API de NotificationCompat de la biblioteca de compatibilidad de Android.This guide focuses on the NotificationCompat APIs from the Android support library. Estas API garantizarán la máxima compatibilidad con versiones anteriores de Android 4,0 (nivel de API 14).These APIs will ensure maximum backwards compatibility to Android 4.0 (API level 14).

Diseño baseBase layout

Todas las notificaciones de Android se basan en el formato de diseño base, que, como mínimo, incluye los siguientes elementos:All Android notifications are built on the base layout format, which, at a minimum, includes the following elements:

  1. Un icono de notificación, que representa la aplicación de origen, o el tipo de notificación si la aplicación admite distintos tipos de notificaciones.A notification icon, which represents the originating app, or the notification type if the app supports different types of notifications.

  2. El títulode la notificación o el nombre del remitente si la notificación es un mensaje personal.The notification title, or the name of the sender if the notification is a personal message.

  3. Mensaje de notificación.The notification message.

  4. Marcade tiempo.A timestamp.

Estos elementos se muestran como se muestra en el diagrama siguiente:These elements are displayed as illustrated in the following diagram:

ubicación de los elementos de notificaciónLocation of notification elements

Los diseños base se limitan a 64 píxeles independientes de densidad (DP) en altura.Base layouts are limited to 64 density-independent pixels (dp) in height. Android crea este estilo de notificación básico de forma predeterminada.Android creates this basic notification style by default.

Opcionalmente, las notificaciones pueden mostrar un icono grande que representa la aplicación o la foto del remitente.Optionally, notifications can display a large icon that represents the application or the sender's photo. Cuando se usa un icono grande en una notificación en Android 5,0 y versiones posteriores, el icono de notificación pequeña se muestra como un distintivo en el icono grande:When a large icon is used in a notification in Android 5.0 and later, the small notification icon is displayed as a badge over the large icon:

Foto de notificación simple

A partir de Android 5,0, las notificaciones también pueden aparecer en la pantalla de bloqueo:Beginning with Android 5.0, notifications can also appear on the lock screen:

ejemplo de notificación de pantalla de bloqueoExample lock screen notification

El usuario puede hacer doble punteo en la notificación de la pantalla de bloqueo para desbloquear el dispositivo y saltar a la aplicación que originó esa notificación, o bien deslizar para descartar la notificación.The user can double-tap the lock screen notification to unlock the device and jump to the app that originated that notification, or swipe to dismiss the notification. 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 que se muestre contenido confidencial en las notificaciones de la pantalla de bloqueo.Apps can set the visibility level of a notification to control what is shown on the lock screen, and users can choose whether to allow sensitive content to be shown in lock screen notifications.

Android 5,0 presentó un formato de presentación de notificaciones de alta prioridad denominado " Head-up".Android 5.0 introduced a high-priority notification presentation format called Heads-up. Las notificaciones de los cabezales se desplazan hacia abajo desde la parte superior de la pantalla durante unos segundos y, a continuación, se revierten al área de notificación:Heads-up notifications slide down from the top of the screen for a few seconds and then retreat back up to the notification area:

notificación de suscripción de ejemploExample heads-up notification

Las notificaciones de cabezales permiten que la interfaz de usuario del sistema Coloque información importante delante del usuario sin interrumpir el estado de la actividad que se está ejecutando actualmente.Heads-up notifications make it possible for the system UI to put important information in front of the user without disrupting the state of the currently running activity.

Android incluye compatibilidad con los metadatos de notificación para que las notificaciones se puedan ordenar y mostrar de manera inteligente.Android includes support for notification metadata so that notifications can be sorted and displayed intelligently. Los metadatos de notificación también controlan el modo en que se presentan las notificaciones en la pantalla de bloqueo y en formato de cabeza.Notification metadata also controls how notifications are presented on the lock screen and in Heads-up format. Las aplicaciones pueden establecer los siguientes tipos de metadatos de notificación:Applications can set the following types of notification metadata:

  • Prioridad – el nivel de prioridad determina cómo y cuándo se presentan las notificaciones.Priority – The priority level determines how and when notifications are presented. Por ejemplo, en Android 5,0, las notificaciones de alta prioridad se muestran como notificaciones de cabeza.For example, In Android 5.0, high-priority notifications are displayed as Heads-up notifications.

  • Visibilidad – especifica la cantidad de contenido de notificación que se va a mostrar cuando aparezca la notificación en la pantalla de bloqueo.Visibility – Specifies how much notification content is to be displayed when the notification appears on the lock screen.

  • La categoría – informa al sistema de cómo controlar la notificación en varias circunstancias, como cuando el dispositivo está en modo no molesta .Category – Informs the system how to handle the notification in various circumstances, such as when the device is in Do Not Disturb mode.

Nota

La visibilidad y la categoría se introdujeron en Android 5,0 y no están disponibles en versiones anteriores de Android.Visibility and Category were introduced in Android 5.0 and are not available in earlier versions of Android. A partir de Android 8,0, los canales de notificación se utilizan para controlar cómo se presentan las notificaciones al usuario.Beginning with Android 8.0, notification channels are used to control how notifications are presented to the user.

Diseños expandidosExpanded layouts

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.Beginning with Android 4.1, notifications can be configured with expanded layout styles that allow the user to expand the height of the notification to view more content. Por ejemplo, en el ejemplo siguiente se muestra una notificación de diseño expandida en modo de contrato:For example, the following example illustrates an expanded layout notification in contracted mode:

Notificación contratada

Cuando se expande esta notificación, se revela todo el mensaje:When this notification is expanded, it reveals the entire message:

Notificación expandida

Android admite tres estilos de diseño expandidos para las notificaciones de evento único:Android supports three expanded layout styles for single-event notifications:

  • Big Text – en modo de contrato, muestra un extracto de la primera línea del mensaje seguido de dos puntos.Big Text – In contracted mode, displays an excerpt of the first line of the message followed by two periods. En el modo expandido, muestra el mensaje completo (como se muestra en el ejemplo anterior).In expanded mode, displays the entire message (as seen in the above example).

  • – de bandeja de entrada en modo de contrato, muestra el número de mensajes nuevos.Inbox – In contracted mode, displays the number of new messages. En el modo expandido, muestra el primer mensaje de correo electrónico o una lista de los mensajes en la bandeja de entrada.In expanded mode, displays the first email message or a list of the messages in the inbox.

  • Imagen – en modo de contrato, solo muestra el texto del mensaje.Image – In contracted mode, displays only the message text. En el modo expandido, muestra el texto y una imagen.In expanded mode, displays the text and an image.

Además de la notificación básica (más adelante en este artículo), se explica cómo crear notificaciones de texto, bandeja de entradae imagen .Beyond the Basic Notification (later in this article) explains how to create Big Text, Inbox, and Image notifications.

Canales de notificaciónNotification channels

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 desea mostrar.Beginning with Android 8.0 (Oreo), you can use the notification channels feature to create a user-customizable channel for each type of notification that you want to display. Los canales de notificación permiten agrupar las notificaciones para que todas las notificaciones enviadas a un canal presenten el mismo comportamiento.Notification channels make it possible for you to group notifications so that all notifications posted to a channel exhibit the same behavior. Por ejemplo, podría tener un canal de notificación destinado a notificaciones que requieran atención inmediata y un canal "más silencioso" independiente que se use para mensajes informativos.For example, you might have a notification channel that is intended for notifications that require immediate attention, and a separate "quieter" channel that is used for informational messages.

La aplicación de YouTube que se instala con Android Oreo enumera dos categorías de notificación: Descargar notificaciones y notificaciones generales:The YouTube app that is installed with Android Oreo lists two notification categories: Download notifications and General notifications:

pantallas de notificaciones depara YouTube en Android OreoNotification screens for YouTube in Android Oreo

Cada una de estas categorías corresponde a un canal de notificación.Each of these categories corresponds to a notification channel. La aplicación de YouTube implementa un canal de notificaciones de descarga y un canal de notificaciones generales .The YouTube app implements a Download Notifications channel and a General Notifications channel. El usuario puede pulsar Descargar notificaciones, que muestra la pantalla de configuración del canal de notificaciones de descarga de la aplicación:The user can tap Download notifications, which displays the settings screen for the app's download notifications channel:

pantalla de descargas de notificaciones para la aplicación de YouTubeDownload notifications screen for the YouTube app

En esta pantalla, el usuario puede modificar el comportamiento del canal de las notificaciones de descarga haciendo lo siguiente:In this screen, the user can modify the behavior of the Download notifications channel by doing the following:

  • Establezca el nivel de importancia en urgente, alto, medioo bajo, lo que configura el nivel de interrupción de sonido y visual.Set the Importance level to Urgent, High, Medium, or Low, which configures the level of sound and visual interruption.

  • Activar o desactivar el punto de notificación.Turn the notification dot on or off.

  • Activar o desactivar la luz intermitente.Turn the blinking light on or off.

  • Mostrar u ocultar notificaciones en la pantalla de bloqueo.Show or hide notifications on the lock screen.

  • Invalide la configuración de no molestar .Override the Do Not Disturb setting.

El canal de notificaciones generales tiene una configuración similar:The General Notifications channel has similar settings:

pantalla general de notificaciones de la aplicación de YouTubeGeneral notifications screen for the YouTube app

Tenga en cuenta que no tiene control absoluto sobre el modo en que los canales de notificación interactúan con el usuario – el usuario puede modificar la configuración de cualquier canal de notificación en el dispositivo, tal como se ve en las capturas de pantallas anteriores.Notice that you do not have absolute control over how your notification channels interact with the user – the user can modify the settings for any notification channel on the device as seen in the screenshots above. Sin embargo, puede configurar los valores predeterminados (como se describe a continuación).However, you can configure default values (as will be described below). Como se muestra en estos ejemplos, la nueva característica de canales de notificación permite proporcionar a los usuarios un mayor control sobre los distintos tipos de notificaciones.As these examples illustrate, the new notification channels feature makes it possible for you to give users fine-grained control over different kinds of notifications.

Creación de notificacionesNotification creation

Para crear una notificación en Android, use la clase NotificationCompat. Builder del paquete NuGet Xamarin. Android. support. V4 .To create a notification in Android, you use the NotificationCompat.Builder class from the Xamarin.Android.Support.v4 NuGet package. Esta clase permite crear y publicar notificaciones en versiones anteriores de Android.This class makes it possible to create and publish notifications on older versions of Android. también se describe NotificationCompat.Builder.NotificationCompat.Builder is also discussed.

NotificationCompat.Builder proporciona métodos para establecer las diversas opciones en una notificación, como:NotificationCompat.Builder provides methods for setting the various options in a notification, such as:

  • El contenido, incluido el título, el texto del mensaje y el icono de notificación.The content, including the title, the message text, and the notification icon.

  • Estilo de la notificación, como el estilo de texto grande, bandeja de entradao imagen .The style of the notification, such as Big Text, Inbox, or Image style.

  • La prioridad de la notificación: mínima, baja, predeterminada, alta o máxima.The priority of the notification: minimum, low, default, high, or maximum. En Android 8,0 y versiones posteriores, la prioridad se establece a través de un canal de notificación.On Android 8.0 and higher, the priority is set via a notification channel.

  • La visibilidad de la notificación en la pantalla de bloqueo: pública, privada o secreta.The visibility of the notification on the lock screen: public, private, or secret.

  • Metadatos de categoría que ayudan a Android a clasificar y filtrar la notificación.Category metadata that helps Android classify and filter the notification.

  • Una intención opcional que indica que una actividad se inicia cuando se puntea la notificación.An optional intent that indicates an activity to launch when the notification is tapped.

  • IDENTIFICADOR del canal de notificación en el que se publicará la notificación (Android 8,0 y versiones posteriores).The ID of the notification channel that the notification will be published on (Android 8.0 and higher).

Después de establecer estas opciones en el generador, se genera un objeto de notificación que contiene la configuración.After you set these options in the builder, you generate a notification object that contains the settings. Para publicar la notificación, se pasa este objeto de notificación al Administrador de notificaciones.To publish the notification, you pass this notification object to the Notification Manager. Android proporciona la clase NotificationManager , que es responsable de publicar notificaciones y mostrarla al usuario.Android provides the NotificationManager class, which is responsible for publishing notifications and displaying them to the user. Se puede obtener una referencia a esta clase desde cualquier contexto, como una actividad o un servicio.A reference to this class can be obtained from any context, such as an activity or a service.

Creación de un canal de notificaciónCreating a notification channel

Las aplicaciones que se ejecutan en Android 8,0 deben crear un canal de notificación para las notificaciones.Apps that are running on Android 8.0 must create a notification channel for their notifications. Un canal de notificación requiere los tres datos siguientes:A notification channel requires the following three pieces of information:

  • Una cadena de identificador que es única para el paquete que identificará el canal.An ID string that is unique to the package that will identify the channel.
  • Nombre del canal que se va a mostrar al usuario.The name of the channel that will be displayed to the user. El nombre debe tener entre 1 y 40 caracteres.The name must be between one and 40 characters.
  • Importancia del canal.The importance of the channel.

Las aplicaciones deberán comprobar la versión de Android que se están ejecutando.Apps will need to check the version of Android that they are running. Los dispositivos que ejecutan versiones anteriores a Android 8,0 no deben crear un canal de notificación.Devices running versions older than Android 8.0 should not create a notification channel. El método siguiente es un ejemplo de cómo crear un canal de notificación en una actividad:The following method is one example of how to create a notification channel in an activity:

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);
}

Se debe crear el canal de notificación cada vez que se cree la actividad.The notification channel should be created each time the activity is created. En el caso del método CreateNotificationChannel, debe llamarse en el método OnCreate de una actividad.For the CreateNotificationChannel method, it should be called in the OnCreate method of an activity.

Crear y publicar una notificaciónCreating and publishing a notification

Para generar una notificación en Android, siga estos pasos:To generate a notification in Android, follow these steps:

  1. Cree una instancia de un objeto NotificationCompat.Builder.Instantiate a NotificationCompat.Builder object.

  2. Llame a varios métodos en el objeto NotificationCompat.Builder para establecer las opciones de notificación.Call various methods on the NotificationCompat.Builder object to set notification options.

  3. Llame al método Build del objeto NotificationCompat.Builder para crear una instancia de un objeto de notificación.Call the Build method of the NotificationCompat.Builder object to instantiate a notification object.

  4. Llame al método Notify del administrador de notificaciones para publicar la notificación.Call the Notify method of the notification manager to publish the notification.

Debe proporcionar al menos la siguiente información para cada notificación:You must provide at least the following information for each notification:

  • Un icono pequeño (24x24 DP de tamaño)A small icon (24x24 dp in size)

  • Un título cortoA short title

  • El texto de la notificaciónThe text of the notification

En el ejemplo de código siguiente se muestra cómo usar NotificationCompat.Builder para generar una notificación básica.The following code example illustrates how to use NotificationCompat.Builder to generate a basic notification. Observe que los métodos de NotificationCompat.Builder admiten el encadenamiento de métodos; es decir, cada método devuelve el objeto de generador para que pueda usar el resultado de la última llamada al método para invocar la siguiente llamada al método:Notice that NotificationCompat.Builder methods support method chaining; that is, each method returns the builder object so you can use the result of the last method call to invoke the next method call:

// 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 objeto NotificationCompat.Builder denominado builder, junto con el identificador del canal de notificación que se va a usar.In this example, a new NotificationCompat.Builder object called builder is instantiated, along with the ID of the notification channel to be used. Se establecen el título y el texto de la notificación, y el icono de notificación se carga desde Resources/drawable/ic_notification. png.The title and text of the notification are set, and the notification icon is loaded from Resources/drawable/ic_notification.png. La llamada al método Build del generador de notificaciones crea un objeto de notificación con esta configuración.The call to the notification builder's Build method creates a notification object with these settings. El siguiente paso consiste en llamar al método Notify del administrador de notificaciones.The next step is to call the Notify method of the notification manager. Para buscar el administrador de notificaciones, llame a GetSystemService, como se mostró anteriormente.To locate the notification manager, you call GetSystemService, as shown above.

El método Notify acepta dos parámetros: el identificador de notificación y el objeto de notificación.The Notify method accepts two parameters: the notification identifier and the notification object. El identificador de notificación es un entero único que identifica la notificación en la aplicación.The notification identifier is a unique integer that identifies the notification to your application. 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.In this example, the notification identifier is set to zero (0); however, in a production application, you will want to give each notification a unique identifier. Reutilizar el valor del identificador anterior en una llamada a Notify provoca que se sobrescriba la última notificación.Reusing the previous identifier value in a call to Notify causes the last notification to be overwritten.

Cuando este código se ejecuta en un dispositivo Android 5,0, genera una notificación similar a la del ejemplo siguiente:When this code runs on an Android 5.0 device, it generates a notification that looks like the following example:

Resultado de la notificación para el código de ejemplo

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.The notification icon is displayed on the left hand side of the notification – this image of a circled “i” has an alpha channel so that Android can draw a gray circular background behind it. También puede proporcionar un icono sin un canal alfa.You can also supply an icon without an alpha channel. Para mostrar una imagen fotográfica como un icono, consulte formato de iconos grandes más adelante en este tema.To display a photographic image as an icon, see Large Icon Format later in this topic.

La marca de tiempo se establece automáticamente, pero puede invalidar esta configuración mediante una llamada al método SetWhen del generador de notificaciones.The timestamp is set automatically, but you can override this setting by calling the SetWhen method of the notification builder. Por ejemplo, en el ejemplo de código siguiente se establece la marca de tiempo en la hora actual:For example, the following code example sets the timestamp to the current time:

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

Habilitar sonido y vibraciónEnabling sound and vibration

Si desea que la notificación también emita un sonido, puede llamar al método SetDefaults del generador de notificaciones y pasar el NotificationDefaults.Sound marca:If you want your notification to also play a sound, you can call the notification builder's SetDefaults method and pass in the NotificationDefaults.Sound flag:

// 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.This call to SetDefaults will cause the device to play a sound when the notification is published. Si desea que el dispositivo vibra en lugar de reproducir un sonido, puede pasar NotificationDefaults.Vibrate a SetDefaults. si desea que el dispositivo reproduzca un sonido y vibra el dispositivo, puede pasar ambas marcas a SetDefaults:If you want the device to vibrate rather than play a sound, you can pass NotificationDefaults.Vibrate to SetDefaults. If you want the device to play a sound and vibrate the device, you can pass both flags to SetDefaults:

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

Si habilita el sonido sin especificar un sonido para reproducir, Android usa el sonido predeterminado de la notificación del sistema.If you enable sound without specifying a sound to play, Android uses the default system notification sound. Sin embargo, puede cambiar el sonido que se reproducirá llamando al método SetSound del generador de notificaciones.However, you can change the sound that will be played by calling the notification builder's SetSound method. Por ejemplo, para reproducir el sonido de alarma con la notificación (en lugar del sonido de notificación predeterminado), puede obtener el URI del sonido de alarma desde el RingtoneManager y pasarlo a SetSound:For example, to play the alarm sound with your notification (instead of the default notification sound), you can get the URI for the alarm sound from the RingtoneManager and pass it to SetSound:

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

Como alternativa, puede usar el sonido de tono predeterminado del sistema para su notificación:Alternatively, you can use the system default ringtone sound for your notification:

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 mediante métodos NotificationCompat.Builder).After you create a notification object, it's possible to set notification properties on the notification object (rather than configure them in advance through NotificationCompat.Builder methods). Por ejemplo, en lugar de llamar al método SetDefaults para habilitar la vibración en una notificación, puede modificar directamente la marca de bits de la propiedad de valores predeterminados de la notificación:For example, instead of calling the SetDefaults method to enable vibration on a notification, you can directly modify the bit flag of the notification's Defaults property:

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

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

Este ejemplo hace que el dispositivo vibra cuando se publica la notificación.This example causes the device to vibrate when the notification is published.

Actualización de una notificaciónUpdating a notification

Si desea actualizar el contenido de una notificación una vez publicada, puede volver a usar el objeto de NotificationCompat.Builder existente para crear un nuevo objeto de notificación y publicar esta notificación con el identificador de la última notificación.If you want to update the content of a notification after it has been published, you can reuse the existing NotificationCompat.Builder object to create a new notification object and publish this notification with the identifier of the last notification. Por ejemplo:For example:

// 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 de NotificationCompat.Builder existente se usa para crear un nuevo objeto de notificación con un título y un mensaje distintos.In this example, the existing NotificationCompat.Builder object is used to create a new notification object with a different title and message. El nuevo objeto de notificación se publica con el identificador de la notificación anterior y esto actualiza el contenido de la notificación publicada anteriormente:The new notification object is published using the identifier of the previous notification, and this updates the content of the previously-published notification:

Notificación actualizada

El cuerpo de la notificación anterior se reutiliza – solo cambian el título y el texto de la notificación mientras la notificación se muestra en el cajón de notificaciones.The body of the previous notification is reused – only the title and the text of the notification changes while the notification is displayed in the notification drawer. El texto del título cambia de "notificación de ejemplo" a "notificación actualizada" y el texto del mensaje cambia de "Hola mundo.The title text changes from "Sample Notification" to "Updated Notification" and the message text changes from "Hello World! Esta es mi primera notificación.This is my first notification!" en "cambio a este mensaje".to "Changed to this message."

Una notificación permanece visible hasta que se produce una de estas tres acciones:A notification remains visible until one of three things happens:

  • El usuario descarta la notificación (o pulsa Borrar todo).The user dismisses the notification (or taps Clear All).

  • 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.The application makes a call to NotificationManager.Cancel, passing in the unique notification ID that was assigned when the notification was published.

  • La aplicación llama a NotificationManager.CancelAll.The application calls NotificationManager.CancelAll.

Para obtener más información sobre cómo actualizar las notificaciones de Android, consulte modificar una notificación.For more about updating Android notifications, see Modify a Notification.

Inicio de una actividad a partir de una notificaciónStarting an activity from a notification

En Android, es habitual asociar una notificación a una acción – una actividad que se inicia cuando el usuario pulsa la notificación.In Android, it's common for a notification to be associated with an action – an activity that's launched when the user taps the notification. Esta actividad puede residir en otra aplicación o incluso en otra tarea.This activity can reside in another application or even in another task. Para agregar una acción a una notificación, cree un objeto PendingIntent y asocie el PendingIntent a la notificación.To add an action to a notification, you create a PendingIntent object and associate the PendingIntent with the notification. Un PendingIntent es un tipo especial de intención que permite a la aplicación de destinatario ejecutar un fragmento de código predefinido con los permisos de la aplicación de envío.A PendingIntent is a special type of intent that allows the recipient application to run a predefined piece of code with the permissions of the sending application. Cuando el usuario pulsa la notificación, Android inicia la actividad especificada por el PendingIntent.When the user taps the notification, Android starts up the activity specified by the PendingIntent.

El siguiente fragmento de código muestra cómo crear una notificación con un PendingIntent que iniciará la actividad de la aplicación de origen, MainActivity:The following code snippet illustrates how to create a notification with a PendingIntent that will launch the activity of the originating app, 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, excepto en que se agrega un PendingIntent al objeto de notificación.This code is very similar to the notification code in the previous section, except that a PendingIntent is added to the notification object. En este ejemplo, el PendingIntent está asociado a la actividad de la aplicación de origen antes de que se pase al método SetContentIntent del generador de notificaciones.In this example, the PendingIntent is associated with the activity of the originating app before it is passed to the notification builder's SetContentIntent method. La marca de PendingIntentFlags.OneShot se pasa al método PendingIntent.GetActivity para que el PendingIntent se use solo una vez.The PendingIntentFlags.OneShot flag is passed to the PendingIntent.GetActivity method so that the PendingIntent is used only once. Cuando se ejecuta este código, se muestra la siguiente notificación:When this code runs, the following notification is displayed:

Primera notificación de acción

Al pulsar esta notificación, el usuario vuelve a la actividad de origen.Tapping this notification takes the user back to the originating activity.

En una aplicación de producción, la aplicación debe controlar la pila de retroceso 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 de retroceso).In a production app, your app must handle the back stack when the user presses the Back button within the notification activity (if you are not familiar with Android tasks and the back stack, see Tasks and Back Stack). En la mayoría de los casos, la navegación hacia atrás de la actividad de notificación debe devolver al usuario de la aplicación y volver a la pantalla principal.In most cases, navigating backward out of the notification activity should return the user out of the app and back to Home screen. Para administrar la pila de retroceso, la aplicación usa la clase TaskStackBuilder para crear una PendingIntent con una pila de retroceso.To manage the back stack, your app uses the TaskStackBuilder class to create a PendingIntent with a back stack.

Otra consideración real es que la actividad de origen puede necesitar enviar datos a la actividad de notificación.Another real-world consideration is that the originating activity may need to send data to the notification activity. 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.For example, the notification may indicate that a text message has arrived, and the notification activity (a message viewing screen), requires the ID of the message to display the message to the user. La actividad que crea el PendingIntent puede usar el método Intent. PutExtra para agregar datos (por ejemplo, una cadena) al intento de modo que estos datos se pasen a la actividad de notificación.The activity that creates the PendingIntent can use the Intent.PutExtra method to add data (for example, a string) to the intent so that this data is passed to the notification activity.

En el ejemplo de código siguiente se muestra cómo usar TaskStackBuilder para administrar la pila de retroceso y se incluye un ejemplo de cómo enviar una cadena de un solo mensaje a una actividad de notificación llamada SecondActivity:The following code sample illustrates how to use TaskStackBuilder to manage the back stack, and it includes an example of how to send a single message string to a notification activity called 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.In this code example, the app consists of two activities: MainActivity (which contains the notification code above), and SecondActivity, the screen the user sees after tapping the notification. Cuando se ejecuta este código, se presenta una notificación simple (similar al ejemplo anterior).When this code is run, a simple notification (similar to the previous example) is presented. Al pulsar en la notificación, el usuario se dirige a la pantalla SecondActivity:Tapping on the notification takes the user to the SecondActivity screen:

Captura de pantalla de segunda actividad

El mensaje de cadena (que se pasa al método PutExtra de la intención) se recupera en SecondActivity a través de esta línea de código:The string message (passed into the intent's PutExtra method) is retrieved in SecondActivity via this line of code:

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

Este mensaje recuperado, "Greetings from MainActivity!," se muestra en la pantalla SecondActivity, como se muestra en la captura de pantalla anterior.This retrieved message, "Greetings from MainActivity!," is displayed in the SecondActivity screen, as shown in the above screenshot. Cuando el usuario presiona el botón atrás mientras está en SecondActivity, la navegación conduce a la aplicación y vuelve a la pantalla anterior al inicio de la aplicación.When the user presses the Back button while in SecondActivity, navigation leads out of the app and back to the screen preceding the launch of the app.

Para obtener más información sobre la creación de intenciones pendientes, vea PendingIntent.For more information about creating pending intents, see PendingIntent.

Más allá de la notificación básicaBeyond the basic notification

Las notificaciones tienen como valor predeterminado un formato de diseño base simple en Android, pero puede mejorar este formato básico si realiza llamadas de método NotificationCompat.Builder adicionales.Notifications default to a simple base layout format in Android, but you can enhance this basic format by making additional NotificationCompat.Builder method calls. 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.In this section, you'll learn how to add a large photo icon to your notification, and you'll see examples of how to create expanded layout notifications.

Formato de iconos grandesLarge icon format

Las notificaciones de Android suelen mostrar el icono de la aplicación de origen (en el lado izquierdo de la notificación).Android notifications typically display the icon of the originating app (on the left side of the notification). Sin embargo, las notificaciones pueden mostrar una imagen o una foto (un icono grande) en lugar del icono pequeño estándar.However, notifications can display an image or a photo (a large icon) instead of the standard small icon. Por ejemplo, una aplicación de mensajería podría mostrar una foto del remitente en lugar del icono de la aplicación.For example, a messaging app could display a photo of the sender rather than the app icon.

Este es un ejemplo de una notificación básica de Android 5,0 – muestra solo el icono de aplicación pequeña:Here is an example of a basic Android 5.0 notification – it displays only the small app icon:

Notificación normal de ejemplo

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 Monkey de código Xamarin:And here is a screenshot of the notification after modifying it to display a large icon – it uses an icon created from an image of a Xamarin code monkey:

Ejemplo de notificación de iconos grandes

Tenga en cuenta que cuando se presenta una notificación en formato de iconos grandes, el icono de aplicación pequeña se muestra como un distintivo en la esquina inferior derecha del icono grande.Notice that when a notification is presented in large icon format, the small app icon is displayed as a badge on the lower right corner of the large icon.

Para usar una imagen como un icono grande en una notificación, se llama al método SetLargeIcon del generador de notificaciones y se pasa un mapa de bits de la imagen.To use an image as a large icon in a notification, you call the notification builder's SetLargeIcon method and pass in a bitmap of the image. A diferencia de SetSmallIcon, SetLargeIcon solo acepta un mapa de bits.Unlike SetSmallIcon, SetLargeIcon only accepts a bitmap. Para convertir un archivo de imagen en un mapa de bits, se usa la clase BitmapFactory .To convert an image file into a bitmap, you use the BitmapFactory class. Por ejemplo:For example:

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.This example code opens the image file at Resources/drawable/monkey_icon.png, converts it to a bitmap, and passes the resulting bitmap to NotificationCompat.Builder. Normalmente, la resolución de la imagen de origen es mayor que el icono pequeño – pero no mucho mayor.Typically, the source image resolution is larger than the small icon – but not much larger. Una imagen demasiado grande podría producir operaciones de cambio de tamaño innecesarias que podrían retrasar el envío de la notificación.An image that is too large might cause unnecessary resizing operations that could delay the posting of the notification.

Estilo de texto grandeBig text style

El estilo de texto grande es una plantilla de diseño expandida que se usa para mostrar mensajes largos en las notificaciones.The Big Text style is an expanded layout template that you use for displaying long messages in notifications. Al igual que todas las notificaciones de diseño expandidas, la notificación de Big Text se muestra inicialmente en un formato de presentación compacto:Like all expanded layout notifications, the Big Text notification is initially displayed in a compact presentation format:

Ejemplo de notificación de texto grande

En este formato, solo se muestra un extracto del mensaje, finalizado en dos puntos.In this format, only an excerpt of the message is shown, terminated by two periods. Cuando el usuario arrastra hacia abajo en la notificación, se expande para mostrar el mensaje de notificación completo:When the user drags down on the notification, it expands to reveal the entire notification message:

Notificación de Big Text expandida

Este formato de diseño expandido también incluye texto de resumen en la parte inferior de la notificación.This expanded layout format also includes summary text at the bottom of the notification. El alto máximo de la notificación de Big Text es 256 DP.The maximum height of the Big Text notification is 256 dp.

Para crear una notificación de Big Text , cree una instancia de un objeto NotificationCompat.Builder, como antes, y, a continuación, cree una instancia y agregue un objeto BigTextStyle al objeto NotificationCompat.Builder.To create a Big Text notification, you instantiate a NotificationCompat.Builder object, as before, and then instantiate and add a BigTextStyle object to the NotificationCompat.Builder object. A continuación se muestra un ejemplo:Here is an example:

// 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 pasarse a NotificationCompat.Builder.In this example, the message text and summary text are stored in the BigTextStyle object (textStyle) before it is passed to NotificationCompat.Builder.

Estilo de imagenImage style

El estilo de imagen (también denominado estilo Big Picture ) es un formato de notificación expandido que se puede usar para mostrar una imagen en el cuerpo de una notificación.The Image style (also called the Big Picture style) is an expanded notification format that you can use to display an image in the body of a notification. Por ejemplo, una aplicación de captura de pantalla o una aplicación fotográfica puede usar el estilo de notificación de imagen para proporcionar al usuario una notificación de la última imagen capturada.For example, a screenshot app or a photo app can use the Image notification style to provide the user with a notification of the last image that was captured. 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 de alto máximo, dentro de los límites de la memoria disponible.Note that the maximum height of the Image notification is 256 dp – Android will resize the image to fit into this maximum height restriction, within the limits of available memory.

Al igual que todas las notificaciones de diseño expandidas, las notificaciones de imagen se muestran en primer lugar en un formato compacto que muestra un extracto del texto del mensaje adjunto:Like all expanded layout notifications, Image notifications are first displayed in a compact format that displays an excerpt of the accompanying message text:

La notificación de imagen compacta no muestra ninguna imagen

Cuando el usuario se arrastra hacia abajo en la notificación de imagen , se expande para mostrar una imagen.When the user drags down on the Image notification, it expands to reveal an image. Por ejemplo, esta es la versión expandida de la notificación anterior:For example, here is the expanded version of the previous notification:

Imagen expandida la notificación de imagen

Tenga en cuenta que cuando la notificación se muestra en formato compacto, muestra el texto de la notificación (el texto que se pasa al método SetContentText del generador de notificaciones, como se mostró anteriormente).Notice that when the notification is displayed in compact format, it displays notification text (the text that is passed to the notification builder's SetContentText method, as shown earlier). Sin embargo, cuando la notificación se expande para mostrar la imagen, muestra el texto de resumen sobre la imagen.However, when the notification is expanded to reveal the image, it displays summary text above the image.

Para crear una notificación de imagen , cree una instancia de un objeto NotificationCompat.Builder como antes y, a continuación, cree e inserte un objeto BigPictureStyle en el objeto NotificationCompat.Builder.To create an Image notification, you instantiate a NotificationCompat.Builder object as before, and then create and insert a BigPictureStyle object into the NotificationCompat.Builder object. Por ejemplo:For example:

// 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 método de SetLargeIcon 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.Like the SetLargeIcon method of NotificationCompat.Builder, the BigPicture method of BigPictureStyle requires a bitmap of the image that you want to display in the body of the notification. En este ejemplo, el método DecodeResource de BitmapFactory lee el archivo de imagen ubicado en Resources/drawable/x_bldg. png y lo convierte en un mapa de bits.In this example, the DecodeResource method of BitmapFactory reads the image file located at Resources/drawable/x_bldg.png and converts it into a bitmap.

También puede mostrar imágenes que no están empaquetadas como un recurso.You can also display images that are not packaged as a resource. Por ejemplo, el siguiente código de ejemplo carga una imagen desde la tarjeta SD local y la muestra en una notificación de imagen :For example, the following sample code loads an image from the local SD card and displays it in an Image notification:

// 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, se carga el archivo de imagen que se encuentra en /sdcard/Pictures/My-Tshirt.jpg , se cambia el 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:In this example, the image file located at /sdcard/Pictures/my-tshirt.jpg is loaded, resized to half of its original size, and then converted to a bitmap for use in the notification:

Imagen de camiseta de ejemplo en la notificación

Si no conoce el tamaño del archivo de imagen de antemano, es una buena idea encapsular la llamada a BitmapFactory. DecodeFile en un controlador de excepciones – se puede producir una excepción de OutOfMemoryError si la imagen es demasiado grande para que Android cambie de tamaño.If you don't know the size of the image file in advance, it's a good idea to wrap the call to BitmapFactory.DecodeFile in an exception handler – an OutOfMemoryError exception might be thrown if the image is too large for Android to resize.

Para obtener más información sobre cómo cargar y descodificar imágenes de mapa de bits de gran tamaño, consulte carga eficaz de mapas de bits grandes.For more about loading and decoding large bitmap images, see Load Large Bitmaps Efficiently.

Estilo de bandeja de entradaInbox style

El formato de bandeja de entrada es una plantilla de diseño expandida diseñada para mostrar líneas de texto independientes (por ejemplo, un resumen de bandeja de entrada de correo electrónico) en el cuerpo de la notificación.The Inbox format is an expanded layout template intended for displaying separate lines of text (such as an email inbox summary) in the body of the notification. La notificación de formato de bandeja de entrada se muestra primero en un formato compacto:The Inbox format notification is first displayed in a compact format:

Ejemplo de notificación de bandeja de entrada compacta

Cuando el usuario arrastra hacia abajo en la notificación, se expande para mostrar un resumen de correo electrónico como se muestra en la siguiente captura de pantalla:When the user drags down on the notification, it expands to reveal an email summary as seen in the screenshot below:

Notificación de bandeja de entrada de ejemplo expandida

Para crear una notificación de bandeja de entrada , cree una instancia de un objeto NotificationCompat.Builder, como antes, y agregue un objeto InboxStyle al NotificationCompat.Builder.To create an Inbox notification, you instantiate a NotificationCompat.Builder object, as before, and add an InboxStyle object to the NotificationCompat.Builder. A continuación se muestra un ejemplo:Here is an example:

// 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 objeto InboxStyle (el alto máximo de la notificación de bandeja de entrada es 256 DP).To add new lines of text to the notification body, call the Addline method of the InboxStyle object (the maximum height of the Inbox notification is 256 dp). Tenga en cuenta que, a diferencia del estilo Big Text , el estilo Inbox es compatible con líneas de texto individuales en el cuerpo de la notificación.Note that, unlike Big Text style, the Inbox style supports individual lines of text in the notification body.

También puede usar el estilo de bandeja de entrada para cualquier notificación que necesite Mostrar líneas individuales de texto en un formato expandido.You can also use the Inbox style for any notification that needs to display individual lines of text in an expanded format. Por ejemplo, el estilo de notificación de 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 de bandeja de entrada con nuevas líneas de contenido de notificación (consulte Actualización de un Notificación anterior), en lugar de generar una secuencia continua de notificaciones nuevas, principalmente similares.For example, the Inbox notification style can be used to combine multiple pending notifications into a summary notification – you can update a single Inbox style notification with new lines of notification content (see Updating a Notification above), rather than generate a continuous stream of new, mostly similar notifications.

Configuración de metadatosConfiguring metadata

NotificationCompat.Builder incluye métodos a los que se puede llamar para establecer metadatos sobre la notificación, como la prioridad, la visibilidad y la categoría.NotificationCompat.Builder includes methods that you can call to set metadata about your notification, such as priority, visibility, and category. Android usa esta información — junto con la configuración de preferencias de usuario — para determinar cómo y cuándo mostrar las notificaciones.Android uses this information — along with user preference settings — to determine how and when to display notifications.

Configuración de prioridadPriority settings

Las aplicaciones que se ejecutan en Android 7,1 y menos necesitan establecer la prioridad directamente en la propia notificación.Apps running on Android 7.1 and lower need to set the priority directly on the notification itself. La configuración de prioridad de una notificación determina dos resultados cuando se publica la notificación:The priority setting of a notification determines two outcomes when the notification is published:

  • Donde aparece la notificación en relación con otras notificaciones.Where the notification appears in relation to other notifications. Por ejemplo, las notificaciones de prioridad alta se presentan por encima de las notificaciones de prioridad inferior en el cajón de notificaciones, independientemente de Cuándo se publicó cada notificación.For example, high priority notifications are presented above lower priority notifications in the notifications drawer, regardless of when each notification was published.

  • Si la notificación se muestra en el formato de notificación de cara al día (Android 5,0 y versiones posteriores).Whether the notification is displayed in the Heads-up notification format (Android 5.0 and later). Solo las notificaciones de prioridad alta y máxima se muestran como notificaciones de suscripción.Only high and maximum priority notifications are displayed as Heads-up notifications.

Xamarin. Android define las siguientes enumeraciones para establecer la prioridad de la notificación:Xamarin.Android defines the following enumerations for setting notification priority:

  • NotificationPriority.Max – alerta al usuario de una condición urgente o crítica (por ejemplo, una llamada entrante, una dirección activa o una alerta de emergencia).NotificationPriority.Max – Alerts the user to an urgent or critical condition (for example, an incoming call, turn-by-turn directions, or an emergency alert). En dispositivos Android 5,0 y versiones posteriores, las notificaciones de prioridad máxima se muestran en el formato de cara arriba.On Android 5.0 and later devices, maximum priority notifications are displayed in Heads-up format.

  • NotificationPriority.High – informa al usuario de eventos importantes (como correos electrónicos importantes o la llegada de mensajes de chat en tiempo real).NotificationPriority.High – Informs the user of important events (such as important emails or the arrival of real-time chat messages). En los dispositivos Android 5,0 y versiones posteriores, las notificaciones de prioridad alta se muestran en formato de cara a arriba.On Android 5.0 and later devices, high priority notifications are displayed in Heads-up format.

  • NotificationPriority.Default – notifica al usuario las condiciones que tienen un nivel de importancia medio.NotificationPriority.Default – Notifies the user of conditions that have a medium level of importance.

  • NotificationPriority.Low – para información no urgente a la que el usuario debe estar informado (por ejemplo, recordatorios de actualizaciones de software o actualizaciones de red social).NotificationPriority.Low – For non-urgent information that the user needs to be informed of (for example, software update reminders or social network updates).

  • NotificationPriority.Min – de información general que el usuario solo advierte al ver las notificaciones (por ejemplo, la ubicación o la información meteorológica).NotificationPriority.Min – For background information that the user notices only when viewing notifications (for example, location or weather information).

Para establecer la prioridad de una notificación, llame al método SetPriority del objeto NotificationCompat.Builder, pasando el nivel de prioridad.To set the priority of a notification, call the SetPriority method of the NotificationCompat.Builder object, passing in the priority level. Por ejemplo:For example:

builder.SetPriority (NotificationPriority.High);

En el ejemplo siguiente, la notificación de alta prioridad, "un mensaje importante"In the following example, the high priority notification, "An important message!" aparece en la parte superior del cajón de notificaciones:appears at the top of the notification drawer:

Ejemplo de notificación de alta prioridad

Dado que se trata de una notificación de prioridad alta, también se muestra como una notificación de cara arriba de la pantalla de actividad actual del usuario en Android 5,0:Because this is a high-priority notification, it is also displayed as a Heads-up notification above the user's current activity screen in Android 5.0:

Ejemplo de notificación de suscripción

En el ejemplo siguiente, se muestra la notificación de prioridad baja "pensamiento para el día" bajo una notificación de nivel de batería de prioridad superior:In the next example, the low-priority "Thought for the day" notification is displayed under a higher-priority battery level notification:

Ejemplo de notificación de prioridad baja

Dado que la notificación "pensamiento durante el día" es una notificación de prioridad baja, Android no la mostrará en formato de cabeza.Because the "Thought for the day" notification is a low-priority notification, Android will not display it in Heads-up format.

Nota

En Android 8,0 y versiones posteriores, la prioridad de la configuración del canal de notificación y del usuario determinará la prioridad de la notificación.On Android 8.0 and higher, the priority of the notification channel and user settings will determine the priority of the notification.

Configuración de visibilidadVisibility settings

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.Beginning with Android 5.0, the visibility setting is available to control how much notification content appears on the secure lock screen. Xamarin. Android define las siguientes enumeraciones para establecer la visibilidad de la notificación:Xamarin.Android defines the following enumerations for setting notification visibility:

  • NotificationVisibility.Public – se muestra el contenido completo de la notificación en la pantalla de bloqueo seguro.NotificationVisibility.Public – The full content of the notification is displayed on the secure lock screen.

  • NotificationVisibility.Private – solo se muestra información esencial en la pantalla de bloqueo seguro (como el icono de notificación y el nombre de la aplicación que la registró), pero el resto de los detalles de la notificación están ocultos.NotificationVisibility.Private – Only essential information is displayed on the secure lock screen (such as the notification icon and the name of the app that posted it), but the rest of the notification's details are hidden. Todas las notificaciones tienen como valor predeterminado NotificationVisibility.Private.All notifications default to NotificationVisibility.Private.

  • NotificationVisibility.Secret – no se muestra nada en la pantalla de bloqueo seguro, ni siquiera en el icono de notificación.NotificationVisibility.Secret – Nothing is displayed on the secure lock screen, not even the notification icon. El contenido de la notificación solo está disponible después de que el usuario desbloquea el dispositivo.The notification content is available only after the user unlocks the device.

Para establecer la visibilidad de una notificación, las aplicaciones llaman al método SetVisibility del objeto NotificationCompat.Builder, pasando la configuración de visibilidad.To set the visibility of a notification, apps call the SetVisibility method of the NotificationCompat.Builder object, passing in the visibility setting. Por ejemplo, esta llamada a SetVisibility hace que la notificación Private:For example, this call to SetVisibility makes the notification Private:

builder.SetVisibility (NotificationVisibility.Private);

Cuando se publica una notificación de Private, solo se muestra el nombre y el icono de la aplicación en la pantalla de bloqueo seguro.When a Private notification is posted, only the name and icon of the app is displayed on the secure lock screen. En lugar del mensaje de notificación, el usuario ve "desbloquear el dispositivo para ver esta notificación":Instead of the notification message, the user sees "Unlock your device to see this notification":

Desbloquear el mensaje de notificación del dispositivo

En este ejemplo, NotificationsLab es el nombre de la aplicación de origen.In this example, NotificationsLab is the name of the originating app. Esta versión censurada 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.This redacted version of the notification appears only when the Lock screen is secure (i.e., secured via PIN, pattern, or password) – if the lock screen is not secure, the full content of the notification is available on the lock screen.

Configuración de categoríasCategory settings

A partir de Android 5,0, las categorías predefinidas están disponibles para clasificar y filtrar las notificaciones.Beginning with Android 5.0, predefined categories are available for ranking and filtering notifications. Xamarin. Android proporciona las siguientes enumeraciones para estas categorías:Xamarin.Android provides the following enumerations for these categories:

  • Notification.CategoryCall – llamada telefónica entrante.Notification.CategoryCall – Incoming phone call.

  • Notification.CategoryMessage – mensaje de texto entrante.Notification.CategoryMessage – Incoming text message.

  • Notification.CategoryAlarm – una condición de alarma o una expiración del temporizador.Notification.CategoryAlarm – An alarm condition or timer expiration.

  • Notification.CategoryEmail – mensaje de correo electrónico entrante.Notification.CategoryEmail – Incoming email message.

  • Notification.CategoryEvent – un evento de calendario.Notification.CategoryEvent – A calendar event.

  • Notification.CategoryPromo – un mensaje o anuncio promocional.Notification.CategoryPromo – A promotional message or advertisement.

  • Notification.CategoryProgress – el progreso de una operación en segundo plano.Notification.CategoryProgress – The progress of a background operation.

  • Notification.CategorySocial – la actualización de redes sociales.Notification.CategorySocial – Social networking update.

  • Notification.CategoryError – error de una operación en segundo plano o de un proceso de autenticación.Notification.CategoryError – Failure of a background operation or authentication process.

  • Notification.CategoryTransport – la actualización de la reproducción multimedia.Notification.CategoryTransport – Media playback update.

  • Notification.CategorySystem – reservado para uso del sistema (estado del sistema o del dispositivo).Notification.CategorySystem – Reserved for system use (system or device status).

  • Notification.CategoryService – indica que se está ejecutando un servicio en segundo plano.Notification.CategoryService – Indicates that a background service is running.

  • Notification.CategoryRecommendation – un mensaje de recomendación relacionado con la aplicación que se está ejecutando actualmente.Notification.CategoryRecommendation – A recommendation message related to the currently running app.

  • Notification.CategoryStatus – información sobre el dispositivo.Notification.CategoryStatus – Information about the device.

Cuando se ordenan las notificaciones, la prioridad de la notificación tiene prioridad sobre la configuración de la categoría.When notifications are sorted, the notification's priority takes precedence over its category setting. Por ejemplo, una notificación de alta prioridad se mostrará como un aviso, incluso si pertenece a la categoría Promo.For example, a high-priority notification will be displayed as Heads-up even if it belongs to the Promo category. Para establecer la categoría de una notificación, se llama al método SetCategory del objeto NotificationCompat.Builder, pasando el valor de la categoría.To set the category of a notification, you call the SetCategory method of the NotificationCompat.Builder object, passing in the category setting. Por ejemplo:For example:

builder.SetCategory (Notification.CategoryCall);

La característica no molestar (novedad en Android 5,0) filtra las notificaciones en función de las categorías.The Do not disturb feature (new in Android 5.0) filters notifications based on categories. Por ejemplo, la pantalla no molestar en configuración permite al usuario excluir las notificaciones de llamadas telefónicas y mensajes:For example, the Do not disturb screen in Settings allows the user to exempt notifications for phone calls and messages:

No molestar modificadores de pantalla

Cuando el usuario configura no molesta para bloquear todas las interrupciones excepto las llamadas telefónicas (como se muestra en la captura de pantalla anterior), Android permite que se presenten notificaciones con un valor de categoría de Notification.CategoryCall mientras el dispositivo esté en no molestar. modo.When the user configures Do not disturb to block all interrupts except for phone calls (as illustrated in the above screenshot), Android allows notifications with a category setting of Notification.CategoryCall to be presented while the device is in Do not disturb mode. Tenga en cuenta que las notificaciones de Notification.CategoryAlarm nunca se bloquean en el modo no molestar .Note that Notification.CategoryAlarm notifications are never blocked in Do not disturb mode.

En el ejemplo LocalNotifications se muestra cómo usar NotificationCompat.Builder para iniciar una segunda actividad desde una notificación.The LocalNotifications sample demonstrates how to use NotificationCompat.Builder to launch a second activity from a notification. Este código de ejemplo se explica en el tutorial uso de notificaciones locales en Xamarin. Android .This sample code is explained in the Using Local Notifications in Xamarin.Android walkthrough.

Estilos de notificaciónNotification styles

Para crear notificaciones de estilo Big Text, Imageo Inbox con NotificationCompat.Builder, la aplicación debe usar las versiones de compatibilidad de estos estilos.To create Big Text, Image, or Inbox style notifications with NotificationCompat.Builder, your app must use the compatibility versions of these styles. Por ejemplo, para usar el estilo Big Text , cree instancias de NotificationCompat.BigTextstyle:For example, to use the Big Text style, instantiate NotificationCompat.BigTextstyle:

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 de imagen y bandeja de entrada , respectivamente.Similarly, your app can use NotificationCompat.InboxStyle and NotificationCompat.BigPictureStyle for Inbox and Image styles, respectively.

Categoría y prioridad de la notificaciónNotification priority and category

NotificationCompat.Builder admite el método SetPriority (disponible a partir de Android 4,1).NotificationCompat.Builder supports the SetPriority method (available starting with Android 4.1). Sin embargo, el método SetCategory no es compatible con NotificationCompat.Builder porque las categorías forman parte del nuevo sistema de metadatos de notificación que se presentó en Android 5,0.However, the SetCategory method is not supported by NotificationCompat.Builder because categories are part of the new notification metadata system that was introduced in 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 condicionalmente a SetCategory cuando el nivel de API es igual o mayor que Android 5,0 (nivel de API 21):To support older versions of Android, where SetCategory is not available, your code can check the API level at runtime to conditionally call SetCategory when the API level is equal to or greater than Android 5.0 (API level 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 está establecida en Android 5,0 y la versión mínima de Android está establecida en Android 4,1 (nivel de API 16) .In this example, the app's Target Framework is set to Android 5.0 and the Minimum Android Version is set to Android 4.1 (API Level 16). Como SetCategory está disponible en el nivel de API 21 y versiones posteriores, este código de ejemplo llamará SetCategory solo cuando esté disponible – no llamará a SetCategory cuando el nivel de API sea inferior a 21.Because SetCategory is available in API level 21 and later, this example code will call SetCategory only when it is available – it will not call SetCategory when the API level is less than 21.

Visibilidad de la pantalla de bloqueoLock screen visibility

Dado que Android no admitía las notificaciones de la pantalla de bloqueo antes de Android 5,0 (nivel de API 21), NotificationCompat.Builder no admite el método SetVisibility.Because Android did not support lock screen notifications before Android 5.0 (API level 21), NotificationCompat.Builder does not support the SetVisibility method. Como se explicó anteriormente para SetCategory, el código puede comprobar el nivel de API en tiempo de ejecución y llamar a SetVisiblity solo cuando está disponible:As explained above for SetCategory, your code can check the API level at runtime and call SetVisiblity only when it is available:

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

ResumenSummary

En este artículo se explica cómo crear notificaciones locales en Android.This article explained how to create local notifications in Android. Se ha descrito la anatomía de una notificación, se ha explicado cómo usar NotificationCompat.Builder para crear notificaciones, cómo aplicar estilo a las notificaciones en formato grande, texto de gran tamaño, imagen y formatos de bandeja de entrada , cómo establecer la configuración de los metadatos de notificación, como prioridad, visibilidad y categoría, y cómo iniciar una actividad desde una notificación.It described the anatomy of a notification, it explained how to use NotificationCompat.Builder to create notifications, how to style notifications in large icon, Big Text, Image and Inbox formats, how to set notification metadata settings such as priority, visibility, and category, and how to launch an activity from a notification. En este artículo también se describe cómo funciona esta configuración de notificaciones con las nuevas características de cabeza de seguridad, pantalla de bloqueo y no molestar que se introdujeron en Android 5,0.This article also described how these notification settings work with the new Heads-up, lock screen, and Do not disturb features introduced in Android 5.0. Por último, aprendió a usar NotificationCompat.Builder para mantener la compatibilidad con las notificaciones con versiones anteriores de Android.Finally, you learned how to use NotificationCompat.Builder to maintain notification compatibility with earlier versions of Android.

Para obtener instrucciones sobre el diseño de notificaciones para Android, vea notificaciones.For guidelines about designing notifications for Android, see Notifications.