Intégrer votre application Windows UWP au Kit de développement logiciel (SDK) côté client pour les notifications utilisateur (déconseillé)
Importante
L’API de notifications Microsoft Graph est déconseillée et a cessé de retourner des données en janvier 2022. Pour une autre expérience de notification, consultez Microsoft Azure Notification Hubs. Pour plus d’informations, consultez le billet de blog Retrait de l’ API de notifications de Microsoft Graph (bêta).
Après avoir inscrit votre application dans le centre d'administration Microsoft Entra et intégré vos expériences inter-appareils dans le Centre de développement partenaires, l’étape suivante consiste à intégrer votre application cliente au SDK côté client pour les applications Windows UWP.
Avec le Kit de développement logiciel (SDK) côté client, votre application peut accomplir les étapes d’inscription nécessaires pour commencer à recevoir des notifications publiées par votre serveur d’applications ciblant l’utilisateur actuellement connecté. Le Kit de développement logiciel (SDK) gère ensuite les notifications côté client, en recevant les nouvelles notifications entrantes, en vérifiant l’état des notifications, par exemple, pour le masquage universel, et en récupérant l’historique complet des notifications.
Flux de nouvelle notification entrante
Le flux de données pour la réception de nouvelles notifications entrantes est présenté dans le diagramme suivant.
Le processus implique quelques composants :
- Serveur d’applications : serveur principal de votre application
- Client de l’application : serveur frontal de votre application (application UWP, application Android ou application iOS)
- Notifications de Microsoft Graph : composant de service qui active la publication, le stockage et la synchronisation des notifications à l’utilisateur dans différentes instances de clients de l’application sur divers appareils et plateformes.
- WNS : services de notifications Push Windows que l’API de notifications de Microsoft Graph utilise pour signaler les clients
Le diagramme présente les étapes suivantes :
- Logique d’application. Cette étape capture ce qui déclenche la publication de la notification à l’utilisateur. Il s’agit d’une logique spécifique de l’application. Ce peut être un événement ou une mise à jour de données concernant quelque chose d’autre dans Microsoft Graph, tel qu’un nouvel événement ou une nouvelle tâche de calendrier, ou quelque chose que votre application souhaite notifier à l’utilisateur.
- Le serveur d’applications publie une notification à l’utilisateur ciblé via l’API de notifications de Microsoft Graph. Pour plus d’informations, voir l’intégration côté serveur.
- À la réception de la demande web contenant la nouvelle notification, l’API de notifications de Microsoft Graph conserve le contenu de la notification en sécurité dans le cloud pour cette application et cet utilisateur.
- Pour chaque instance de client de l’application qui s’abonne pour recevoir des notifications destinées à cet utilisateur, l’API de notifications de Microsoft Graph envoie un signal pour notifier le client de l’application via le service de notifications Push natif du système d’exploitation. En l’occurrence, l’application est une application UWP sous Windows, qui utilise une notification Push brute des services WNS pour envoyer le signal.
- Une fois l’application signalée par la notification Push entrante, elle demande au Kit de développement logiciel (SDK) d’extraire les modifications du magasin de notifications à l’utilisateur.
- Le Kit de développement logiciel (SDK) établit une connexion sécurisée et conforme avec le magasin de notifications à l’utilisateur dans Microsoft Graph.
- Le Kit de développement logiciel (SDK) récupère les modifications des données, en l’occurrence, le contenu de la nouvelle notification.
- Le kit de développement logiciel (SDK) déclenche les rappels d’événements pour notifier l’application une fois les modifications récupérées.
- Logique d’application. Cette étape capture ce que votre application choisit de faire dans le rappel d’événement. Généralement, cela entraîne des modifications des données de l’application locale et des mises à jour de l’interface utilisateur locale. Dans ce cas, l’application construit généralement une fenêtre contextuelle de notification toast pour informer l’utilisateur du contenu de la notification.
Flux de mise à jour de notification
L’un des principaux avantages liés à l’utilisation de l’API de notifications de Microsoft Graph est qu’elle conserve les notifications en sécurité dans le cloud et les convertit en un type de ressource avec état. Elle peut donc aider votre application à gérer et à synchroniser l’état correct des notifications sur différents appareils pour le même utilisateur connecté dans un contexte inter-appareils. Quand une notification est marquée comme masquée ou lue sur un appareil, les autres appareils peuvent être notifiés en temps réel. L’approche « traité une fois, masqué partout » peut devenir réellement prometteuse dans le cadre de l’expérience de notification pour vos utilisateurs.
Le diagramme suivant illustre le flux de données pour le changement de l’état d’une notification ou la suppression de celle-ci sur un appareil, ainsi que pour la réception/gestion du changement d’état ou de la suppression sur un autre appareil.
Notez que la deuxième partie du flux est similaire au flux de traitement des nouvelles notifications entrantes. Il s’agit d’une conception : le modèle de programmation du KIT de développement logiciel (SDK) est conçu pour que le client d’application puisse gérer tous les types de modifications des données de notification utilisateur (nouvelles notifications entrantes, changements d’état de notification, notification supprimée) de la même façon.
Le diagramme présente les étapes suivantes :
- Logique d’application. Quelque chose déclenche la modification ou la suppression de la notification. En général, tout événement peut déclencher une modification de notification.
- Application faisant appel au Kit de développement logiciel (SDK) client pour mettre à jour ou supprimer une notification. Actuellement, nous exposons deux propriétés concernant les changements d’état (userActionState et readState) mais votre application peut définir ces états et le moment où ils doivent être mis à jour. Par exemple, quand un utilisateur masque la fenêtre contextuelle de notification, vous pouvez mettre à jour l’état userActionState afin qu’il soit masqué. Quand un utilisateur clique sur la fenêtre contextuelle de notification et lance l’application pour utiliser le contenu correspondant, vous pouvez mettre à jour l’état userActionState en le définissant comme Activé, et l’état readState en le définissant comme Lu.
- Une fois l’API correspondante appelée pour mettre à jour ou supprimer une notification, le Kit de développement logiciel (SDK) fait appel au magasin de notifications à l’utilisateur dans le cloud pour propager ce changement aux autres instances du client de l’application avec le même utilisateur connecté.
- Lors de la réception de la demande de mise à jour/suppression d’un client, l’API de notifications de Microsoft Graph met à jour le magasin de notifications et identifie les autres instances du client de l’application abonnées à cette modification.
- Pour chaque abonnement client, l’API de notifications de Microsoft Graph envoie un signal pour notifier le client de l’application via le service de notifications Push natif du système d’exploitation. En l’occurrence, il s’agit d’une application UWP sous Windows, qui utilise une notification Push brute des services WNS pour envoyer le signal.
- Une fois l’application signalée par la notification Push entrante, elle demande au Kit de développement logiciel (SDK) d’extraire les modifications du magasin de notifications à l’utilisateur.
- Le Kit de développement logiciel (SDK) établit une connexion sécurisée et conforme avec le magasin de notifications à l’utilisateur dans Microsoft Graph.
- Le Kit de développement logiciel (SDK) récupère les modifications des données, en l’occurrence les mises à jour d’état de notification ou les suppressions de notification.
- Le kit de développement logiciel (SDK) déclenche les rappels d’événements pour notifier l’application une fois les modifications récupérées.
- Logique d’application. Cette étape capture ce que votre application choisit de faire dans le rappel d’événement. Généralement, cela entraîne des modifications des données de l’application locale et des mises à jour de l’interface utilisateur locale. Dans ce cas, étant donné qu’il existe des mises à jour de notification, l’application doit mettre à jour l’interface utilisateur localement afin qu’elle reflète le changement d’état. Par exemple, si une notification est marquée comme activée, vous pouvez supprimer la fenêtre contextuelle de notification toast correspondante dans le centre de notifications Windows conformément à l’approche « traité une fois, masqué partout ».
Pour plus d’informations sur les notifications de Microsoft Graph, voir la vue d’ensemble des notifications de Microsoft Graph. Pour plus d’informations sur la procédure à suivre pour l’intégration de bout en bout avec l’API de notifications de Microsoft Graph, voir la vue d’ensemble de l’intégration de l’API de notifications de Microsoft Graph.
Ajout du Kit de développement logiciel (SDK) à votre projet
Sous Windows, le Kit de développement logiciel (SDK) côté client est un package NuGet qui délivre en dehors du système d’exploitation Windows. Cette API est disponible en C #, C ++ et WinJS.
Téléchargez le package NuGet du Kit de développement logiciel (SDK) de l’API de notifications de Microsoft Graph pour les applications Windows sur nuget, ou procédez comme suit pour le télécharger à partir de votre solution applicative dans Visual Studio :
Dans Visual Studio, cliquez avec le bouton droit sur le projet pour afficher le menu contextuel, puis cliquez sur Gérer les packages NuGet….
Accédez à l’onglet Parcourir, puis recherchez Microsoft.ConnectedDevices.UserNotifications.
Le Kit de développement logiciel (SDK) côté client de l’API de notifications de Microsoft Graph figure parmi les résultats de la recherche. Cliquez sur le bouton Installer pour l’installer.
Une fois l’installation terminée, le package apparaît sous Références dans l’Explorateur de solutions.
Pour plus de détails sur l’inclusion et l’utilisation de packages NuGet à partir de votre application UWP, voir :
- Utiliser des packages de nuget.org
- Démarrage rapide : Installer et utiliser un package dans Visual Studio
Initialisation des plateformes d’appareils connectés
Le Kit de développement logiciel (SDK) côté client est construit sur une infrastructure appelée plateforme d’appareil connecté. Pour que ses fonctionnalités soient utilisables, la plateforme doit être initialisée dans votre application. Les étapes d’initialisation doivent avoir lieu dans votre méthode OnLaunched ou onActivated de la classe principale, car elles sont indispensables pour l’exécution des scénarios de notification.
Vous devez construire et initialiser la plateforme en instanciant la classe ConnectedDevicesPlatform. Avant cela, veillez à raccorder les gestionnaires d’événements comme indiqué car, une fois la plateforme démarrée, les événements pourraient commencer à se déclencher.
var platform = new ConnectedDevicesPlatform();
platform.AccountManager.AccessTokenRequested += AccountManager_AccessTokenRequestedAsync;
platform.AccountManager.AccessTokenInvalidated += AccountManager_AccessTokenInvalidated;
platform.NotificationRegistrationManager.NotificationRegistrationStateChanged += NotificationRegistrationManager_NotificationRegistrationStateChanged;
platform.Start();
Gestion de jeton d’accès au compte
Tous les appels web effectués par le Kit de développement logiciel (SDK), par exemple, pour la récupération du contenu d’une nouvelle notification entrante ou la mise à jour d’états de notification, lisent ou écrivent des données de l’utilisateur. Ils nécessitent donc toujours un jeton d’accès valide. Le Kit de développement logiciel (SDK) requiert que vous gériez les événements suivants (appelés quand un jeton d’accès est demandé ou invalidé) pour vous assurer qu’une fois la plateforme initialisée, votre jeton d’accès pour l’utilisateur soit correctement géré.
AccountManager_AccessTokenRequestedAsync
Pour une implémentation complète, voir l’exemple d’application 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
Pour une implémentation complète, voir l’exemple d’application 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)}");
}
Gestion de l’expiration d’inscription de notification Push
L’API de notifications de Microsoft Graph utilise les services WNS, la plateforme de notifications Push native de Windows, pour signaler à l’application cliente les modifications des données des notifications à l’utilisateur. Cela se produit quand de nouvelles notifications entrantes sont publiées à partir de votre serveur d’applications ou quand l’état d’une notification est mis à jour sur un autre appareil du même utilisateur connecté dans un contexte inter-appareils.
C’est pourquoi un canal WNS valide permettant le passage de notifications Push brutes est requis. Le rappel d’événement suivant gère les expirations du canal de notifications Push des services WNS.
NotificationRegistrationManager_NotificationRegistrationStateChanged
Pour une implémentation complète, voir l’exemple d’application 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();
}
}
}
Connexion de votre utilisateur
Les notifications de Microsoft Graph, ainsi que celles de nombreux autres types de ressources dans Microsoft Graph, sont centralisées autour des utilisateurs. Pour que votre application puisse s’abonner au notifications destinées à l’utilisateur connecté et commencer à les recevoir, vous devez commencer par obtenir un jeton OAuth valide à utiliser dans le processus d’inscription. Vous pouvez utiliser votre méthode préférée de génération et gestion des jetons OAuth. L’exemple d’application utilise une bibliothèque d’authentification Active Directory (ADAL).
Si vous utilisez un compte Microsoft, vous devez inclure dans votre demande de connexion les autorisations suivantes : wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry et https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.
Si vous utilisez un compte Microsoft Entra, vous devez demander l’audience suivante : https://cdpcs.access.microsoft.com.
Ajout du compte d’utilisateur à la plateforme
Vous devez inscrire le compte d’utilisateur connecté auprès du Kit de développement logiciel (SDK). Cela implique l’ajout du compte et l’inscription d’un canal de notifications Push pour recevoir les notifications Push initiales via les services 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 + "!");
}
Abonnement pour recevoir les notifications à l’utilisateur
Vous devez instancier un objet UserDataFeed pour votre application pour cet utilisateur connecté. Votre application est identifiée par l’ID d’application multiplateforme que vous avez fourni durant le processus d’intégration d’expériences inter-appareils.
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;
Réception et gestion de notifications à l’utilisateur
Le diagramme de flux présenté plus haut dans cette rubrique montre que les modèles de programmation pour gérer une nouvelle notification entrante provenant d’un serveur d’applications ou une mise à jour ou suppression de notification lancée par une autre instance du client de l’application sont similaires. Les étapes ci-après ont trait à la gestion de ces modifications des données.
Traitement du signal de notification Push entrante
Tous les types de modifications des données de notification à l’utilisateur génèrent un signal qui est transmis aux clients de l’application sous forme de notification Push. Pour les applications Windows (UWP), le signal est transmis sous forme de notification Push brute des services WNS. Lors de la réception du signal de notification Push brute, l’application doit appeler la méthode TryParse pour déclencher l’extraction par le Kit de développement logiciel (SDK) des modifications des données à partir du service de notifications de Microsoft Graph.
public async Task ReceiveNotificationAsync(string content)
{
ConnectedDevicesNotification notification = ConnectedDevicesNotification.TryParse(content);
if (notification != null)
{
await platform.ProcessNotificationAsync(notification);
}
}
Gestion des modifications des données de notification à l’utilisateur
Après que le Kit de développement logiciel (SDK) a extrait les modifications des données, un rappel d’événement est lancé, et le client de l’application doit gérer la création, la mise à jour ou la suppression de la notification.
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;
}
}
Mettre à jour l’état d’une notification
Si un changement d’état d’une notification est déclenché par cette instance du client de l’application (par exemple, si la fenêtre contextuelle de notification toast sur cet appareil est activée par l’utilisateur), l’application doit appeler le Kit de développement logiciel (SDK) pour mettre à jour l’état de la notification afin que ce changement d’état soit synchronisé sur tous les appareils utilisés par le même utilisateur.
notification.UserActionState = UserNotificationUserActionState.Activated;
await notification.SaveAsync();
Supprimer une notification
Si une suppression de notification est déclenchée par cette instance de client de l’application (par exemple, si la tâche correspondant à cette notification est marquée comme terminée et supprimée de la base de données de votre application), l’application doit appeler le Kit de développement logiciel (SDK) pour supprimer la notification afin que cette opération de suppression soit synchronisée sur tous les appareils utilisés par le même utilisateur.
Une notification n’est supprimée du magasin de notifications à l’utilisateur que si elle a expiré ou été explicitement supprimée. Une notification à l’utilisateur n’est pas supprimée quand vous mettez à jour l’état UserActionState sur Masqué, car la définition sémantique de celui-ci est définie par l’application elle-même.
await channel.DeleteUserNotificationAsync(notification.Id);
Contenu connexe
- Référence API pour l’ensemble des API liées aux fonctionnalités de notification dans le Kit de développement logiciel (SDK).
- Exemple côté client pour les applications Windows (UWP).
- Exemple de serveur d’applications pour la publication des notifications.