Integrar la aplicación UWP de Windows al SDK del lado cliente para las notificaciones de usuario (obsoleto)
Importante
La API de notificaciones de Microsoft Graph está en desuso y dejará de devolver datos a finales de enero de 2022. Para obtener una experiencia de notificación alternativa, consulte Microsoft Azure Notification Hubs. Para obtener más información, consulte la entrada de blog Retirada de la API de notificaciones de Microsoft Graph (beta).
Después de registrar la aplicación en el Centro de administración Microsoft Entra e incorporar las experiencias entre dispositivos en el Centro de desarrollo de partners, el siguiente paso es integrar la aplicación cliente con el SDK del lado cliente para aplicaciones para UWP de Windows.
Con el SDK de cliente, la aplicación puede realizar los pasos de registro necesarios para empezar a recibir notificaciones publicadas desde el servidor de aplicación dirigidas al usuario que ha iniciado sesión. Luego, el SDK administra las notificaciones en el lado cliente y se encarga de recibir nuevas notificaciones entrantes, administrar el estado de notificaciones para conseguir escenarios como el descarte universal y recuperar el historial completo de notificaciones.
Nuevo flujo de notificaciones entrantes
Para recibir nuevas notificaciones entrantes, se muestra el flujo de datos en el siguiente diagrama.
Este proceso incluye algunos componentes:
- Servidor de aplicaciones: el back-end de la aplicación
- Cliente de la aplicación: el front-end de la aplicación (una aplicación UWP, una aplicación de Android o una aplicación de iOS)
- Notificaciones de Microsoft Graph: el componente del servicio que permite publicar, almacenar y sincronizar las notificaciones de usuario entre diferentes instancias de clientes de la aplicación en varios dispositivos y plataformas
- WNS: el servicio de notificaciones de inserción de Windows que usa las notificaciones de Microsoft Graph para señalar a los clientes
El diagrama muestra los pasos siguientes:
- Lógica de la aplicación. Este paso captura lo que activa la notificación que se publicará para el usuario. Esta es la lógica específica de la aplicación y puede ser una actualización de eventos o datos sobre algo más en Microsoft Graph, como un evento de calendario o una asignación de tarea, o bien el servicio de aplicaciones que quiere notificar al usuario.
- El servidor de aplicaciones publica una notificación para el usuario de destino a través de la API de notificaciones de Microsoft Graph. Para obtener más información, vea integración del lado servidor.
- Al recibir la solicitud web que contiene la nueva notificación, las notificaciones de Microsoft Graph conservan el contenido de la notificación de forma segura en la nube para esta aplicación y este usuario.
- Para cada instancia del cliente de la aplicación que se subscriba para recibir notificaciones para este usuario, las notificaciones de Microsoft Graph envían una señal para notificar al cliente de la aplicación, mediante el servicio de inserción nativo que proporciona el sistema operativo. En este caso, la aplicación es una aplicación UWP de Windows y usa la notificación de inserción sin procesar de WNS para enviar la señal.
- Después de que la notificación de inserción entrante señale la aplicación, se pide al SDK que obtenga los cambios en el almacén de notificaciones de usuario.
- El SDK establece una conexión segura y conforme con el almacén de notificaciones de usuario en Microsoft Graph.
- El SDK obtiene los cambios de datos, en este caso, el contenido de la nueva notificación.
- El SDK desencadena la devolución de la llamada de evento para notificar a la aplicación cuando se recuperen correctamente los cambios.
- Lógica de la aplicación. Este paso captura lo que la aplicación decide realizar dentro de la devolución de llamada de evento. Normalmente, esto resulta en cambios de datos de la aplicación local y actualizaciones de la interfaz de usuario local. En este caso, la aplicación suele crear un elemento emergente de notificación del sistema para notificar al usuario sobre el contenido de la notificación.
Flujo de actualización de notificaciones
Una de las principales ventajas del uso de las notificaciones de Microsoft Graph es que conservan las notificaciones en la nube de forma segura y las convierte en un tipo de recurso con estado. Por ello, puede ayudar a la aplicación a administrar y sincronizar el estado correcto de las notificaciones en varios dispositivos para el mismo usuario que ha iniciado sesión en varios dispositivos. Cuando se marca una notificación como descartada o leída en un dispositivo, los demás dispositivos pueden ser notificados en tiempo real. "Controlada una vez, descartada en todas partes" puede ser una verdadera promesa como parte de la experiencia de notificación de los usuarios.
El siguiente diagrama muestra el flujo de datos para cambiar el estado de una notificación o eliminar la notificación en un dispositivo, la recepción y manipulación del cambio de estado o la eliminación en otro dispositivo.
Observe que la segunda parte del flujo es similar al flujo para controlar las nuevas notificaciones entrantes. Esto es por diseño: el patrón de programación del SDK está diseñado para que el cliente de la aplicación pueda controlar todos los tipos de cambios de datos de notificación de usuario (nuevas notificaciones entrantes, cambios de estado de notificación, notificaciones eliminadas) de forma similar.
El diagrama muestra los pasos siguientes:
- Lógica de la aplicación. Algo desencadena el cambio o la eliminación de la notificación. En general, cualquier evento puede desencadenar el cambio de una notificación.
- La aplicación llama al SDK del cliente para actualizar o eliminar una notificación. Actualmente, exponemos dos propiedades sobre los cambios de estado, userActionState y readState, pero la aplicación puede definir estos estados y cuándo deben actualizarse. Por ejemplo, cuando un usuario descarta la notificación emergente, puede actualizar userActionState como Descartado. Cuando un usuario hace clic en la notificación emergente e inicia la aplicación para consumir contenido de aplicación correspondiente, puede actualizar userActionState como Activado y readState como Leído.
- Después de llamar a la API correspondiente para actualizar o eliminar una notificación, el SDK realizará una llamada al almacén de notificaciones del usuario en la nube para distribuir este cambio a las demás instancias de cliente de la aplicación con el mismo usuario que ha iniciado sesión.
- Al recibir la solicitud de actualización o eliminación de un cliente, las notificaciones de Microsoft Graph actualizan el almacén de notificaciones e identifican las demás instancias del cliente de la aplicación que se suscribió a este cambio.
- Para cada suscripción del cliente de la aplicación, las notificaciones de Microsoft Graph envían una señal para notificar al cliente de la aplicación, mediante el servicio de inserción nativo que proporciona el sistema operativo. En este caso, se trata de una aplicación UWP de Windows que usa la notificación de inserción sin procesar de WNS para enviar la señal.
- Después de que la notificación de inserción entrante señale la aplicación, se pide al SDK que obtenga los cambios en el almacén de notificaciones de usuario.
- El SDK establece una conexión segura y conforme con el almacén de notificaciones de usuario en Microsoft Graph.
- El SDK obtiene los cambios de datos, en este caso, las actualizaciones de estado de notificación o las eliminaciones de las notificaciones.
- El SDK desencadena la devolución de la llamada de evento para notificar a la aplicación cuando se recuperen correctamente los cambios.
- Lógica de la aplicación. Este paso captura lo que la aplicación decide realizar dentro de la devolución de llamada de evento. Normalmente, esto resulta en cambios de datos de la aplicación local y actualizaciones de la interfaz de usuario local. En este caso, como hay actualizaciones de notificación, la aplicación debe actualizar la interfaz de usuario local para reflejar el cambio de estado. Por ejemplo, si una notificación se marca como activada, puede quitar la correspondiente notificación del sistema emergente en el centro de actividades de Windows para lograr el "controlada una vez, descartada en todas partes".
Para obtener más información sobre las notificaciones de Microsoft Graph, vea Introducción a las notificaciones de Microsoft Graph. Para obtener más información sobre los pasos necesarios para integrar las notificaciones de Microsoft Graph de un extremo a otro, vea la Introducción a la integración de las notificaciones de Microsoft Graph.
Agregar el SDK al proyecto
En Windows, el SDK del lado cliente es un paquete NuGet que envía fuera del sistema operativo Windows. Esta API está disponible en C#, C++ y WinJS.
Descargue el paquete NuGet para el SDK de las notificaciones de Microsoft Graph para aplicaciones Windows en nuget o siga estos pasos para descargarlo desde la solución de la aplicación en Visual Studio:
En Visual Studio, haga clic derecho en el proyecto para mostrar el menú contextual y, después, haga clic en Administrar paquetes NuGet....
Vaya a la pestaña Examinar y busque Microsoft.ConnectedDevices.UserNotifications.
Verá el SDK del lado cliente de las notificaciones de Microsoft Graph en los resultados de búsqueda. Haga clic en el botón Instalar para instalarlo.
Cuando se completa la instalación, el paquete se muestra en Referencias en el Explorador de soluciones.
Para obtener más información sobre cómo incluir y consumir paquetes NuGet desde la aplicación UWP, vea:
Iniciar las Plataformas de dispositivos conectados
El SDK del lado cliente se basa en una infraestructura llamada Plataforma de dispositivos conectados. Para poder usar las características, se debe inicializar la plataforma de la aplicación. Los pasos de inicialización deberían aparecer en el método de la clase principal OnLaunched u onActivated, porque estos son necesarios antes de que puedan tener lugar los escenarios de notificación.
Debe crear e inicializar la plataforma con una instancia de la clase ConnectedDevicesPlatform. Antes de hacerlo, asegúrese de conectar los controladores de eventos, como se muestra, porque después de iniciar la plataforma, puede que los eventos comiencen a activarse.
var platform = new ConnectedDevicesPlatform();
platform.AccountManager.AccessTokenRequested += AccountManager_AccessTokenRequestedAsync;
platform.AccountManager.AccessTokenInvalidated += AccountManager_AccessTokenInvalidated;
platform.NotificationRegistrationManager.NotificationRegistrationStateChanged += NotificationRegistrationManager_NotificationRegistrationStateChanged;
platform.Start();
Controlar el token de acceso de la cuenta
Todas las llamadas web que realiza el SDK, incluidas las llamadas para recuperar el contenido de una nueva notificación entrante, actualizar los estados de notificación y mucho más, leen de o escriben en los datos del usuario y, por ello, siempre requieren un token de acceso válido. El SDK requiere que controle los eventos siguientes, invocados cuando se solicita o se invalida un token de acceso, para asegurarse de que una vez iniciada la plataforma, el token de acceso para el usuario se controla correctamente.
AccountManager_AccessTokenRequestedAsync
Para una implementación completa, vea el ejemplo de aplicación de Windows.
private async void AccountManager_AccessTokenRequestedAsync(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenRequestedEventArgs args)
{
private List<Account> accounts = new List<Account>();
var account = accounts.Find((x) => x.EqualsTo(args.Request.Account));
if (account != null)
{
try
{
var accessToken = await account.GetAccessTokenAsync(args.Request.Scopes);
args.Request.CompleteWithAccessToken(accessToken);
}
catch (Exception ex)
{
args.Request.CompleteWithErrorMessage(ex.Message);
}
}
}
AccountManager_AccessTokenInvalidated
Para una implementación completa, vea el ejemplo de aplicación de Windows.
private void AccountManager_AccessTokenInvalidated(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenInvalidatedEventArgs args)
{
Logger.Instance.LogMessage($"Token Invalidated. AccountId: {args.Account.Id}, AccountType: {args.Account.Id}, scopes: {string.Join(" ", args.Scopes)}");
}
Controlar la expiración del registro push
Las notificaciones de Microsoft Graph usan WNS, la plataforma de inserción nativa de Windows, para señalar a la aplicación cliente cambios de datos de notificaciones del usuario. Esto ocurre cuando nuevas notificaciones entrantes se publican desde el servidor de aplicaciones o cuando se actualiza el estado de las notificaciones en otro dispositivo con el mismo usuario que ha iniciado sesión en un escenario con varios dispositivos.
Por este motivo, es necesario un canal WNS válido que permita que las notificaciones de inserción sin procesar lleguen correctamente. La siguiente devolución de llamada controla la expiración del canal de inserción de WNS.
NotificationRegistrationManager_NotificationRegistrationStateChanged
Para una implementación completa, vea el ejemplo de aplicación de Windows.
private async void NotificationRegistrationManager_NotificationRegistrationStateChanged(ConnectedDevicesNotificationRegistrationManager sender, ConnectedDevicesNotificationRegistrationStateChangedEventArgs args)
{
if ((args.State == ConnectedDevicesNotificationRegistrationState.Expired) || (args.State == ConnectedDevicesNotificationRegistrationState.Expiring))
{
var account = m_accounts.Find((x) => x.EqualsTo(args.Account));
if (account != null)
{
await account.RegisterAccountWithSdkAsync();
}
}
}
Hacer que el usuario inicie sesión
Las notificaciones de Microsoft Graph, como muchos otros tipos de recursos de Microsoft Graph, están centralizadas en los usuarios. Para que la aplicación se suscriba y empiece a recibir notificaciones para el usuario que ha iniciado sesión, primero debe obtener un token de OAuth válido que se usará en el proceso de registro. Puede usar el método preferido para crear y administrar los tokens de OAuth. La aplicación de ejemplo usa ADAL.
Si usa una cuenta de Microsoft, deberá incluir los permisos siguientes en la solicitud de inicio de sesión: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry y https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.
Si usa una cuenta de Microsoft Entra, deberá solicitar la siguiente audiencia: https://cdpcs.access.microsoft.com.
Agregar la cuenta del usuario a la plataforma
Debe registrar la cuenta del usuario que ha iniciado sesión con el SDK. Esto implica agregar la cuenta y registrar un canal de inserción para recibir las notificaciones de inserción iniciales por WNS.
var account = new ConnectedDevicesAccount(accountId, accountType);
var addResult = await platform.AccountManager.AddAccountAsync(account);
if (addResult.Status != ConnectedDevicesAccountAddedStatus.Success)
{
throw new Exception("Add account failed with " + addResult.Status + "!");
}
var pushChannel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
ConnectedDevicesNotificationRegistration registration = new ConnectedDevicesNotificationRegistration();
registration.Type = ConnectedDevicesNotificationType.WNS;
registration.Token = pushChannel.Uri;
var registerResult = await platform.NotificationRegistrationManager.RegisterAsync(account, registration);
if (registerResult.Status != ConnectedDevicesNotificationRegistrationStatus.Success)
{
throw new Exception("Register push channel failed with " + registerResult.Status + "!");
}
Suscribirse para recibir notificaciones de usuario
Deberá crear una instancia de un objeto UserDataFeed para la aplicación de este usuario que ha iniciado sesión. La aplicación se identifica con el Id. de aplicación multiplataforma que proporcionó durante el proceso de incorporación de las experiencias en varios dispositivos.
UserDataFeed feed = UserDataFeed.GetForAccount(account, platform, "YOUR_HOST_HERE");
var scopes = new List<UserDataFeedSyncScope> { UserNotificationChannel.SyncScope };
var subscribeResult = await feed.SubscribeToSyncScopesAsync(scopes);
if (!subscribeResult)
{
throw new Exception("Subsribe failed!");
}
var channel = new UserNotificationChannel(feed);
var reader = channel.CreateReader();
reader.DataChanged += Reader_DataChanged;
Recibir y administrar las notificaciones de usuario
El diagrama de flujo representado anteriormente en este tema muestra que los patrones de programación para controlar nuevas notificaciones entrantes desde un servidor de aplicaciones y una actualización o eliminación de notificación iniciadas desde otra instancia de cliente de aplicación son similares. Estos son los pasos para controlar los cambios de los datos.
Controlar la señal de notificación de inserción entrante
Todos los tipos de cambios de datos de notificación de usuario crean una señal que se entrega a los clientes de aplicación, como una notificación de inserción. Para las aplicaciones UWP de Windows, se envía la señal como una notificación de inserción de WNS sin procesar. Al recibir la señal de inserción sin procesar, la aplicación debe llamar a TryParse para desencadenar el SDK y obtener los cambios de datos reales del servicio de notificaciones de Microsoft Graph.
public async Task ReceiveNotificationAsync(string content)
{
ConnectedDevicesNotification notification = ConnectedDevicesNotification.TryParse(content);
if (notification != null)
{
await platform.ProcessNotificationAsync(notification);
}
}
Controlar los cambios de datos de notificación de usuario
Después de que el SDK haya obtenido correctamente los cambios de datos, se invoca una devolución de llamada de evento y se espera que el cliente de la aplicación administre la creación, la actualización o la eliminación de la notificación.
private async void Reader_DataChanged(UserNotificationReader reader, object args)
{
var notifications = await reader.ReadBatchAsync(UInt32.MaxValue);
foreach (var notification in notifications)
{
// Handle notification changes based on change type;
}
}
Actualizar el estado de una notificación
Si se inicia un cambio de estado de notificación de esta instancia del cliente de aplicación (por ejemplo, si un usuario ha activado la notificación del sistema emergente en este dispositivo), la aplicación debe llamar al SDK para actualizar el estado de la notificación para que este cambio de estado se sincronice en todos los dispositivos que usa el mismo usuario.
notification.UserActionState = UserNotificationUserActionState.Activated;
await notification.SaveAsync();
Eliminar una notificación
Si la eliminación de una notificación se inicia desde esta instancia de cliente de aplicación (por ejemplo, si la tarea correspondiente a esta notificación se marca como completada y se elimina de la base de datos de la aplicación), la aplicación debe llamar al SDK para eliminar la notificación y sincronizar esta operación de eliminación en todos los dispositivos que ha usado el mismo usuario.
Una notificación se elimina del almacén de notificaciones del usuario solo si ha expirado o se ha eliminado de forma explícita. No se elimina la notificación de usuario al actualizar UserActionState como Descartado, porque la definición semántica de UserActionState la define la misma aplicación.
await channel.DeleteUserNotificationAsync(notification.Id);
Contenido relacionado
- Referencia de la API para todo el conjunto de API relacionadas con las características de notificación de SDK.
- Ejemplo del lado cliente para aplicaciones UWP de Windows.
- Ejemplo de servidor de aplicaciones para publicar notificaciones.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de