Delen via

How-To Handleiding: Integreren met Graph Notifications (iOS)

Met Graph Notifications kan uw app meldingen voor gebruikersdoelgroepen verzenden en beheren op meerdere apparaten.

Met de Sdk aan de clientzijde van Project Rome in iOS kan uw iOS-app zich registreren om meldingen te ontvangen die zijn gepubliceerd vanaf uw app-server die is gericht op een aangemelde gebruiker. De SDK stelt de app-client in staat nieuwe nettoladingen voor binnenkomende meldingen te ontvangen, de status van de bestaande meldingen te beheren en de meldingsgeschiedenis te herstellen. Zie Microsoft Graph Notifications Overview (Overzicht van Microsoft Graph-meldingen) voor meer informatie over meldingen en hoe dit mensgerichte levering van meldingen mogelijk maakt.

Alle functies in de Project Rome SDK, met inbegrip van Graph Notifications en meer, zijn gebouwd op een onderliggend platform genaamd het Connected Devices Platform. Deze handleiding is ontworpen om u te begeleiden bij de benodigde stappen om aan de slag te gaan met het Platform voor verbonden apparaten en om uit te leggen hoe u API's in de SDK kunt gebruiken om Graph Notifications -specific-functies te implementeren.

In deze stappen hieronder wordt verwezen naar code uit de voorbeeld-app Project Rome iOS die beschikbaar is op GitHub.

Zie de API-referentiepagina voor koppelingen naar de referentiedocumenten die relevant zijn voor meldingsscenario's.

Het platform en meldingen voor verbonden apparaten instellen

Uw app registreren

Verificatie van een Microsoft-account (MSA) of Azure Active Directory (AAD) is vereist voor bijna alle functies van de Project Rome SDK, met uitzondering van de API's voor nabij delen. Als u nog geen MSA hebt en er een wilt gebruiken, registreert u zich op account.microsoft.com.

Opmerking

Azure Active Directory-accounts (AAD) worden niet ondersteund met de Device Relay-API's.

Met behulp van de gekozen verificatiemethode moet u uw app registreren bij Microsoft door de instructies in de portal voor toepassingsregistratie te volgen. Als u geen Microsoft-ontwikkelaarsaccount hebt, moet u er een maken.

Wanneer u een app registreert met behulp van een MSA, moet u een client-id-tekenreeks ontvangen. Sla dit op voor later gebruik. Hierdoor heeft uw app toegang tot de platformbronnen voor verbonden apparaten van Microsoft. Als u AAD gebruikt, raadpleegt u Azure Active Directory-verificatiebibliotheken voor instructies over het ophalen van de client-id-tekenreeks.

De SDK toevoegen

De eenvoudigste manier om het Connected Devices Platform toe te voegen aan uw iOS-app is met behulp van de CocoaPods-afhankelijkheidsmanager . Ga naar het Podfile van uw iOS-project en voeg de volgende vermelding in:

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

Opmerking

Als u CocoaPod wilt gebruiken, moet u het .xcworkspace-bestand in uw project gebruiken.

Verificatie en accountbeheer instellen

Voor het Platform voor verbonden apparaten moet een geldig OAuth-token worden gebruikt in het registratieproces. U kunt uw voorkeursmethode gebruiken voor het genereren en beheren van de OAuth-tokens. Om ontwikkelaars te helpen aan de slag te gaan met het platform, hebben we echter een verificatieprovider opgenomen als onderdeel van de iOS-voorbeeld-app die u kunt gebruiken om vernieuwingstokens in uw app te genereren en te beheren.

Als u de opgegeven code niet gebruikt, moet u zelf de MCDConnectedDevicesAccountManager-interface implementeren.

Als u een MSA gebruikt, neem dan de volgende scopes op in uw aanvraag: "wl.offline_access", "ccs.ReadWrite", "dds.read", "dds.register", "wns.connect", "asimovrome.telemetry", en "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp".

Opmerking

Azure Active Directory-accounts (AAD) worden niet ondersteund met de Device Relay-API's.

Als u een AAD-account gebruikt, moet u de volgende doelgroepen aanvragen: "https://cdpcs.access.microsoft.com", "https://cs.dds.microsoft.com", "https://wns.windows.com/"en "https://activity.microsoft.com".

