guida How-To: Integrazione con le notifiche graph (iOS)

Con Graph Notifications la tua app può inviare e gestire notifiche destinate agli utenti tra più dispositivi.

Con Project Rome SDK sul lato client in iOS la tua app iOS può registrarsi per ricevere le notifiche pubblicate dal server applicazioni destinate a un utente connesso. L'SDK consente al client dell'app di ricevere i payload delle nuove notifiche in ingresso, gestire lo stato di quelle esistenti e recuperare la cronologia delle notifiche. Per altre informazioni su Notifications e su come consente il recapito delle notifiche incentrato sull'utente, vedi la panoramica su Microsoft Graph Notifications.

Tutte le funzionalità di Project Rome SDK, tra cui Graph Notifications e molto altro, si basano su una piattaforma sottostante chiamata piattaforma dispositivi connessi. Questa guida è pensata come supporto durante l'esecuzione dei passaggi necessari per iniziare a usare la piattaforma dispositivi connessi e illustra come usare le API nell'SDK per implementare le funzionalità specifiche di Graph Notifications.

La procedura seguente farà riferimento a codice dell'app di esempio per iOS di Project Rome disponibile in GitHub.

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

Configurazione della piattaforma dispositivi connessi e delle notifiche

Registrare l'app

È richiesta l'autenticazione con account Microsoft (MSA) o di Azure Active Directory (AAD) per quasi tutte le funzionalità di Project Rome SDK, ad eccezione delle API di condivisione in prossimità. Se non hai già un account Microsoft e vuoi usarne uno, registrati in account.microsoft.com.

Nota

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

Usando il metodo di autenticazione scelto, devi registrare l'app in Microsoft seguendo le istruzioni nel portale di registrazione delle applicazioni. Se non hai un account per sviluppatore Microsoft, dovrai crearne uno.

Quando registri un'app usando un account Microsoft, dovresti ricevere una stringa di ID client. Salvala per usarla in seguito. Ciò consentirà alla tua app di accedere alle risorse della piattaforma dispositivi connessi di Microsoft. Se usi AAD, vedi Librerie di autenticazione di Azure Active Directory per istruzioni su come ottenere la stringa di ID client.

Aggiungere l'SDK

Il modo più semplice per aggiungere la piattaforma dispositivi connessi all'app iOS consiste nell'usare il gestore delle dipendenze CocoaPods. Passa al Podfile del progetto iOS e inserisci 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

Nota

Per utilizzare CocoaPod, devi usare il file con estensione 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 consentire agli sviluppatori di iniziare a usare la piattaforma, è stato incluso un provider di autenticazione come parte dell'app di esempio per iOS, che puoi usare per generare e gestire i token di aggiornamento nella tua app.

Se non usi il codice fornito, dovrai implementare manualmente l'interfaccia MCDConnectedDevicesAccountManager.

Se usi un account Microsoft, includi 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".

Nota

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 l'implementazione MCDConnectedDevicesAccountManager specificata, se si usa AAD, è necessario specificare le autorizzazioni seguenti nella registrazione dell'app nel portale di Azure (portal.azure.com Azure Active Directory > Registrazioni app>):

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

Registrare l'app per le notifiche push

Registra l'applicazione in Apple per il supporto del servizio APN (Apple Push Notification). Assicurati di prendere nota dell'ID del mittente e della chiave del server ricevuti perché ti serviranno in seguito.

Dopo aver completato la registrazione, devi 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

Avviso

Questo passaggio è obbligatorio solo se vuoi usare le funzionalità di Project Rome per accedere ai dati da o inviare richieste di dispositivi non Windows. Se si usano solo dispositivi Windows come destinazione, non devi completare questo passaggio.

