Schrittanleitung: Integration in Graph-Benachrichtigungen (iOS)
Mithilfe von Graph-Benachrichtigungen kann Ihre App geräteübergreifend Benachrichtigungen für Benutzer senden und verwalten.
Mit dem clientseitigen Project Rome-SDK unter iOS kann Ihre iOS-App für den Empfang der vom App-Server veröffentlichten Benachrichtigungen für angemeldete Benutzer registriert werden. Mithilfe des SDK kann der App-Client neue eingehende Benachrichtigungsnutzlasten empfangen, den Status der vorhandenen Benachrichtigungen verwalten und den Benachrichtigungsverlauf abrufen. Weitere Informationen über Benachrichtigungen und die Übermittlung benutzerzentrierter Benachrichtigungen finden Sie unter Microsoft Graph-Benachrichtigungen
Alle Features im Project Rome-SDK, einschließlich Graph-Benachrichtigungen, bauen auf einer Plattform auf, die als Plattform für verbundene Geräte bezeichnet wird. Diese Anleitung führt Sie durch die erforderlichen Schritte für die Verwendung der Plattform für verbundene Geräte, und es wird erläutert, wie mit den APIs im SDK spezielle Features von Graph-Benachrichtigungen implementiert werden.
In den folgenden Schritten wird auf Code aus der iOS-Beispiel-App für Project Rome verwiesen, die auf GitHub verfügbar ist.
Auf der Seite API-Referenz finden Sie Links zur Referenzdokumentation für Benachrichtigungsszenarien.
Einrichten der Plattform für verbundene Geräte und von Benachrichtigungen
Registrieren der App
Fast alle Features des Project Rome-SDK, mit Ausnahme der Umgebungsfreigabe-APIs, erfordern MSA-Authentifizierung (Microsoft Account) oder AAD-Authentifizierung (Azure Active Directory). Wenn Sie noch kein MSA haben, jedoch ein MSA verwenden möchten, registrieren Sie sich auf account.microsoft.com.
Hinweis
AAD-Konten (Azure Active Directory) werden für Device Relay-APIs nicht unterstützt.
Sie müssen Ihre App mit der gewählten Authentifizierungsmethode gemäß den Anweisungen im App-Registrierungsportal bei Microsoft registrieren. Wenn Sie über kein Microsoft Developer-Konto verfügen, müssen Sie eines erstellen.
Wenn Sie eine App mit einem MSA registrieren, erhalten Sie eine Client-ID-Zeichenfolge. Speichern Sie diese zur späteren Verwendung. Dadurch erhält Ihre App Zugriff auf Ressourcen der Microsoft-Plattform für verbundene Geräte. Wenn Sie AAD verwenden, finden Sie unter Azure Active Directory-Authentifizierungsbibliotheken Anweisungen zum Abrufen der Client-ID-Zeichenfolge.
Hinzufügen des SDK
Die einfachste Möglichkeit, der iOS-App die Plattform für verbundene Geräte hinzuzufügen, ist die Verwendung des CocoaPods-Abhängigkeits-Managers. Wechseln Sie zur Podfile-Datei Ihres iOS-Projekts, und fügen Sie den folgenden Eintrag ein:
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, müssen Sie die XCWORKSPACE-Datei in Ihrem Projekt verwenden.
Einrichten von Authentifizierung und Kontoverwaltung
Die Plattform für verbundene Geräte erfordert, dass bei der Registrierung ein gültiges OAuth-Token verwendet wird. Sie können Ihre bevorzugte Methode zum Generieren und Verwalten der OAuth-Token verwenden. Um jedoch Entwicklern die ersten Schritte mit der Plattform zu erleichtern, wird in der Beispiel-App für iOS ein Authentifizierungsanbieter bereitgestellt, den Sie zum Generieren und Verwalten von Aktualisierungstoken in der App verwenden können.
Wenn Sie nicht den bereitgestellten Code verwenden, müssen Sie die MCDConnectedDevicesAccountManager-Schnittstelle selbst implementieren.
Wenn Sie ein MSA verwenden, schließen Sie die folgenden Bereiche in die Anmeldeanforderung ein: "wl.offline_access"
, "ccs.ReadWrite"
, "dds.read"
, "dds.register"
, "wns.connect"
, "asimovrome.telemetry"
und "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp"
.
Hinweis
AAD-Konten (Azure Active Directory) werden für Device Relay-APIs nicht unterstützt.
Wenn Sie ein AAD-Konto verwenden, müssen Sie die folgenden Zielgruppen anfordern: "https://cdpcs.access.microsoft.com"
, "https://cs.dds.microsoft.com"
, "https://wns.windows.com/"
und "https://activity.microsoft.com"
.
Bei Verwendung von AAD müssen Sie unabhängig davon, ob Sie die bereitgestellte MDConnectedDevicesAccountManager-Implementierung verwenden, in der Registrierung der App im Azure-Portal (portal.azure.com > „Azure Active Directory“ > „App-Registrierungen“) die folgenden Berechtigungen angeben:
- Microsoft-Dienst für Aktivitätsfeeds
- Bereitstellen und Ändern von Benutzerbenachrichtigungen für diese App
- Lesen und Schreiben von App-Aktivitäten in den/aus dem Aktivitätsfeed des Benutzers
- Windows-Benachrichtigungsdienst
- Verbinden des Geräts mit dem Windows-Benachrichtigungsdienst
- Microsoft-Geräteverzeichnisdienst
- Siehe die Liste der Geräte
- Muss der Liste der Geräte und Apps hinzugefügt
- Microsoft-Befehlsdienst
- Kommunizieren mit Benutzergeräten
- Lesen von Benutzergeräten
Registrieren der App für Pushbenachrichtigungen
Registrieren Sie Ihre Anwendung bei Apple für die Unterstützung von Apple-Pushbenachrichtigungen. Notieren Sie sich die Absender-ID und den Serverschlüssel, die Sie erhalten, da Sie diese später benötigen.
Nach der Registrierung müssen Sie der Plattform für verbundene Geräte in der App die Pushbenachrichtigungsfunktionalität zuordnen.
self.notificationRegistration = [[MCDConnectedDevicesNotificationRegistration alloc] init];
if ([[UIApplication sharedApplication] isRegisteredForRemoteNotifications])
{
self.notificationRegistration.type = MCDNotificationTypeAPN;
}
else
{
self.notificationRegistration.type = MCDNotificationTypePolling;
}
self.notificationRegistration.appId = [[NSBundle mainBundle] bundleIdentifier];
self.notificationRegistration.appDisplayName = (NSString*)[[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleDisplayName"];
self.notificationRegistration.token = deviceToken;
self.isRegisteredWithToken = YES;
Registrieren der App im Microsoft Windows Dev Center für die geräteübergreifende Nutzung
Warnung
Dieser Schritt ist nur erforderlich, wenn Sie die Project Rome-Features verwenden möchten, um von Nicht-Windows-Geräten auf Daten zuzugreifen oder Anforderungen zu senden. Wenn die Features nur für Windows-Geräte vorgesehen sind, brauchen Sie diesen Schritt nicht durchzuführen.
Registrieren Sie die App für das Feature für die geräteübergreifende Nutzung im Microsoft-Entwicklerdashboard. Dies ist ein anderes Verfahren als die oben beschriebene Registrierung mit MSA- oder ADD-Authentifizierung. Der Hauptzweck dieses Verfahrens ist es, die plattformspezifischen App-Identitäten einer plattformübergreifenden App-Identität zuzuordnen, die von der Plattform für verbundene Geräte erkannt wird. Dieser Schritt ermöglicht auch das Senden von Benachrichtigungen mithilfe der nativen Pushbenachrichtigungsdienste, die der/den von der App verwendeten Plattform(en) entspricht. Für iOS wird hierdurch das Senden von Benachrichtigungen an iOS-App-Endpunkte über den Apple-Pushbenachrichtigungsdienst (Apple Push Notification Service, APNs) ermöglicht.
Wechseln Sie zum Dev Center-Dashboard, navigieren Sie im linken Navigationsbereich zu „Cross-Device Experiences“ (Geräteübergreifende Nutzung), und wählen Sie die Option zum Konfigurieren einer neuen geräteübergreifenden App aus.
Der Dev Center-Onboardingprozess erfordert die folgenden Schritte:
„Select supported platforms“ (Unterstützte Plattformen auswählen): Wählen Sie die Plattformen aus, auf denen Ihre App präsent sein wird und die für die geräteübergreifende Nutzung aktiviert werden sollen. Im Falle der Integration von Graph-Benachrichtigungen können Sie abhängig von den verwendeten Plattformen Windows, Android und/oder iOS auswählen.
„Provide app IDs“ (App-IDs angeben): Geben Sie für jede Plattform, die Sie verwenden, App-IDs an. Für iOS-Apps ist dies der Paketname, den Sie der App beim Erstellen des Projekts zugewiesen haben. Sie können verschiedene IDs (bis zu zehn) pro Plattform hinzufügen. Dies ist sinnvoll, wenn mehrere Versionen der App vorhanden sind oder wenn Sie über mehrere Apps verfügen, die dieselbe vom App-Server gesendete Benachrichtigung empfangen sollen, die für denselben Benutzer vorgesehen ist.
Geben Sie die APP-IDs an, die Sie durch die oben beschriebenen Schritte für die MSA- und/oder AAD-App-Registrierung erhalten haben, oder wählen Sie sie aus.
Geben Sie Ihre Anmeldeinformationen für die nativen Benachrichtigungsplattformen an, die für Ihre App relevant sind (z.B. WNS für Windows, FCM für Android und/oder APNs für iOS), um die Bereitstellung von Benachrichtigungen von Ihrem App-Server zu ermöglichen, wenn Sie Benachrichtigungen an Benutzer veröffentlichen.
Überprüfen Sie abschließend die Domäne für die geräteübergreifende App, um sicherzustellen, dass Ihre App der Besitzer der Domäne ist und sie als geräteübergreifende Identität für die App verwenden kann.
Verwenden der Plattform
Erstellen einer Instanz der Plattform
Instanziieren Sie zunächst einfach die Plattform.
MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
Abonnieren von MCDConnectedDevicesAccountManager
Für den Zugriff auf die Plattform ist ein authentifizierter Benutzer erforderlich. Sie müssen MCDConnectedDevicesAccountManager-Ereignisse abonnieren, um sicherzustellen, dass ein gültiges Konto verwendet wird.
[MCDConnectedDevicesPlatform* platform.accountManager.accessTokenRequested
subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
MCDConnectedDevicesAccessTokenRequestedEventArgs* _Nonnull request __unused) {
// Get access token
}
[MCDConnectedDevicesPlatform* platform.platform.accountManager.accessTokenInvalidated
subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
// Refresh and renew existing access token
}
Abonnieren von MCDConnectedDevicesNotificationRegistrationManager
Die Plattform verwendet für die Übermittlung von Befehlen zwischen Geräten Benachrichtigungen. Aus diesem Grund müssen Sie MCDConnectedDevicesNotificationRegistrationManager-Ereignisse registrieren, um sicherzustellen, dass die Cloudregistrierungsstatus für das verwendete Konto gültig sind. Überprüfen Sie den Status mittels ConnectedDevicesNotificationRegistrationState.
[MCDConnectedDevicesPlatform* platform.notificationRegistrationManager.notificationRegistrationStateChanged
subscribe:^(MCDConnectedDevicesNotificationRegistrationManager* manager __unused,
MCDConnectedDevicesNotificationRegistrationStateChangedEventArgs* args __unused) {
// Check state using MCDConnectedDevicesNotificationRegistrationState enum
}
Starten der Plattform
Da die Plattform jetzt initialisiert ist und Ereignishandler vorhanden sind, können Sie mit der Ermittlung von Remotesystemgeräten beginnen.
[MCDConnectedDevicesPlatform* platform start];
Abrufen von Benutzerkonten, die von der App erkannt werden
Es ist wichtig, sicherzustellen, dass die Liste der von der App erkannten Benutzerkonten ordnungsgemäß mit dem MCDConnectedDevicesAccountManager synchronisiert wird.
Verwenden Sie zum Hinzufügen eines neuen Benutzerkontos MCDConnectedDevicesAccountManager.addAccountAsync.
[MCDConnectedDevicesPlatform* platform.accountManager
addAccountAsync:self.mcdAccount
callback:^(MCDConnectedDevicesAddAccountResult* _Nonnull result, NSError* _Nullable error) {
// Check state using **MCDConnectedDevicesAccountAddedStatus** enum
}
Um ein ungültiges Konto zu entfernen, können Sie MCDConnectedDevicesAccountManager.removeAccountAsync verwenden.
[MCDConnectedDevicesPlatform* platform.accountManager
removeAccountAsync:existingAccount
callback:^(MCDConnectedDevicesRemoveAccountResult* _Nonnull result __unused, NSError* _Nullable error) {
// Remove invalid user account
}
Initialisieren eines Kanals für Graph-Benachrichtigungen
Mit dem Project Rome-SDK kann Ihre App unterschiedliche Kanäle abonnieren, um verschiedene Typen von Benutzerdaten zu empfangen und zu verwalten – einschließlich Graph-Benachrichtigungen, Benutzeraktivitäten u.v.m. Diese werde alle in MCDUserDataFeed gespeichert und synchronisiert. MCDUserNotification ist die Klasse und der Datentyp, die einer über Graph-Benachrichtigungen gesendeten Benachrichtigung für Benutzer entsprechen. Für die Integration in Graph-Benachrichtigungen und den Empfang einer vom App-Server veröffentlichten MCDUserNotification müssen Sie zunächst den Benutzerdatenfeed initialisieren, indem Sie einen MCDUserNotificationChannel erstellen. Sie sollten dabei wie im obigen Schritt für die Plattforminitialisierung vorgehen: Immer wenn die App in den Vordergrund gelangt (jedoch nicht vor der Plattforminitialisierung) sollte dies überprüft und möglicherweise wiederholt werden.
Mit den folgenden Methoden wird ein MCDUserNotificationChannel initialisiert.
// You must be logged in to use UserNotifications
NSArray<MCDUserAccount*>* accounts = [[AppDataSource sharedInstance].accountProvider getUserAccounts];
if (accounts.count > 0)
{
// Get a UserNotification channel, getting the default channel
NSLog(@"Creating UserNotificationChannel");
NSArray<MCDUserAccount*>* accounts = [[AppDataSource sharedInstance].accountProvider getUserAccounts];
MCDUserDataFeed* userDataFeed = [MCDUserDataFeed userDataFeedForAccount:accounts[0]
platform:[AppDataSource sharedInstance].platform
activitySourceHost:CROSS_PLATFORM_APP_ID];
NSArray<MCDSyncScope*>* syncScopes = @[ [MCDUserNotificationChannel syncScope] ];
[userDataFeed addSyncScopes:syncScopes];
self.channel = [MCDUserNotificationChannel userNotificationChannelWithUserDataFeed:userDataFeed];
}
else
{
NSLog(@"Must log in to receive notifications for the logged in user!");
self.createNotificationStatusField.text = @"Need to be logged in!";
}
Jetzt benötigen Sie einen MCDUserNotificationChannel-Verweis in channel
.
Erstellen eines MCDUserNotificationReader, um eingehende MCDUserNotifications zu empfangen und auf den MCDUserNotification-Verlauf zuzugreifen
Wie bereits gezeigt, fungiert die anfängliche APNs-Nachricht im Hintergrund lediglich als Signal. Sie müssen diese Signalnutzlast an die Plattform für verbundene Geräte übergeben, damit das SDK eine vollständige Synchronisierung mit dem Server der Plattform für verbundene Geräte, die sämtliche vom App-Server veröffentlichten MCDUserNotifications enthält, ausführt. Dadurch wird die vollständige Benachrichtigungsnutzlast, die vom App-Server veröffentlicht wurde und die dem Signal entspricht, abgerufen (und falls vorherige Benachrichtigungen veröffentlicht, jedoch aufgrund von Geräteverbindungsproblemen oder anderen Problemen nicht im App-Client empfangen wurden, werden diese ebenfalls abgerufen). Durch diese Echtzeitsynchronisierungen, die kontinuierlich vom SDK ausgeführt werden, kann der App-Client auf den lokalen Cache des MCDUserNotification-Datenfeeds des angemeldeten Benutzers zugreifen. In diesem Fall ermöglicht der MCDUserNotificationReader den Zugriff des App-Clients auf den Datenfeed – um über einen Ereignislistener die neueste Benachrichtigungsnutzlast zu empfangen oder auf die MCDUserNotification-Sammlung zuzugreifen, die als Ansichtsmodell für den Benachrichtigungsverlauf des Benutzers verwendet werden kann.
Empfangen von MCDUserNotifications
Zunächst müssen Sie einen MCDUserNotificationReader instanziieren und alle im Reader bereits vorhandenen MCDUserNotifications abrufen, wenn Sie diese Informationen für die zu aktivierende Erfahrung verwenden möchten. Es ist immer davon ausgehen, dass der App-Server bereits Benachrichtigungen für den angemeldeten Benutzer veröffentlicht hat, da der betreffende Geräteendpunkt möglicherweise nicht der einzige oder nicht der erste Endpunkt ist, auf dem der Benutzer Ihre App installiert hat. Fügen Sie dann einen Ereignislistener hinzu, der ausgelöst wird, wenn die Plattform für verbundene Geräte eine Synchronisierung durchführt und Sie über neue Änderungen zu benachrichtigen hat. Im Fall von Graph-Benachrichtigungen kann es sich bei neuen Änderungen um neue eingehende MCDUserNotifications handeln, die vom App-Server veröffentlicht wurden. Oder es kann sich um MCDUserNotifcation-Aktualisierungen, -Löschungen oder abgelaufene MCDUserNotifications vom Server oder von anderen registrierten Endpunkten handeln, bei denen derselbe Benutzer angemeldet ist.
Tipp
Im Ereignislistener behandeln Sie die Hauptgeschäftslogik und verwenden den Inhalt der Benachrichtigungsnutzlast auf Grundlage Ihrer Szenarien. Wenn Sie derzeit eine APNs-Benachrichtigung im Hintergrund verwenden, um eine visuelle Benachrichtigung in der Mitteilungszentrale auf Betriebssystemebene zu erstellen, oder wenn Sie mit dem Inhalt der Benachrichtigung im Hintergrund Benutzeroberflächenelemente der App aktualisieren, führen Sie dies hier durch.
// Instantiate the reader from a MCDUserNotificationChannel
// Add a data change listener to subscribe to new changes when new notifications or notification updates are received
- (void)setupWithAccount:(MCDUserAccount*)account {
dispatch_async(dispatch_get_global_queue(QOS_CLASS_DEFAULT, 0), ^{
@synchronized (self) {
MCDUserDataFeed* dataFeed = [MCDUserDataFeed userDataFeedForAccount:account platform:_platform activitySourceHost:@"graphnotifications.sample.windows.com"];
[dataFeed addSyncScopes:@[[MCDUserNotificationChannel syncScope]]];
self.channel = [MCDUserNotificationChannel userNotificationChannelWithUserDataFeed:dataFeed];
self.reader = [self.channel createReader];
__weak typeof(self) weakSelf = self;
_readerRegistrationToken = [self.reader addDataChangedListener:^(__unused MCDUserNotificationReader* source) {
NSLog(@"ME123 Got a change!");
if (weakSelf) {
[weakSelf forceRead];
} else {
NSLog(@"ME123 WEAKSELF FOR CHANGES IS NULL!!!");
}
}];
[self forceRead];
}
});
}
// this is your own business logic when the event listener is fired
// In this case, the app reads the existing batch of notifications in the store and handle any new incoming notifications or notification updates after that
- (void)forceRead {
NSLog(@"ME123 Forced to read!");
[self.reader readBatchAsyncWithMaxSize:NSUIntegerMax completion:^(NSArray<MCDUserNotification *> * _Nullable notifications, NSError * _Nullable error) {
if (error) {
NSLog(@"ME123 Failed to read batch with error %@", error);
} else {
[self _handleNotifications:notifications];
NSLog(@"ME123 Have %ld listeners", self.listenerMap.count);
for (void (^listener)(void) in self.listenerMap.allValues) {
NSLog(@"ME123 Calling a listener about an update!");
listener();
}
}
}];
}
Aktualisieren des Status einer vorhandenen MCDUserNotification
Im vorherigen Abschnitt wurde erwähnt, dass manchmal eine über den Reader empfangene MCDUserNotification-Änderung eine Statusaktualisierung einer vorhandenen MCDUserNotification sein kann, die als geschlossen oder gelesen markiert ist. In diesem Fall kann der App-Client auswählen, wie vorzugehen ist, z.B. Aktivieren von universellem Schließen, indem die entsprechende visuelle Benachrichtigung auf dem betreffenden Gerät entfernt wird. Häufig wurde die MCDUserNotification-Änderungsaktualisierung zuvor von Ihrem App-Client initiiert – von einem anderen Gerät aus. Sie können die Zeit der Statusaktualisierung der MCDUserNotifications wählen. In der Regel erfolgt diese jedoch, wenn die entsprechende visuelle Benachrichtigung durch den Benutzer des Geräts behandelt wird. Oder die Benachrichtigung wird vom Benutzer in einer von Ihnen aktivierten In-App-Erfahrung behandelt. Ein Beispiel für diesen Flow wäre etwa: Der App-Server veröffentlicht eine Benachrichtigung an Benutzer A. Benutzer A empfängt diese Benachrichtigung auf seinem PC und seinem Smartphone, auf denen die App-Clients installiert sind. Der Benutzer klickt auf dem PC auf die Benachrichtigung und öffnet die App, um die entsprechende Aufgabe zu behandeln. Der App-Client auf dem PC ruft dann das SDK der Plattform für verbundene Geräte auf, um den Status der entsprechenden Benutzerbenachrichtigung zu aktualisieren, damit diese Aktualisierung auf allen Geräten des Benutzers synchronisiert wird. Die anderen App-Clients, entfernen dann bei Empfang dieser Statusaktualisierung in Echtzeit die entsprechende visuelle Warnung/Nachricht/Popupbenachrichtigung aus der Mitteilungszentrale/dem Infobereich/dem Info-Center des Geräts. So werden Benachrichtigungen auf den Geräten eines Benutzers universell geschlossen.
Tipp
Die MCDUserNotification-Klasse bietet derzeit 2 Typen von Statusaktualisierungen – Sie können den MCDUserNotificationReadState oder den MCDUserNotificationUserActionState ändern und eine eigene Logik für die Vorgehensweise definieren, die beim Aktualisieren von Benachrichtigungen angewendet werden soll. Sie können z.B. den ActionState als „Activated“ oder „Dismissed“ markieren und dann anhand dieses Werts universelles Verwerfen implementieren. Alternativ oder gleichzeitig können Sie den Lesestatus als „Read“ oder „Unread“ markieren und auf dieser Grundlage bestimmen, welche Benachrichtigungen im App-internen Benachrichtigungsverlauf angezeigt werden sollen.
- (void)dismissNotification:(MCDUserNotification*)notification {
@synchronized (self) {
notification.userActionState = MCDUserNotificationUserActionStateDismissed;
[notification saveAsync:^(__unused MCDUserNotificationUpdateResult * _Nullable result, __unused NSError * _Nullable err) {
NSLog(@"ME123 Dismiss notification with result %d error %@", result.succeeded, err);
}];
}
}