Guida How-To: Integrazione con le notifiche di Graph (iOS)

Graph Notifications consente all'app di inviare e gestire le notifiche di destinazione utente in più dispositivi.

Con l'SDK client di Project Rome su iOS, la tua app iOS può registrarsi per ricevere notifiche pubblicate dal server della tua app destinate a un utente loggato. L'SDK consente al client dell'app di ricevere nuovi payload di notifica in ingresso, gestire lo stato delle notifiche esistenti e ripetere la cronologia delle notifiche. Per altre informazioni sulle notifiche e sul modo in cui consente il recapito delle notifiche incentrate sull'utente, vedere Panoramica delle notifiche di Microsoft Graph

Tutte le funzionalità di Project Rome SDK, includng Graph Notifications e altro ancora, sono basate su una piattaforma sottostante denominata Piattaforma dispositivi connessi. Questa guida è progettata per illustrare i passaggi necessari per iniziare a usare la piattaforma dispositivi connessi e per spiegare come usare le API nell'SDK per implementare le funzionalità di Graph Notifications -specific.

Questa procedura seguente farà riferimento al codice dell'app di esempio Project Rome iOS disponibile in GitHub.

Visita la pagina Riferimento API per collegamenti alla documentazione di riferimento pertinente per gli scenari di notifica.

Configurazione della piattaforma e delle notifiche dei dispositivi connessi

Registrare l'app