Of u nu de opgegeven MCDConnectedDevicesAccountManager-implementatie gebruikt of niet, als u AAD gebruikt, moet u de volgende machtigingen opgeven in de registratie van uw app in de Azure-portal (portal.azure.com > Azure Active Directory-app-registraties > ):

  • Service voor Microsoft-activiteitsfeed
    • Gebruikersmeldingen voor deze app leveren en wijzigen
    • App-activiteit lezen en schrijven naar de activiteitsfeed van gebruikers
  • Windows Notification Service
    • Uw apparaat verbinden met Windows Notification Service
  • Microsoft Device Directory Service
    • Uw lijst met apparaten weergeven
    • Worden toegevoegd aan uw lijst met apparaten en apps
  • Microsoft Command Service
    • Communiceren met gebruikersapparaten
    • Gebruikersapparaten lezen

Uw app voor pushmeldingen registreren

Registreer uw toepassing bij Apple voor ondersteuning voor Apple Push Notification . Noteer de afzender-id en serversleutel die u ontvangt, omdat u deze later nodig hebt.

Nadat u zich hebt geregistreerd, moet u de functionaliteit voor pushmeldingen koppelen aan het Platform voor verbonden apparaten in uw app.

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;

Uw app registreren in Microsoft Windows Dev Center voor ervaringen tussen apparaten

Waarschuwing

Deze stap is alleen vereist als u Project Rome-functies wilt gebruiken voor toegang tot gegevens van of aanvragen van niet-Windows-apparaten. Als u zich alleen op Windows-apparaten richt, hoeft u deze stap niet te voltooien.

Registreer uw app voor de functie voor ervaringen op meerdere apparaten van het Microsoft Developer Dashboard. Dit is een andere procedure dan MSA- en AAD-app-registratie hierboven. Het belangrijkste doel van dit proces is om de platformspecifieke app-identiteiten te koppelen aan een platformoverschrijdende app-identiteit die wordt herkend door Connected Devices Platform. Met deze stap kunt u ook meldingen verzenden met behulp van de systeemeigen pushmeldingsservices die overeenkomen met de mobiele platformen die uw app gebruikt. Voor iOS kunnen meldingen via APNS - Apple Push Notification Service naar iOS-app-eindpunten worden verzonden.

Ga naar Het Dashboard van het Ontwikkelaarscentrum, navigeer naar Ervaringen op meerdere apparaten in het navigatiedeelvenster aan de linkerkant en selecteer een nieuwe app voor meerdere apparaten configureren. Dashboard van ontwikkelaarscentrum : ervaringen tussen apparaten

Voor het onboardingproces van het Ontwikkelaarscentrum zijn de volgende stappen vereist:

  • Ondersteunde platforms selecteren: selecteer de platformen waarop uw app aanwezig is en kan worden ingeschakeld voor ervaringen tussen apparaten. In het geval van Graph Notifications-integratie kunt u kiezen uit Windows, Android en/of iOS, afhankelijk van de platforms die u gebruikt. Ervaringen tussen apparaten – ondersteunde platforms

  • Geef app-id's op: geef app-id's op voor elk platform dat u gebruikt. Voor iOS-apps is dit de pakketnaam die u aan uw app hebt toegewezen toen u het project maakte. Houd er rekening mee dat u verschillende id's (maximaal tien) per platform kunt toevoegen. Dit is het geval dat u meerdere versies van dezelfde app of zelfs verschillende apps hebt die dezelfde meldingen willen ontvangen die door uw app-server op dezelfde gebruiker zijn gericht. Ervaringen tussen apparaten : app-id's

  • Geef of selecteer de app-id's uit MSA- en/of AAD-app-registraties die zijn verkregen in de bovenstaande MSA-/AAD-app-registratiestappen. Ervaringen tussen apparaten : MSA- en AAD-app-registraties

  • Geef uw referenties op voor de systeemeigen meldingsplatforms die relevant zijn voor uw app (bijvoorbeeld WNS voor Windows, FCM voor Android en/of APNS voor iOS) om de levering van meldingen van uw app-server mogelijk te maken wanneer u op gebruikers gerichte meldingen publiceert. Apparaatoverstijgende ervaringen – push-credentials

  • Controleer ten slotte het domein van uw app op meerdere apparaten om ervoor te zorgen dat uw app het eigendom van het domein heeft en deze kan gebruiken als een identiteit voor meerdere apparaten voor uw app. Ervaringen tussen apparaten : domeinverificatie

Het platform gebruiken

Een exemplaar van het platform maken

Om aan de slag te gaan, instantieert u het platform.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];

Abonneren op MCDConnectedDevicesAccountManager

Voor het platform is een geverifieerde gebruiker vereist voor toegang tot het platform. U moet zich abonneren op MCDConnectedDevicesAccountManager-gebeurtenissen om ervoor te zorgen dat een geldig account wordt gebruikt.

