Inicio rápido: enviar una notificación del sistema (HTML)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

Nota ¿No usas JavaScript? Consulta el tema de Inicio rápido: enviar una notificación del sistema (XAML).

Una notificación del sistema es una interfaz de usuario emergente que aparece en la pantalla y que permite que la aplicación se comunique con el usuario cuando este se encuentra en otra aplicación, en la pantalla Inicio o, en el caso de Windows, en el escritorio. Este inicio rápido te guía a través de los pasos para definir y mostrar una notificación del sistema. Estas acciones se demuestran mediante una notificación local, que es la notificación más simple de implementar. Abordamos los siguientes pasos:

Especificar una plantilla para la notificación
Recuperar el contenido XML en blanco de la plantilla
Agregar texto a la notificación
Agregar una imagen a la notificación
Configurar una duración para la notificación
Especificar audio para anexarlo a la notificación
Proporcionar la información contextual que se usa cuando la notificación activa la aplicación
Enviar la notificación del sistema como una notificación local

Nota En este inicio rápido, manipularás el contenido de la notificación directamente a través del Document Object Model (DOM) XML. Un enfoque opcional se encuentra disponible a través de la biblioteca NotificationsExtensions, que presenta el contenido XML como propiedades de objeto, incluido IntelliSense. Para obtener más información, consulta Inicio rápido: usar la biblioteca NotificationsExtensions en el código. Para ver el código de este inicio rápido expresado mediante NotificationsExtensions, consulta la muestra de notificaciones del sistema.

Nota Cuando pruebes la funcionalidad del código de las notificaciones del sistema con Microsoft Visual Studio, debes usar la opción de depuración Equipo local o Equipo remoto en un equipo con Windows x86, x64 o Windows en tiempo de ejecución. No puedes usar la opción de función de depuración del simulador de Visual Studio porque tu código se compilará y se ejecutará en el simulador, pero la notificación del sistema no aparecerá.

Requisitos previos

Para comprender este tema, necesitarás:

Conocimientos prácticos sobre los términos y conceptos relacionados con las notificaciones del sistema. Para más información, consulta el tema de introducción a las notificaciones del sistema.
La opción Compatibilidad con notificaciones del sistema debe establecerse en "true" en el manifiesto de la aplicación ("Sí" en el editor de manifiestos de Visual Studio) para poder enviar o recibir notificaciones del sistema. Para más información, consulta Cómo elegir recibir notificaciones del sistema.
Estar familiarizado con XML y su manipulación mediante API de Document Object Model (DOM).
Estar familiarizado con el esquema XML de la notificación del sistema. Para más información, consulta el tema sobre el esquema de notificaciones del sistema.
Capacidad para crear una aplicación de la Tienda Windows con JavaScript básica mediante las API de Windows en tiempo de ejecución. Para obtener más información, consulta el tema sobre cómo crear tu primera aplicación de la Tienda Windows con JavaScript.

Instrucciones

1. Opcional: declarar una variable de espacio de nombres

Este paso te proporciona un nombre corto para que lo uses en lugar del nombre completo del espacio de nombres. Es el equivalente de una instrucción "using" en C# o de la instrucción "Imports" en Visual Basic. Esto permite simplificar el código.

Nota El resto del código de este inicio rápido supone que se ha declarado esta variable.


var notifications = Windows.UI.Notifications;

2. Seleccionar una plantilla para la notificación del sistema y recuperar su contenido XML

Elige una plantilla del catálogo de plantillas proporcionado por el sistema que se ajuste a las necesidades de tu contenido. Para obtener la lista completa de plantillas, consulta la enumeración ToastTemplateType. Ten en cuenta que cada notificación individual que envíes puede usar una plantilla diferente.

Nota En Windows Phone 8.1 solo se admite una variación de la plantilla toastText02. Acepta dos cadenas de texto, la primera de las cuales se representa con texto en negrita. Sin embargo, como ambas están en la misma línea, solo se debe usar una cadena corta o dos cadenas muy cortas para evitar concatenaciones.

Este ejemplo, aplicado a Windows, usa la plantilla toastImageAndText01, que requiere una imagen y una cadena de texto. Aquí te mostramos un ejemplo:

ToastImageAndText01


var template = notifications.ToastTemplateType.toastImageAndText01;
var toastXml = notifications.ToastNotificationManager.getTemplateContent(template);

El método getTemplateContent devuelve un XmlDocument. El código anterior recupera el siguiente esqueleto XML, para el que proporcionarás detalles en los pasos siguientes a través de funciones estándar de Document Object Model (DOM):