Registra l'app per la funzionalità per le esperienze tra dispositivi del dashboard per sviluppatori Microsoft. Si tratta di una procedura diversa dalla registrazione dell'app per MSA e AAD descritta in precedenza. L'obiettivo principale di questo processo è definire il mapping tra le identità di app specifiche della piattaforma e un'identità di app multipiattaforma che sia riconosciuta dalla piattaforma dispositivi connessi. Questo passaggio consentirà anche l'invio di notifiche tramite i servizi di notifica push nativi corrispondenti alle piattaforme per dispositivi mobili usate dalla tua app. Per iOS consente l'invio delle notifiche agli endpoint delle app iOS tramite il servizio APN (Apple Push Notification).

Vai al dashboard di Dev Center, passa a Esperienze tra dispositivi dal riquadro di spostamento a sinistra e seleziona la configurazione di una nuova app per più 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 con Graph Notifications, puoi selezionare Windows, Android e/o iOS, a seconda della piattaforma in uso.

• Fornisci gli ID app - Specifica gli ID app per ogni piattaforma in uso. Per le app iOS, questo è il nome del pacchetto assegnato all'app quando hai creato il progetto. Tieni presente che puoi aggiungere ID diversi (fino a dieci) per ogni piattaforma, ad esempio nel caso in cui ci siano più versioni della stessa app o addirittura app differenti, che devono essere in grado di ricevere le stesse notifiche inviate dal server applicazioni destinate allo stesso utente.

• Specifica o seleziona gli ID app dalle registrazioni delle app in MSA e/o AAD ottenuti tramite la procedura di registrazione delle app per MSA/AAD precedente.

• Specifica le tue credenziali per le piattaforme di notifica nativa rilevanti per la tua app (ad esempio WNS per Windows, FCM per Android, e/o il servizio APN per iOS) per abilitare il recapito delle notifiche inviate dal server applicazioni durante la pubblicazione di notifiche destinate agli utenti.

• Infine, verifica il dominio dell'app tra dispositivi per assicurarti che la tua app abbia la proprietà del dominio e possa usarlo come identità tra dispositivi per la tua app.

Uso della piattaforma

Creare un'istanza della piattaforma

Per iniziare, crea semplicemente un'istanza della piattaforma.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];

Sottoscrivere MCDConnectedDevicesAccountManager

La piattaforma richiede l'accesso di un utente autenticato. 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

                 }

Sottoscrivere MCDConnectedDevicesNotificationRegistrationManager

Analogamente, la piattaforma usa le notifiche per il recapito dei comandi tra i dispositivi. Devi pertanto sottoscrivere gli eventi MCDConnectedDevicesNotificationRegistrationManager per assicurarti che gli stati di registrazione del cloud siano validi per l'account in uso. Verifica lo stato tramite 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 i gestori eventi sono presenti, si è pronti per avviare l'individuazione dei dispositivi del sistema remoto.

[MCDConnectedDevicesPlatform* platform start];

Recuperare gli account utente noti all'app

È importante assicurarsi che l'elenco degli account utente noto per l'app sia sincronizzato correttamente con MCDConnectedDevicesAccountManager.

Usa 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, puoi 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 alla tua app di sottoscrivere diversi canali per ricevere e gestire vari tipi di dati utente, incluse notifiche di Graph Notifications, attività utente e altro ancora. Tutti questi dati sono archiviati e sincronizzati in MCDUserDataFeed. MCDUserNotification costituisce la classe e il tipo di dati corrispondenti a una notifica mirata all'utente inviata tramite Graph Notifications. Per consentire l'integrazione con Graph Notifications e iniziare a ricevere notifiche di tipo MCDUserNotification pubblicate dal server applicazioni, per prima cosa dovrai inizializzare il feed dei 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 consentono di inizializzare 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, dovrebbe essere presente un riferimento a MCDUserNotificationChannel in channel.

Creare un MCDUserNotificationReader per ricevere notifiche di tipo MCDUserNotification in ingresso e accedere alla cronologia di MCDUserNotification

