Ihre iOS-App mit dem clientseitigen SDK für Benutzerbenachrichtigungen (veraltet) integrieren
Wichtig
Die Microsoft Graph-Benachrichtigungs-API ist veraltet und gibt seit Januar 2022 keine Daten mehr zurück. Eine alternative Benachrichtigungsoberfläche finden Sie unter Microsoft Azure-Benachrichtigungshubs. Weitere Informationen finden Sie im Blogbeitrag Retiring Microsoft Graph Notifications API (Beta).
Nachdem Sie Ihre App im Azure-Portal registriert haben und Ihre geräteübergreifende Oberfläche im Dev-Center für Partner integriert haben, ist der nächste Schritt, Ihre clientseitige App mit dem clientseitigen SDK für iOS-Apps zu integrieren.
Mit dem clientseitigen SDK kann Ihre App die nötigen Registrierungsschritte ausführen, um Benachrichtigungen von Ihrem App-Server zu empfangen, die an den Benutzer gerichtet sind, der aktuell angemeldet ist. Das SDK verwaltet die Benachrichtigungen clientseitig, einschließlich des Empfangs neuer Benachrichtigungen und der Verwaltung des Status von Benachrichtigungen, um Szenarien wie geräteübergreifendes Schließen und den Abruf des vollständigen Benachrichtigungsverlaufes zu realisieren.
Fluss neuer eingehender Benachrichtigungen
Für den Empfang neuer eingehender Benachrichtigungen wird der Datenfluss im folgenden Diagramm gezeigt.
Der Prozess umfasst einige Komponenten:
- App-Server – das Back-End Ihrer Anwendung
- App-Client – das Frontend Ihrer Anwendung (eine UWP-App, eine Android-App oder eine App für iOS)
- Microsoft Graph-Benachrichtigungen – Diejenige Dienstkomponente, die es ermöglicht, Benutzerbenachrichtigungen zu veröffentlichen, zu speichern und zwischen verschiedenen Instanzen der App auf mehreren Geräten und Plattformen zu synchronisieren.
- APNs – der Apple-Pushbenachrichtigungsdienst, der von Apple für iOS-Apps bereitgestellt wird. Microsoft Graph-Benachrichtigungen verwenden diesen Dienst, um iOS-App-Clients Datenänderungen bei Benutzerbenachrichtigungen zu signalisieren.
Das Diagramm zeigt die folgenden Schritte:
- Anwendungslogik: Dieser Schritt erfasst, was den Veröffentlichung der Benachrichtigung an den Benutzer auslöst. Dies ist App-spezifische Logik, die auch eine Ereignis- oder Datenaktualisierung zu etwas anderem in Microsoft Graph sein kann, beispielsweise ein neuer Kalendereintrag oder die Zuweisung einer Aufgabe, oder etwas anderes, worüber Ihr App-Dienst den Benutzer informieren möchte.
- Der App-Server sendet mittels der Microsoft Graph Benachrichtigungs-API eine Benachrichtigung an den entsprechenden Benutzer. Weitere Informationen hierzu finden Sie unter Serverseitige Integration.
- Bei Empfang der Webanforderung, welche die neue Benachrichtigung enthält, speichert Microsoft Graph Benachrichtigungen den Inhalt der Benachrichtigung für diese App und diesen Benutzer sicher in der Cloud.
- Für jede Instanz der Client-App, die für den Empfang von Benachrichtigungen für diesen Benutzer angemeldet ist, sendet Microsoft Graph Benachrichtigungen mittels des jeweils systemeigenen Push-Dienstes ein Signal aus, um den App-Client zu benachrichtigen. In diesem Fall handelt es sich bei der Anwendung um eine iOS-App, und diese verwendet [APNs Hintergrund-Updatebenachrichtigung], um das Signal zu versenden.
- Nachdem die Anwendung das Signal mittels eingehender Pushbenachrichtigung empfangen hat, fordert sie das SDK dazu auf, die Änderungen im Benachrichtigungsspeicher des Benutzers abzurufen.
- Das SDK baut eine sichere und konforme Verbindung mit dem Benachrichtigungsspeicher des Benutzers in Microsoft Graph auf.
- Das SDK empfängt die Datenänderungen – in diesem Fall handelt es sich um die neuen Benachrichtigungsinhalte.
- Das SDK sendet Ereignisrückrufe, um die App zu benachrichtigen, nachdem die Änderungen erfolgreich abgerufen wurden.
- Anwendungslogik. Dieser Schritt umfasst, was die App innerhalb des Ereignisrückrufes entscheidet, zu tun. In der Regel führt dies zur Änderung lokaler Anwendungsdaten und zu lokalen Benutzeroberflächen-Updates. In diesem Fall erstellt die App in der Regel eine iOS-Benachrichtigung, um den Benutzer über den Inhalt der Benachrichtigung zu informieren.
Benachrichtigungs-Updatefluss
Einer der Hauptvorteile bei der Verwendung von Microsoft Graph Benachrichtigungen ist, dass Benachrichtigungen sicher in der Cloud gespeichert und in einen zustandsbehafteten Ressourcentyp gewandelt werden. Daher kann es Ihrer Anwendung dabei helfen, in einem plattformübergreifenden Szenario den korrekten Benachrichtigungsstatus über verschiedene Geräte hinweg für denselben angemeldeten Benutzer zu verwalten und zu synchronisieren. Wenn eine Benachrichtigung als geschlossen oder auf einem Gerät als gelesen markiert wird, können die anderen Geräte darüber in Echtzeit benachrichtigt werden. „Einmal behandelt, überall geschlossen“ kann für Ihre benachrichtigten Nutzer zu einem echten Versprechen werden.
Das folgende Diagramm zeigt den Datenfluss für die Änderung des Status einer Benachrichtigung oder für das Löschen der Benachrichtigung auf einem Gerät und den Erhalt/die Verarbeitung der Statusänderung oder der Löschung auf einem anderen Gerät.
Beachten Sie, dass der zweite Teil des Flussdiagramms ähnlich dem Ablauf für die Verarbeitung eingehender neuer Benachrichtigungen ist. Dies ist beabsichtigt: das Programmierungsmuster des SDK ist so konzipiert, dass der Anwendungsclient alle Arten von Benutzer-Benachrichtigungsdatenänderungen verarbeiten kann (neue eingehende Benachrichtigungen, Benachrichtigungs-Zustandsänderungen, Löschen von Benachrichtigungen).
Das Diagramm zeigt die folgenden Schritte:
- Anwendungslogik. Etwas löst die Änderung oder Löschung der Benachrichtigung aus. Im Allgemeinen kann jedes Ereignis eine Änderung der Benachrichtigung auslösen.
- Die App kontaktiert das Client-SDK, um eine Benachrichtigung zu aktualisieren oder zu löschen. Derzeit bieten wir zwei Eigenschaften bezüglich Statusänderungen: userActionState und readState. Ihre Anwendung kann diese Status definieren und auch festlegen, wann diese aktualisiert werden müssen. Wenn ein Benutzer das Benachrichtigungs-Popup beispielsweise schließt, können Sie die Eigenschaft userActionState auf geschlossen setzen. Wenn ein Benutzer auf das Benachrichtigungs-Popup klickt und die App öffnet, um den entsprechenden App-Inhalt zu konsumieren, können Sie userActionState auf aktiviert und readState auf gelesen setzen.
- Nachdem die entsprechende API aufgerufen wird, um eine Benachrichtigung zu aktualisieren oder zu löschen, kontaktiert das SDK den Benachrichtigungsspeicher des Benutzers in der Cloud, um diese Änderung an die restlichen App-Client-Instanzen aufzufächern, in denen derselbe Benutzer angemeldet ist.
- Nach Erhalt der Aktualisierungs-/Löschanfrage von einem Client aktualisiert Microsoft Graph Benachrichtigungen den Benachrichtigungsspeicher und identifiziert die anderen App-Client-Instanzen, die sich für diese Änderung angemeldet haben.
- Für jede Instanz der Client-App, die für den Empfang von Benachrichtigungen für diesen Benutzer angemeldet ist, sendet Microsoft Graph Benachrichtigungen mittels des jeweils systemeigenen Push-Dienstes ein Signal aus, um den App-Client zu benachrichtigen. In diesem Fall handelt es sich um eine iOS-App, und diese verwendet APNs Hintergrund-Updatebenachrichtigung, um das Signal zu versenden.
- Nachdem die Anwendung das Signal mittels eingehender Pushbenachrichtigung empfangen hat, fordert sie das SDK dazu auf, die Änderungen im Benachrichtigungsspeicher des Benutzers abzurufen.
- Das SDK baut eine sichere und konforme Verbindung mit dem Benachrichtigungsspeicher des Benutzers in Microsoft Graph auf.
- Das SDK empfängt die Datenänderungen – in diesem Fall handelt es sich um Benachrichtigungs-Statusaktualisierungen oder Benachrichtigungs-Löschungen.
- Das SDK sendet Ereignisrückrufe, um die App zu benachrichtigen, nachdem die Änderungen erfolgreich abgerufen wurden.
- Anwendungslogik. Dieser Schritt umfasst, was die App innerhalb des Ereignisrückrufes entscheidet, zu tun. In der Regel führt dies zur Änderung lokaler Anwendungsdaten und zu lokalen Benutzeroberflächen-Updates. Da Benachrichtigungsaktualisierungen vorliegen, sollte die App in diesem Fall die Benutzeroberfläche lokal aktualisieren, um die Zustandsänderung darzustellen. Wenn eine Benachrichtigung z.B. als aktiviert markiert wird, können Sie die zugehörige Benachrichtigung aus der iOS-Mitteilungszentrale entfernen, um nach dem Prinzip „einmal behandelt, überall geschlossen“ zu arbeiten.
Weitere Informationen zu Microsoft Graph Benachrichtigungen finden Sie unter Microsoft Graph Benachrichtigungen Überblick. Für zusätzliche Informationen über die Schritte, die erforderlich sind, um Microsoft Graph-Benachrichtigungen von Ende zu Ende zu integrieren, lesen Sie die Microsoft Graph-Benachrichtigungsübersicht.
Ihrem Projekt das SDK hinzufügen
Die einfachste Methode zum Hinzufügen der Plattform für verbundene Geräte zu Ihrer iOS-App ist die Verwendung des CocoaPods Abhängigkeits-Managers. Wechseln Sie zu dem Podfile Ihres iOS-Projekts und fügen Sie den folgenden Eintrag hinzu:
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
Hinweis
Um CocoaPod nutzen zu können, verwenden Sie die .xcworkspace-Datei in Ihrem Projekt.
Die Plattform für verbundene Geräte initialisieren
Das clientseitige SDK basiert auf einer Infrastruktur namens Plattform für verbundene Geräte. Bevor eine der Funktionen verwendet werden kann, muss die Plattform innerhalb Ihrer App initialisiert werden. Die Initialisierungsschritte sollten in Ihrer AppDelegate-Methode erfolgen, da sie benötigt werden, bevor die Benachrichtigungsszenarien erfolgen können.
Sie müssen die Plattform konstruieren und initialisieren, indem Sie die Klasse MCDConnectedDevicesPlatforminstanziieren. Vorher müssen Sie sicherstellen, dass Ereignishandler (wie gezeigt) verknüpft sind, denn die Ereignisse können eintreten, sobald die Plattform gestartet wird.
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];
Handhabung von Konto-Zugriffstoken
Alle Webaufrufe, die das SDK durchführt, einschließlich des Abrufens des Inhalts einer neuen eingehenden Benachrichtigung, das Aktualisierung von Benachrichtigungsstatus usw., lesen aus oder schreiben in die Benutzerdaten und benötigen daher stets ein gültiges Zugriffstoken. Das SDK erfordert, dass Sie die folgenden Ereignisse verarbeiten. Diese treten ein, sobald ein Zugriffstoken angefordert oder ungültig gemacht wird, um sicherzustellen, dass Ihr Zugriffstoken nach der Initialisierung der Plattform korrekt verarbeitet wird.
accessTokenRequested
Eine vollständige Implementierung finden Sie in der Beispiel-App für iOS.
accessTokenInvalidated
Eine vollständige Implementierung finden Sie in der Beispiel-App für iOS.
[platform.accountManager.accessTokenInvalidated
subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
}];
Verarbeitung des Ablaufs von Push-Registrierungen
Microsoft Graph Benachrichtigungen verwenden APNs, die native Push-Plattform unter iOS, um der Clientanwendung Änderungen der Benachrichtigungsdaten des Benutzers zu signalisieren. Dies geschieht, wenn neue eingehende Benachrichtigungen von Ihrem App-Server veröffentlicht werden oder wenn der Status einer Benachrichtigung auf einem anderen Gerät aktualisiert wird, falls es sich um denselben Nutzer in einem geräteübergreifenden Szenario handelt.
Aus diesem Grund wird ein gültiges APN-Token benötigt, welches die erfolgreiche Hintergrundaktualisierung von Benachrichtigungen zulässt. Der folgende Ereignisrückruf verarbeitet die Ablaufzeit von APNs Push-Token.
notificationRegistrationStateChanged
Eine vollständige Implementierung finden Sie in der Beispiel-App für iOS.
Ihren Benutzer anmelden
Microsoft Graph-Benachrichtigungen sind, wie viele andere Ressourcentypen in Microsoft Graph, um einen zentralen Benutzer herum konstruiert. Um Ihre App für Benachrichtigungen für den angemeldeten Benutzer anzumelden und diese zu empfangen, müssen Sie zuerst ein gültiges OAuth-Token beschaffen, das im Registrierungsprozess verwendet wird. Sie können Ihre bevorzugte Methode zum Generieren und Verwalten der OAuth-Token verwenden. Die Beispiel-App verwendet ADAL.
Wenn Sie ein Microsoft-Konto verwenden, müssen Sie die folgenden Berechtigungen in Ihre Anmeldeanfrage inkludieren: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry und https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.
Wenn Sie ein Azure AD-Konto verwenden, müssen Sie die folgende Zielgruppe anfordern: https://cdpcs.access.microsoft.com.
Der Plattform das Benutzerkonto hinzufügen
Sie müssen das angemeldete Benutzerkonto beim SDK registrieren. Dazu ist es nötig, das Konto hinzuzufügen, und einen Push-Kanal zu registrieren, um die anfänglichen Pushbenachrichtigungen durch APNs zu erhalten. Einzelheiten hierzu finden Sie bei der prepareAccountAsync Methode im Beispiel.
MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
MCDConnectedDevicesAccount* mcdAccount = [MCDConnectedDevicesAccount new];
[platform.accountManager addAccountAsync:mcdAccount callback:adapter];
Empfang von Benutzerbenachrichtigungen anmelden
Sie müssen ein UserDataFeed-Objekt für Ihre Anwendung für den angemeldeten Benutzer instanziieren. Ihre Anwendung wird durch die plattformübergreifende App-ID identifiziert, die Sie während des geräteübergreifenden Onboardings vergeben haben.
// 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];
}];
Empfangen und Verwalten von Benutzerbenachrichtigungen
Das Flussdiagramm weiter oben in diesem Artikel zeigt, dass die Programmierungsmuster zur Verarbeitung neu ankommender Benachrichtigungen von einem App-Server und ein Benachrichtigungs-Update oder eine -Löschung, die von einer anderen Client-Instanz initiiert werden, ähnlich sind. Die folgenden Schritte beschreiben die Verarbeitung dieser Datenänderungen.
Verarbeitung eingehender Pushbenachrichtigungs-Signale
Alle Typen von Datenänderungen an Benutzerbenachrichtigungen generieren ein Signal, welches als Pushbenachrichtigung zu den App-Clients gesendet wird. Im Falle einer iOS-App wird das Signal als APNs Hintergrundaktualisierungsbenachrichtigung übermittelt. Sobald das Daten-Nachrichtensignal empfangen wird, sollte die App TryParse aufrufen, um das SDK zu veranlassen, die tatsächlichen Datenänderungen vom Microsoft Graph Benachrichtigungsdienst abzurufen.
// 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 may 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");
}
Verarbeitung von Änderungen an Benutzer-Benachrichtigungsdaten
Nachdem das SDK erfolgreich die Datenänderungen abgerufen hat, wird ein Ereignisrückruf ausgelöst, und vom App-Client wird erwartet, dass er die Erstellung, Löschung oder Änderung einer Benachrichtigung übernimmt.
[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;
}
}
}
}];
Aktualisierung des Zustands einer Benachrichtigung
Wenn diese App-Client-Instanz eine Statusänderung für eine Benachrichtigung initiiert (beispielsweise, wenn die Popupbenachrichtigung auf diesem Gerät vom Benutzer aktiviert wird), so muss die App das SDK aufrufen, um den Benachrichtigungsstatus zu aktualisieren, damit dieser Status geräteübergreifend für diesen Nutzer auf all seinen Geräten synchronisiert wird.
- (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;
}];
}
}
Löschen einer Benachrichtigung
Wenn von dieser App-Client-Instanz aus die Löschung einer Benachrichtigung initiiert wird (z.B. falls der Task, der dieser Benachrichtigung zugehörig ist, als abgeschlossen gekennzeichnet wird und aus der Datenbank Ihrer App entfernt wird), so muss die App das SDK aufrufen, um die Benachrichtigung zu löschen, damit dieser Löschvorgang über alle Geräte dieses Benutzers hinweg synchronisiert wird.
Eine Benachrichtigung wird erst dann aus dem Benachrichtigungsspeicher eines Nutzers entfernt, wenn sie abgelaufen ist oder ausdrücklich gelöscht wurde. Eine Benutzerbenachrichtigung wird nicht gelöscht, wenn Sie den UserActionState auf geschlossen setzen, denn die semantische Definition von UserActionState wird durch die Anwendung selbst definiert.
- (void)deleteNotification:(MCDUserNotification*)notification {
[_channel deleteUserNotificationAsync:notification.notificationId
completion:^(__unused MCDUserNotificationUpdateResult* _Nullable result, NSError* _Nullable error) {
// handle result;
}];
}
Siehe auch
- API-Referenz für alle APIs, die mit Benachrichtigungsfunktionen im SDK zusammenhängen.
- Clientseitiges Beispiel für Android-Apps.
- App-Server-Beispiel für die Veröffentlichung von Benachrichtigungen.
Feedback
Feedback senden und anzeigen für