<toast>
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</toast>

3. Proporcionar contenido de texto para la notificación

Este ejemplo primero recupera todos los elementos de la plantilla cuyo nombre de etiqueta es "text". La plantilla toastImageAndText01 contiene una sola cadena de texto que el código asigna. Esta cadena puede ajustarse sobre un máximo de tres líneas y la longitud de la cadena debe establecerse en consecuencia para evitar que se trunque.

   
var toastTextElements = toastXml.getElementsByTagName("text");
toastTextElements[0].appendChild(toastXml.createTextNode("Hello World!"));

4. Proporcionar una imagen para la notificación

Este código primero recupera todos los elementos de la plantilla cuyo nombre de etiqueta es "image". Una plantilla de notificación del sistema, como toastImageAndText01, contiene como máximo una imagen. Ten en cuenta que no todas las plantillas de notificación del sistema contienen imágenes; algunas solo contienen texto.


var toastImageElements = toastXml.getElementsByTagName("image");

Pueden usarse imágenes del paquete de la aplicación, del almacenamiento local de la aplicación o de la Web. Se muestran versiones de este paso para cada origen de imagen. Las imágenes deben tener un tamaño inferior a 200 KB y contener menos de 1024 x 1024 píxeles. Para más información, consulta el tema sobre los tamaños de las imágenes de iconos y notificaciones del sistema.

El siguiente código usa una imagen local del paquete de la aplicación. Este tipo de imagen se incluye en el archivo de solución de Visual Studio y se empaqueta como parte de la aplicación. Se accede a estas imágenes con el prefijo "ms-appx:///". Como procedimiento recomendado, también asignamos texto alternativo opcional por motivos de accesibilidad, como lectores de pantalla.

Importante La imagen "redWide.png" que se usa aquí solo es un ejemplo y no se incluye en un proyecto de Microsoft Visual Studio. Tendrás que reemplazar "redWide.png" por el nombre de una imagen real de tu propiedad que hayas agregado al proyecto antes de intentar enviar esta notificación del sistema.