L'autenticazione dell'account Microsoft (MSA) o Di Azure Active Directory (AAD) è necessaria per quasi tutte le funzionalità di Project Rome SDK (l'eccezione è costituita dalle API di condivisione nelle vicinanze). Se non hai già un account Microsoft e vuoi usarne uno, registrati in account.microsoft.com.

Annotazioni

Gli account Azure Active Directory (AAD) non sono supportati con le API Device Relay.

Usando il metodo di autenticazione scelto, è necessario registrare l'app con Microsoft seguendo le istruzioni nel portale di registrazione delle applicazioni. Se non si ha un account per sviluppatore Microsoft, è necessario crearne uno.

Quando si registra un'app utilizzando un account Microsoft, si dovrebbe ricevere una stringa ID client. Salvalo per più tardi. Ciò consentirà all'app di accedere alle risorse della piattaforma dispositivi connessi di Microsoft. Se si usa AAD, vedere Librerie di autenticazione di Azure Active Directory per istruzioni su come ottenere la stringa ID client.

Aggiungere l'SDK

Il modo più semplice per aggiungere la piattaforma dispositivi connessi all'app iOS consiste nell'usare cocoaPods dependency manager. Passare al podfile del progetto iOS e inserire la voce seguente:

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

Annotazioni

Per utilizzare CocoaPod, è necessario usare il file xcworkspace nel progetto.

Configurazione dell'autenticazione e della gestione degli account

La piattaforma dispositivi connessi richiede un token OAuth valido da usare durante il processo di registrazione. Puoi usare il tuo metodo preferito per generare e gestire i token OAuth. Tuttavia, per aiutare gli sviluppatori a iniziare a usare la piattaforma, è stato incluso un provider di autenticazione come parte dell'app di esempio iOS che è possibile usare per generare e gestire i token di aggiornamento nell'app.

Se non si usa il codice fornito, sarà necessario implementare manualmente l'interfaccia MCDConnectedDevicesAccountManager .

Se si utilizza un account Microsoft, includere gli ambiti seguenti nella richiesta di accesso: "wl.offline_access", "ccs.ReadWrite", "dds.read", "dds.register", "wns.connect", "asimovrome.telemetry" e "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp".

Annotazioni

Gli account Azure Active Directory (AAD) non sono supportati con le API Device Relay.

Se usi un account AAD, sarà necessario richiedere i seguenti destinatari: "https://cdpcs.access.microsoft.com", "https://cs.dds.microsoft.com", "https://wns.windows.com/" e "https://activity.microsoft.com".

Se si usa o meno l'implementazione MCDConnectedDevicesAccountManager fornita, se si usa AAD è necessario specificare le autorizzazioni seguenti nella registrazione dell'app nel portale di Azure (portal.azure.com > registrazioni dell'app di Azure Active Directory > ):

• Servizio feed attività Microsoft
  • Distribuire e modificare le notifiche utente per questa app
  • Leggere e scrivere attività dell'app nel feed attività degli utenti
• Servizio di notifica di Windows
  • Connettere il dispositivo al servizio di notifica Windows
• Servizio Microsoft Device Directory
  • Visualizzare l'elenco dei dispositivi
  • Essere aggiunto all'elenco di app e dispositivi
• Servizio comandi Microsoft
  • Comunicare con i dispositivi utente
  • Leggere i dispositivi utente

Registrare l'app per le notifiche push

Registrare l'applicazione con Apple per il supporto di Apple Push Notification . Assicurati di prendere nota dell'ID mittente e della chiave del server ricevuti, poiché ti serviranno in un secondo momento.

Dopo la registrazione, è necessario associare la funzionalità di notifica push alla piattaforma dispositivi connessi nell'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;

Registrare l'app in Microsoft Windows Dev Center per le esperienze tra dispositivi

Avvertimento

Questo passaggio è necessario solo se si vogliono usare le funzionalità di Project Rome per accedere ai dati da o effettuare richieste di dispositivi non Windows. Se si specifica come destinazione solo i dispositivi Windows, non è necessario completare questo passaggio.

Registrare l'app per la funzionalità esperienze tra dispositivi del dashboard per sviluppatori Microsoft. Si tratta di una procedura diversa rispetto alla registrazione delle app MSA e AAD sopra. L'obiettivo principale di questo processo è eseguire il mapping delle identità dell'app specifiche della piattaforma con un'identità di app multipiattaforma riconosciuta dalla piattaforma dispositivi connessi. Questo passaggio abiliterà anche l'invio di notifiche usando i servizi di notifica push nativi corrispondenti alle piattaforme per dispositivi mobili utilizzate dall'app. Per iOS, consente l'invio di notifiche agli endpoint dell'app iOS tramite APNS - Apple Push Notification Service.

Passare a Dashboard di Dev Center, passare a Esperienze tra dispositivi dal riquadro di spostamento a sinistra e selezionare configurazione di una nuova app tra dispositivi.

Il processo di onboarding di Dev Center richiede la procedura seguente:

• Seleziona le piattaforme supportate: seleziona le piattaforme in cui la tua app sarà presente e sarà abilitata per le esperienze tra dispositivi. Nel caso dell'integrazione di Graph Notifications, è possibile selezionare da Windows, Android e/o iOS, a seconda delle piattaforme in uso.

• Specificare gli ID app: specificare gli ID app per ogni piattaforma in uso. Per le app iOS, questo è il nome del pacchetto assegnato all'app al momento della creazione del progetto. Si noti che è possibile aggiungere ID diversi (fino a dieci) per piattaforma: questo è nel caso in cui si disponga di più versioni della stessa app, o anche di app diverse, che vogliono essere in grado di ricevere le stesse notifiche inviate dal server app destinato allo stesso utente.

• Specificare o selezionare gli ID app dalle registrazioni delle app MSA e/o AAD ottenute nei passaggi precedenti di registrazione delle app MSA/AAD.

• Specificare le credenziali per le piattaforme di notifica native rilevanti per l'app (ad esempio WNS per Windows, FCM per Android e/o APNS per iOS) per abilitare il recapito delle notifiche dal server app quando si pubblicano notifiche mirate agli utenti.

• Infine, verificare il dominio dell'app tra dispositivi per assicurarsi che l'app abbia la proprietà del dominio e possa usarla come identità tra dispositivi per l'app.

Uso della piattaforma

Creare un'istanza della piattaforma

Per iniziare, è sufficiente avviare la piattaforma.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];

Iscriviti a MCDConnectedDevicesAccountManager

La piattaforma richiede un utente autenticato per accedere alla piattaforma. Dovrai sottoscrivere gli eventi MCDConnectedDevicesAccountManager per assicurarti che venga usato un account valido.

[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

                 }

Abbonarsi al gestore delle notifiche di registrazione dei dispositivi MCDConnected

Analogamente, la piattaforma usa le notifiche per recapitare comandi tra i dispositivi. Pertanto, è necessario sottoscrivere gli eventi MCDConnectedDevicesNotificationRegistrationManager per assicurarsi che gli stati di registrazione cloud siano validi per l'account in uso. Verificare lo stato usando MCDConnectedDevicesNotificationRegistrationState

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

                     // Check state using MCDConnectedDevicesNotificationRegistrationState enum

                 }

