Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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).
Une fois que vous avez 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 iOS.
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.
- APN : service Apple Push Notification Service fournis par Apple pour les applications iOS. Les notifications de Microsoft Graph utilisent ce service pour signaler aux clients d’applications iOS des modifications des données de notification à l’utilisateur.
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. Dans ce cas, il s’agit d’une application iOS qui utilise [notification de mise à jour en arrière-plan d’Apple Push Notification Service] 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 alerte iOS 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. Dans ce cas, il s’agit d’une application iOS qui utilise une notification de mise à jour en arrière-plan d’Apple Push Notification Service 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 l’interface utilisateur d’alerte correspondante dans le centre de notifications iOS 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
Le moyen le plus simple d’ajouter la plateforme des appareils connectés à votre application iOS consiste à utiliser le gestionnaire de dépendances CocoaPods. Accédez au Podfile de votre projet iOS et insérez l’entrée suivante :
platform :ios, "10.0"
workspace 'iOSSample'
target 'iOSSample' do
# Uncomment the next line if you're using Swift or would like to use dynamic frameworks
# use_frameworks!
pod 'ProjectRomeSdk'
# Pods for iOSSample
Remarque
Pour pouvoir vous servir de CocoaPod, vous devez utiliser le fichier .xcworkspace de votre projet.
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 qu’une fonctionnalité soit utilisable, la plateforme doit être initialisée dans votre application. Les étapes d’initialisation doivent avoir lieu dans votre méthode AppDelegate, car elles sont indispensables pour l’exécution des scénarios de notification.
Vous devez construire et initialiser la plateforme en instanciant la classe MCDConnectedDevicesPlatform. 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.
MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
[platform.accountManager.accessTokenRequested subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager, MCDConnectedDevicesAccessTokenRequestedEventArgs* _Nonnull args) {
// implement the callback;
}];
[self.platform.accountManager.accessTokenInvalidated
subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
// implement the callback;
}];
[self.platform.notificationRegistrationManager.notificationRegistrationStateChanged subscribe:^(MCDConnectedDevicesNotificationRegistrationManager* _Nonnull manager __unused, MCDConnectedDevicesNotificationRegistrationStateChangedEventArgs* _Nonnull args) {
// implement the callback
}];
[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é.
accessTokenRequested
Pour une implémentation complète, voir l’exemple d’application iOS.
accessTokenInvalidated
Pour une implémentation complète, voir l’exemple d’application iOS.
[platform.accountManager.accessTokenInvalidated
subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
}];
Gestion de l’expiration d’inscription de notification Push
L’API de notifications de Microsoft Graph utilise les services de notifications Push Apple, la plateforme de notifications Push native d’iOS, 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 jeton Apple Push Notification Service valide permettant le passage de notifications de mise à jour en arrière-plan est requis. Le rappel d’événement suivant gère les expirations de jeton Push d’Apple Push Notification Service.
notificationRegistrationStateChanged
Pour une implémentation complète, voir l’exemple d’application iOS.
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 de notifications Push Apple. Pour plus d’informations, voir la méthode prepareAccountAsync dans l’exemple.
MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
MCDConnectedDevicesAccount* mcdAccount = [MCDConnectedDevicesAccount new];
[platform.accountManager addAccountAsync:mcdAccount callback:adapter];
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.
// Initialize the feed and subscribe for notifications
MCDUserDataFeed* feed = [MCDUserDataFeed getForAccount:account
platform:platform
activitySourceHost:APP_HOST_NAME];
NSArray<MCDUserDataFeedSyncScope*>* syncScopes = @[ [MCDUserNotificationChannel syncScope] ];
[feed subscribeToSyncScopesAsync:syncScopes
callback:^(BOOL success __unused, NSError* _Nullable error __unused) {
// Start syncing down notifications
[feed startSync];
}];
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. Dans le cas d’une application iOS, le signal est transmis en tant que notification de mise à jour en arrière-plan d’Apple Push Notification Service. Lors de la réception du signal de message de données, 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.
// App running in background and received a push notification, launched by user tapping the alert view
MCDConnectedDevicesNotification* notification = [MCDConnectedDevicesNotification tryParse:notificationInfo];
if (notification != nil) {
[_platformManager.platform processNotificationAsync:notification
completion:^(NSError* error __unused) {
// NOTE: it might be useful to attach completion to this async in order to know when the
// notification is done being processed.
// This would be a good time to stop a background service or otherwise cleanup.
}];
} else {
NSLog(@"Remote notification is not for ConnectedDevicesPlatform, skip processing");
}
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.
[reader readBatchAsyncWithMaxSize:100 completion:^(NSArray<MCDUserNotification *> * _Nullable notifications,
NSError * _Nullable error) {
if (error) {
} else {
for (MCDUserNotification* notification in self.notifications) {
// Handle notification change 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.
- (void)dismissNotification:(MCDUserNotification*)notification {
if (notification.userActionState == MCDUserNotificationUserActionStateNoInteraction) {
[self dismissNotificationFromTrayWithId:notification.notificationId];
notification.userActionState = MCDUserNotificationUserActionStateDismissed;
[notification saveAsync:^(__unused MCDUserNotificationUpdateResult * _Nullable result, __unused NSError * _Nullable error) {
// handle result;
}];
}
}
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.
- (void)deleteNotification:(MCDUserNotification*)notification {
[_channel deleteUserNotificationAsync:notification.notificationId
completion:^(__unused MCDUserNotificationUpdateResult* _Nullable result, NSError* _Nullable error) {
// handle result;
}];
}
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 Android.
- Exemple de serveur d’applications pour la publication des notifications.