[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

                 }

Abonneren op MCDConnectedDevicesNotificationRegistrationManager

Op dezelfde manier gebruikt het platform meldingen om opdrachten tussen apparaten te leveren. Daarom moet u zich abonneren op de gebeurtenissen van de MCDConnectedDevicesNotificationRegistrationManager om ervoor te zorgen dat de cloudregistratiestatussen geldig zijn voor het account dat wordt gebruikt. De status controleren met MCDConnectedDevicesNotificationRegistrationState

[MCDConnectedDevicesPlatform* platform.notificationRegistrationManager.notificationRegistrationStateChanged
     subscribe:^(MCDConnectedDevicesNotificationRegistrationManager* manager __unused,
                 MCDConnectedDevicesNotificationRegistrationStateChangedEventArgs* args __unused) {

                     // Check state using MCDConnectedDevicesNotificationRegistrationState enum

                 }

Het platform starten

Nu het platform is geïnitialiseerd en gebeurtenis-handlers aanwezig zijn, kunt u beginnen met het detecteren van externe systeemapparaten.

[MCDConnectedDevicesPlatform* platform start];

Gebruikersaccounts ophalen die bekend zijn bij de app

Het is belangrijk om ervoor te zorgen dat de lijst met gebruikersaccounts die bekend zijn bij de app, correct worden gesynchroniseerd met MCDConnectedDevicesAccountManager.

Gebruik MCDConnectedDevicesAccountManager.addAccountAsync om een nieuw gebruikersaccount toe te voegen.

[MCDConnectedDevicesPlatform* platform.accountManager
     addAccountAsync:self.mcdAccount
     callback:^(MCDConnectedDevicesAddAccountResult* _Nonnull result, NSError* _Nullable error) {

     // Check state using **MCDConnectedDevicesAccountAddedStatus** enum

     }

Als u een ongeldig account wilt verwijderen, kunt u MCDConnectedDevicesAccountManager.removeAccountAsync gebruiken

 [MCDConnectedDevicesPlatform* platform.accountManager
     removeAccountAsync:existingAccount
     callback:^(MCDConnectedDevicesRemoveAccountResult* _Nonnull result __unused, NSError* _Nullable error) {

                    // Remove invalid user account

     }

Een Graph Notification-kanaal initialiseren

Met de Project Rome SDK kan uw app zich abonneren op verschillende kanalen om verschillende typen gebruikersgegevens te ontvangen en te beheren, waaronder Graph Notifications, User Activities en meer. Deze worden allemaal opgeslagen en gesynchroniseerd in MCDUserDataFeed. MCDUserNotification is de klasse en het gegevenstype dat overeenkomt met een door de gebruiker gerichte melding die wordt verzonden via Graph Notifications. Als u wilt integreren met Graph Notification en MCDUserNotification wilt ontvangen die is gepubliceerd door uw app-server, moet u eerst de gebruikersgegevensfeed initialiseren door een MCDUserNotificationChannel te maken. U moet dit behandelen zoals de bovenstaande stap voor het initialiseren van het platform: deze moet worden gecontroleerd en mogelijk opnieuw worden uitgevoerd wanneer de app op de voorgrond komt (maar niet vóór de initialisatie van het platform).

Met de volgende methoden initialiseert u een MCDUserNotificationChannel.

// 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!";
}

Op dit moment moet u een MCDUserNotificationChannel-verwijzing hebben in channel.

Een MCDUserNotificationReader maken om binnenkomende MCDUserNotifications te ontvangen en toegang te krijgen tot MCDUserNotification-geschiedenis

Zoals we eerder hebben laten zien, bevat het eerste APNS stille bericht dat op de app-client binnenkomt alleen een schoudertik, en moet u die payload van de schoudertik doorgeven aan het Platform voor Verbonden Apparaten om de SDK te activeren en een volledige synchronisatie uit te voeren met de server van verbonden apparaten, die alle MCDUserNotifications bevat die door uw app-server zijn gepubliceerd. Hiermee wordt de volledige nettolading voor meldingen opgehaald die is gepubliceerd door uw app-server die overeenkomt met deze schoudertik (en in het geval dat er eerdere meldingen zijn gepubliceerd, maar niet op deze app-client zijn ontvangen vanwege apparaatconnectiviteit of andere problemen, worden ze ook uitgetrokken). Met deze realtime-synchronisaties die voortdurend door de SDK worden uitgevoerd, kan de app-client toegang hebben tot een lokale cache van de MCDUserNotification-gegevensfeed van deze aangemelde gebruiker. Een MCDUserNotificationReader maakt in dit geval de toegang van de app-client tot deze gegevensfeed mogelijk: om de meest recente nettolading voor meldingen te ontvangen via gebeurtenislistener of om toegang te krijgen tot de volledige MCDUserNotification-verzameling die kan worden gebruikt als weergavemodel van de meldingsgeschiedenis van de gebruiker.

MCDUserNotifications ontvangen

Eerst moet u een MCDUserNotificationReader instantiëren en alle bestaande MCDUserNotifications in de lezer ophalen als u deze informatie wilt gebruiken voor de ervaring die u probeert in te schakelen. Het is veilig om ervan uit te gaan dat de app-server al meldingen heeft gepubliceerd naar deze aangemelde gebruiker, aangezien dit specifieke apparaateindpunt mogelijk niet het enige eindpunt is of het eerste eindpunt dat de gebruiker uw app heeft geïnstalleerd. Voeg vervolgens een gebeurtenislistener toe die wordt geactiveerd wanneer het Connected Device Platform een synchronisatie voltooit en nieuwe wijzigingen bevat om u op de hoogte te stellen. In het geval van Graph-meldingen kunnen nieuwe wijzigingen bestaan uit nieuwe binnenkomende MCDUserNotifications die zijn gepubliceerd door uw app-server, of updates, verwijderingen en verlopen van MCDUserNotifications die hebben plaatsgevonden vanaf de server of van andere geregistreerde eindpunten waarmee dezelfde gebruiker is aangemeld.

Aanbeveling

Deze event listener is de plek waar u de belangrijkste bedrijfslogica verwerkt en de inhoud van uw berichtgegevens voor meldingen gebruikt op basis van uw scenario's. Als u momenteel APNS stille melding gebruikt om een visuele melding te maken in het meldingencentrum op besturingssysteemniveau, of als u de inhoud van de stille melding gebruikt om de gebruikersinterface in de app bij te werken, is dit de plek om dat te doen.

// 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();
            }
        }
    }];
}