Come illustrato in precedenza, il messaggio automatico iniziale di APNS in arrivo nel client dell'app è semplicemente un avviso e occorre passare questo payload alla piattaforma dispositivi connessi per attivare l'SDK per l'esecuzione di una sincronizzazione completa con il server dispositivi connessi, che contiene tutte le notifiche MCDUserNotification pubblicate dal server applicazioni. In questo modo verrà scaricato il payload della notifica completa pubblicato dal server applicazioni corrispondente a questo avviso (e in caso di notifiche precedenti pubblicate ma non ricevute nel client dell'app a causa di problemi di connettività dei dispositivi o di altro tipo, anch'esse verranno scaricate). Con queste sincronizzazioni in tempo reale eseguite costantemente dall'SDK, il client dell'app è in grado di accedere a una cache locale del feed dei dati di tipo 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 della notifica più recente tramite il listener di eventi o per accedere alla raccolta MCDUserNotification completa utilizzabile come modello di visualizzazione della cronologia delle notifiche dell'utente.

Ricezione di notifiche MCDUserNotification

Per prima cosa dovrai creare un'istanza di MCDUserNotificationReader e ottenere tutte le notifiche MCDUserNotification esistenti già presenti nel lettore, se sei interessato a utilizzare queste informazioni per l'esperienza che intendi garantire. È opportuno partire sempre dal presupposto che il server applicazioni abbia già pubblicato le notifiche per l'utente connesso, dal momento che questo particolare endpoint del dispositivo potrebbe non essere l'unico o il primo endpoint in cui l'utente ha installato l'app. È quindi il momento di aggiungere un listener di eventi che viene attivato quando la piattaforma dispositivi connessi completa una sincronizzazione e ha nuove modifiche da notificare. Nel caso di Graph Notifications, le nuove modifiche potrebbero essere nuove notifiche MCDUserNotification in ingresso pubblicate dal server applicazioni o aggiornamenti, eliminazioni e scadenze di MCDUserNotifcation provenienti dal server o da altri endpoint registrati a cui è connesso lo stesso utente.

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 usi la notifica automatica di APNS per costruire una notifica visiva nel centro notifiche a livello del sistema operativo o se usi il contenuto della notifica automatica per aggiornare parte dell'interfaccia utente in-app, questo è il posto giusto per farlo.

// 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 una notifica MCDUserNotification esistente

Nella sezione precedente si è accennato al fatto che a volte una modifica di una notifica MCDUserNotification ricevuta tramite il lettore potrebbe essere un aggiornamento dello stato di una notifica MCDUserNotification esistente, indipendentemente dal fatto che sia contrassegnata come ignorata o 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. Facciamo un passo indietro: il client dell'app spesso è quello che ha avviato questo aggiornamento della modifica di MCDUserNotification, da un dispositivo diverso. Puoi scegliere quando aggiornare lo stato delle tue notifiche MCDUserNotification, ma in genere vengono aggiornate quando la notifica visiva corrispondente viene gestita dall'utente in quel dispositivo o quando viene ulteriormente gestita dall'utente nel corso di un'esperienza in-app. Ecco un esempio di ciò che il flusso sarebbe simile: il server dell'app pubblica una notifica destinata all'utente A. L'utente A riceve questa notifica sul proprio PC e sul suo telefono in cui vengono 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 l'SDK della piattaforma dispositivi connessi per aggiornare lo stato della notifica UserNotification corrispondente, in modo da sincronizzare questo aggiornamento 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 fornisce attualmente due tipi di aggiornamenti di stato: puoi modificare MCDUserNotificationReadState o MCDUserNotificationUserActionState e definire la tua logica personalizzata riguardo a cosa deve accadere quando le notifiche vengono aggiornate. Ad esempio, puoi contrassegnare lo stato di azione come Activated o Dismissed e basarti su questo valore per implementare Universal Dismiss. In alternativa, o contemporaneamente, puoi contrassegnare lo stato di lettura come Read o Unread e in base a ciò determinare quali notifiche dovranno comparire nella visualizzazione della 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);
        }];
    }
}