toastImageElements[0].setAttribute("src", "ms-appx:///images/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

El siguiente código usa una imagen local del almacenamiento local de la aplicación. La aplicación guarda este tipo de imagen en su almacenamiento local. Esta es la ubicación devuelta por Windows.Storage.ApplicationData.current.localFolder. Se accede a estas imágenes con el prefijo "ms-appdata:///local/". Como lo hicimos anteriormente, también asignamos texto alternativo opcional por motivos de accesibilidad, como lectores de pantalla.


toastImageElements[0].setAttribute("src", "ms-appdata:///local/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

El siguiente código usa una imagen web. Se accede a estas imágenes con el protocolo "http://" para especificar la ruta de acceso de la imagen. También puedes usar el protocolo "https://".


toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");
toastImageElements[0].setAttribute("alt", "red graphic");

Puedes usar el atributo baseUri opcional para especificar una ruta de acceso raíz, como "https://www.microsoft.com/", que esté combinada con cualquier Identificador uniforme de recursos (URI) relativo especificado en los atributos src de las imágenes. Este atributo se puede establecer en el elemento visual (para aplicarlo a toda la notificación) o en el elemento binding (para aplicarlo a ese enlace). Si baseUri se establece en ambos, el valor de binding invalida el valor de visual.

Si baseUri se estableciera en "https://www.microsoft.com/", esta línea en el código de ejemplo:

toastImageElements[0].setAttribute("src", "https://www.microsoft.com/redWide.png");

se podría acortar así:

toastImageElements[0].setAttribute("src", "redWide.png");

5. Opcional: especificar la duración de una notificación del sistema

De forma opcional, puedes establecer una duración para mostrar la notificación del sistema. Hay dos valores: "short" (valor predeterminado) y "long". Usa "long" solo si tu notificación forma parte de un escenario tal como una llamada entrante o un aviso de cita. Para más información, consulta el tema de introducción a las notificaciones del sistema.

Nota En Windows Phone 8.1 no se admiten varias duraciones: todas las notificaciones del sistema deben durar lo mismo. Si este atributo se incluye en una notificación del sistema del teléfono, se omitirá.

Nota La duración predeterminada es "short", de modo que normalmente agregarías este atributo solamente para establecer la duración en "long".


var toastNode = toastXml.selectSingleNode("/toast");
toastNode.setAttribute("duration", "long");

6. Opcional: especificar el audio de la notificación del sistema

Para obtener más información sobre el audio de notificaciones del sistema, consulta el Catálogo de opciones de audio de notificaciones del sistema.

De manera predeterminada, Windows reproduce un breve sonido cuando se muestra la notificación del sistema. Tienes la opción de especificar otro sonido de un conjunto de sonidos proporcionados por el sistema, o bien puedes optar por no usar ninguno. En Windows Phone 8.1, puedes especificar un sonido personalizado. Para obtener más información, consulta el Catálogo de opciones de audio de notificaciones del sistema.

Una pantalla recuperada por medio de getTemplateContent no contiene un elemento audio, por lo que debes definirlo y agregarlo a la carga útil XML. El archivo de sonido se especifica mediante el prefijo "ms-winsoundevent:", o bien, en Windows Phone 8.1, una ruta de acceso que usa el prefijo "ms-appx:///" o "ms-appdata:///". En este ejemplo se crea un elemento audio y se selecciona el elemento toast que será su elemento primario.


var toastNode = toastXml.selectSingleNode("/toast");                        
var audio = toastXml.createElement("audio");

Este ejemplo especifica un sonido no predeterminado.

audio.setAttribute("src", "ms-winsoundevent:Notification.IM");

Este ejemplo especifica que no debe reproducirse ningún sonido.

audio.setAttribute("silent", "true");

En el caso de una notificación del sistema de larga duración, el sonido puede repetirse en bucle en lugar de reproducirse solo una vez. Ten en cuenta que el audio en bucle solo es válido para las notificaciones del sistema de larga duración. En el conjunto de sonidos definidos por el sistema se incluyen los sonidos específicos que pueden usarse en bucle. Este ejemplo especifica un bucle de sonido.

Nota Como no admite notificaciones del sistema de larga duración, Windows Phone 8.1 no admite audio en bucle.


toastNode.setAttribute("duration", "long");

var audio = toastXml.createElement("audio");
audio.setAttribute("src", "ms-winsoundevent:Notification.Looping.Alarm");
audio.setAttribute("loop", "true");

Una vez definido tu elemento de audio, debes anexarlo a la carga XML de tu notificación del sistema como elemento secundario de toast, como se muestra aquí.

toastNode.appendChild(audio);

7. Especifica los parámetros de inicio de la aplicación

Cuando el usuario hace clic en la notificación del sistema, espera que la aplicación se inicie, con una vista relacionada con el contenido de la notificación. Para realizar esto, usa el atributo launch del elemento de notificación del sistema, el cual proporciona una cadena que se pasa de la notificación del sistema a la aplicación cuando esta se inicia a través de la notificación del sistema. La cadena no tiene una forma específica y está definida por la aplicación. La aplicación debe comprobar esa cadena como un argumento cada vez que se activa, ajusta la vista u operación en consecuencia.


toastXml.selectSingleNode("/toast").setAttribute("launch", '{"type":"toast","param1":"12345","param2":"67890"}');

Nota En Windows Phone Silverlight 8.1, el valor de la cadena de inicio se anexa al URI de la página de inicio predeterminada. Por ejemplo, si proporcionas la cadena de inicio "?conversation= 71", da como resultado un URI como /MainPage.xaml?conversation=71. Por lo tanto, la cadena de inicio también debe ser una cadena de consulta válida; de lo contrario, se emite una excepción.

8. Crea la notificación del sistema basada en el contenido XML que has especificado.

var toast = new notifications.ToastNotification(toastXml);

9. Envía la notificación del sistema.

 
 var toastNotifier = notifications.ToastNotificationManager.createToastNotifier();
 toastNotifier.show(toast);

Nota En Windows Phone Silverlight 8.1, no se muestra una notificación del sistema si la aplicación en primer plano actual es el autor de la llamada del método ToastNotifier.Show. En ese caso, la notificación del sistema debe usarse principalmente por un agente en segundo plano.

Nota: El color de fondo que se aplica a la notificación del sistema es el color de fondo declarado por el icono de la aplicación en el manifiesto de la aplicación. Si quieres obtener más información, consulta el tema de inicio rápido: crear un icono predeterminado con el editor de manifiestos de Visual Studio.

Resumen y siguientes pasos

En este inicio rápido, enviaste la notificación del sistema local al usuario.

Este inicio rápido envió la notificación del sistema como una notificación local, lo que hace que sea el tipo de notificación más simple de implementar y te permite ver los resultados rápidamente. También deberías explorar los otros métodos de entrega de notificaciones del sistema: programadas y de inserción. Para más información, consulta el tema sobre la entrega de notificaciones.