De status van een bestaande MCDUserNotification bijwerken

In de vorige sectie hebben we vermeld dat soms een MCDUserNotification-wijziging die via de lezer is ontvangen, een statusupdate kan zijn voor een bestaande MCDUserNotification, of deze wordt gemarkeerd als genegeerd of gemarkeerd als gelezen. In dit geval kan de app-client kiezen wat te doen, zoals het inschakelen van universeel afwijzen door de bijbehorende visuele melding van dit specifieke apparaat te verwijderen. Even een stap terug, vaak is uw app-client degene die deze MCDUserNotification-wijzigingsupdate in de eerste plaats heeft geïnitieerd op een ander apparaat. U kunt de tijd kiezen om de status van uw MCDUserNotifications bij te werken, maar meestal worden ze bijgewerkt wanneer de bijbehorende visuele melding wordt verwerkt door de gebruiker op dat apparaat, of de melding wordt verder verwerkt door de gebruiker in een bepaalde in-app-ervaring die u inschakelt. Hier volgt een voorbeeld van hoe de stroom eruit zou zien: uw app-server publiceert een melding die is gericht op Gebruiker A. Gebruiker A ontvangt deze melding op zowel zijn pc als zijn telefoon waarop de app-clients zijn geïnstalleerd. De gebruiker klikt op de melding op de pc en gaat naar de app om de bijbehorende taak af te handelen. De app-client op deze pc roept vervolgens de Connected Devices Platform SDK aan om de status van de bijbehorende gebruikersmelding bij te werken om deze update op alle apparaten van deze gebruiker te laten synchroniseren. De andere app-clients, zodra ze deze statusupdate in realtime ontvangen, zullen de bijbehorende visuele waarschuwing, bericht of pop-upmelding uit het meldingencentrum, de notificatietray of het Actiecentrum van het apparaat verwijderen. Dit is hoe meldingen universeel worden afgehandeld op alle apparaten van een gebruiker.

Aanbeveling

MCDUserNotification-klasse biedt momenteel twee soorten statusupdates: u kunt de MCDUserNotificationReadState of de MCDUserNotificationUserActionState wijzigen en uw eigen logica definiëren over wat er moet gebeuren wanneer meldingen worden bijgewerkt. U kunt bijvoorbeeld de actiestatus markeren als te activeren of te sluiten en gebruik maken van die waarde om universeel sluiten te implementeren. U kunt ook de leesstatus markeren als Gelezen of Ongelezen en op basis daarvan bepalen welke meldingen moeten worden weergegeven in de geschiedenisweergave van de app.

- (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);
        }];
    }
}