Avviare la piattaforma

Ora che la piattaforma è inizializzata e che sono presenti gestori eventi, è possibile iniziare a individuare i dispositivi di sistema remoti.

[MCDConnectedDevicesPlatform* platform start];

Recuperare gli account utente noti all'app

È importante assicurarsi che l'elenco di account utente noti all'app sia sincronizzato correttamente con MCDConnectedDevicesAccountManager.

Usare MCDConnectedDevicesAccountManager.addAccountAsync per aggiungere un nuovo account utente.

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

     // Check state using **MCDConnectedDevicesAccountAddedStatus** enum

     }

Per rimuovere un account non valido, è possibile usare MCDConnectedDevicesAccountManager.removeAccountAsync

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

                    // Remove invalid user account

     }

Inizializzare un canale di Graph Notifications

Project Rome SDK consente all'app di sottoscrivere diversi canali per ricevere e gestire vari tipi di dati utente, tra cui Graph Notifications, User Activities e altro ancora. Sono tutti archiviati e sincronizzati in MCDUserDataFeed. MCDUserNotification è la classe e il tipo di dati corrispondenti a una notifica di destinazione dell'utente inviata tramite Graph Notifications. Per eseguire l'integrazione con Graph Notification e iniziare a ricevere MCDUserNotification pubblicato dal server app, è prima necessario inizializzare il feed di dati utente creando un MCDUserNotificationChannel. Questa operazione deve essere gestita come il passaggio di inizializzazione della piattaforma descritto in precedenza: deve essere verificata e possibilmente rieseguita ogni volta che l'app passa in primo piano (ma non prima dell'inizializzazione della piattaforma).

I metodi seguenti inizializzano un 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!";
}

A questo punto, è necessario avere un riferimento MCDUserNotificationChannel in channel.

Creare un MCDUserNotificationReader per ricevere MCDUserNotifications in ingresso e accedere alla cronologia MCDUserNotification

Come illustrato in precedenza, il messaggio invisibile all'utente APN iniziale in arrivo sul client dell'app contiene solo un tocco a spalla ed è necessario passare il payload del tocco alla piattaforma dispositivi connessi per attivare l'SDK per eseguire una sincronizzazione completa con il server del dispositivo connesso, che contiene tutti i MCDUserNotification pubblicati dal server app. In questo modo verrà scaricato il payload di notifica completo pubblicato dal server dell'app corrispondente a questa notifica (e nel caso in cui le notifiche precedenti siano state pubblicate ma non ricevute sul client dell'app a causa della connettività del dispositivo o di altri problemi, verranno scaricate anche queste). Con queste sincronizzazioni in tempo reale eseguite costantemente dall'SDK, il client dell'app è in grado di accedere a una cache locale del feed di dati MCDUserNotification dell'utente connesso. Un MCDUserNotificationReader in questo caso consente al client dell'app di accedere a questo feed di dati: per ricevere il payload di notifica più recente tramite listener di eventi o per accedere alla raccolta MCDUserNotification completa che può essere usata come modello di visualizzazione della cronologia delle notifiche dell'utente.

Ricezione di MCDUserNotifications

Prima di tutto è necessario creare un'istanza di MCDUserNotificationReader e ottenere tutte le MCDUserNotification esistenti già memorizzate nel lettore, se si è interessati a utilizzare tali informazioni per migliorare l'esperienza che si sta cercando di abilitare. È sempre consigliabile presupporre che il server app abbia già pubblicato notifiche a questo utente connesso, dato che questo particolare endpoint del dispositivo potrebbe non essere l'unico o il primo endpoint che l'utente ha installato l'app. Aggiungere quindi un listener di eventi che viene attivato quando la piattaforma del dispositivo connesso completa una sincronizzazione e presenta nuove modifiche per notificare l'utente. Nel caso di Graph Notifications, le nuove modifiche potrebbero essere nuove MCDUserNotifications in ingresso pubblicate dal server della tua app, oppure aggiornamenti, eliminazioni e scadenze di MCDUserNotifications che si sono verificati dal server o da altri endpoint registrati a cui lo stesso utente ha eseguito l'accesso.

Suggerimento

Questo listener di eventi è il punto dove puoi gestire la logica di business principale e "utilizzare" il contenuto del payload delle notifiche basato sugli scenari in uso. Se attualmente si usa una notifica invisibile all'utente APNS per costruire una notifica visiva nel Centro notifiche a livello di sistema operativo o se si usa il contenuto nella notifica invisibile all'utente per aggiornare un'interfaccia utente in-app, questa è la posizione in cui eseguire questa operazione.

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

Aggiornare lo stato di un MCDUserNotification esistente

Nella sezione precedente è stato indicato che a volte una modifica MCDUserNotification ricevuta tramite il lettore potrebbe essere un aggiornamento dello stato in un MCDUserNotification esistente, indipendentemente dal fatto che venga contrassegnata come ignorata o contrassegnata come letta. In questo caso il client dell'app può scegliere come procedere, ad esempio abilitando Universal Dismiss tramite la rimozione della notifica visiva corrispondente in questo specifico dispositivo. Facendo un passo indietro, spesso è il client dell'app che, da un dispositivo diverso, ha avviato questo aggiornamento delle modifiche MCDUserNotification. È possibile scegliere il tempo necessario per aggiornare lo stato delle notifiche MCDUserNotification, ma in genere vengono aggiornate quando la notifica visiva corrispondente viene gestita dall'utente nel dispositivo o la notifica viene gestita ulteriormente dall'utente in un'esperienza in-app abilitata. Di seguito è riportato un esempio dell'aspetto del flusso: il server app pubblica una notifica destinata all'utente A. L'utente A riceve questa notifica sia sul PC che sul telefono in cui sono installati i client dell'app. L'utente fa clic sulla notifica nel PC e passa all'app per la gestione dell'attività corrispondente. Il client dell'app in questo PC chiamerà quindi Connected Devices Platform SDK per aggiornare lo stato della notifica utente corrispondente per fare in modo che questo aggiornamento sia sincronizzato tra tutti i dispositivi dell'utente. Gli altri client dell'app, dopo aver ricevuto questo aggiornamento dello stato in tempo reale, rimuoveranno quindi il messaggio, la notifica di tipo avviso popup o l'avviso visivo corrispondente dal centro notifiche o dall'area di notifica del dispositivo. Ecco come le notifiche vengono universalmente ignorate tra i dispositivi di un utente.

Suggerimento

La classe MCDUserNotification offre attualmente 2 tipi di aggiornamenti dello stato: è possibile modificare MCDUserNotificationReadState o MCDUserNotificationUserActionState e definire la propria logica su cosa deve accadere quando le notifiche vengono aggiornate. Ad esempio, è possibile contrassegnare lo stato dell'azione come Attivato o Ignorato e basarsi su quel valore per implementare la disattivazione universale. In alternativa, o contemporaneamente, puoi contrassegnare lo stato di lettura come Lettura o Non letto e in base a ciò determina quali notifiche devono essere visualizzate nella visualizzazione cronologia delle notifiche in-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);
        }];
    }
}