Integrar la aplicación iOS al SDK del lado cliente para las notificaciones de usuario

Después de registrar tu aplicación en el Portal de Azure e incorporar las experiencias en todos los dispositivos en el Centro de desarrollo de partners, el siguiente paso es integrar tu aplicación cliente con el SDK del lado cliente para las aplicaciones iOS.

Con el SDK de cliente, la aplicación puede realizar los pasos de registro necesarios para empezar a recibir notificaciones publicadas desde el servidor de aplicación dirigidas al usuario que ha iniciado sesión. Luego, el SDK administra las notificaciones en el lado cliente y se encarga de recibir nuevas notificaciones entrantes, administrar el estado de notificaciones para conseguir escenarios como el descarte universal y recuperar el historial completo de notificaciones.

Nuevo flujo de notificaciones entrantes

Para recibir nuevas notificaciones entrantes, se muestra el flujo de datos en el siguiente diagrama.

Nuevo flujo de notificaciones para la aplicación de iOS

Este proceso incluye algunos componentes:

  • Servidor de aplicaciones: el back-end de la aplicación
  • Cliente de la aplicación: el front-end de la aplicación (una aplicación UWP, una aplicación de Android o una aplicación de iOS)
  • Notificaciones de Microsoft Graph: el componente del servicio que permite publicar, almacenar y sincronizar las notificaciones de usuario entre diferentes instancias de clientes de la aplicación en varios dispositivos y plataformas
  • Apple Push Notification Service - el servicio de notificación de inserción de Apple proporcionado por Apple para aplicaciones de iOS. Las notificaciones de Microsoft Graph usan este servicio para informar a los clientes de la aplicación de iOS sobre los cambios de datos de notificación de usuario.

El diagrama muestra los pasos siguientes:

  1. Lógica de la aplicación. Este paso captura lo que desencadena que la notificación se publique para el usuario. Se trata de una lógica específica de la aplicación y puede ser un evento o una actualización de datos sobre algo más en Microsoft Graph, como un nuevo evento de calendario o asignación de tareas, o de lo contrario, el servicio de aplicaciones sobre el que se quiere notificar al usuario.
  2. El servidor de aplicaciones publica una notificación para el usuario de destino a través de la API de notificaciones de Microsoft Graph. Para obtener más información, vea integración del lado servidor.
  3. Al recibir la solicitud web que contiene la nueva notificación, las notificaciones de Microsoft Graph conservan el contenido de la notificación de forma segura en la nube para esta aplicación y este usuario.
  4. Para cada instancia del cliente de la aplicación que se subscriba para recibir notificaciones para este usuario, las notificaciones de Microsoft Graph envían una señal para notificar al cliente de la aplicación, mediante el servicio de inserción nativo que proporciona el sistema operativo. En este caso, la aplicación es una aplicación iOS en Windows y usa la [notificación de actualización de fondo de Apple Push Notification Service] para enviar la señal.
  5. Después de que la notificación de inserción entrante señale la aplicación, se pide al SDK que obtenga los cambios en la tienda de notificación de usuario.
  6. El SDK establece una conexión segura y conforme con el almacén de notificaciones de usuario en Microsoft Graph.
  7. El SDK obtiene los cambios de datos, en este caso, el contenido de la nueva notificación.
  8. El SDK desencadena la devolución de la llamada de evento para notificar a la aplicación cuando se recuperen correctamente los cambios.
  9. Lógica de la aplicación. Este paso captura lo que la aplicación decide realizar dentro de la devolución de llamada de evento. Normalmente, esto resulta en cambios de datos de la aplicación local y actualizaciones de la interfaz de usuario local. En este caso, la aplicación crea normalmente una alerta de iOS para notificar al usuario el contenido de la notificación.

Flujo de actualización de notificaciones

Una de las principales ventajas del uso de las notificaciones de Microsoft Graph es que conservan las notificaciones en la nube de forma segura y las convierte en un tipo de recurso con estado. Por ello, puede ayudar a la aplicación a administrar y sincronizar el estado correcto de las notificaciones en varios dispositivos para el mismo usuario que ha iniciado sesión en varios dispositivos. Cuando se marca una notificación como descartada o leída en un dispositivo, los demás dispositivos pueden ser notificados en tiempo real. "Controlada una vez, descartada en todas partes" puede ser una verdadera promesa como parte de la experiencia de notificación de los usuarios.

El siguiente diagrama muestra el flujo de datos para cambiar el estado de una notificación o eliminar la notificación en un dispositivo, la recepción y manipulación del cambio de estado o la eliminación en otro dispositivo.

Actualizar flujo de notificaciones para la aplicación de iOS

Observe que la segunda parte del flujo es similar al flujo para controlar las nuevas notificaciones entrantes. Esto es así por diseño: el patrón de programación del SDK está diseñado para que el cliente de la aplicación pueda controlar todos los tipos de cambio de datos de notificación de usuario (nuevas notificaciones entrantes, cambios de estado de la notificación, notificación eliminada) de forma similar.

El diagrama muestra los pasos siguientes:

  1. Lógica de la aplicación. Algo desencadena el cambio o la eliminación de la notificación. En general, cualquier evento puede desencadenar el cambio de una notificación.
  2. La aplicación llama al SDK del cliente para actualizar o eliminar una notificación. Actualmente, exponemos dos propiedades sobre los cambios de estado, userActionState y readState, pero la aplicación puede definir estos estados y cuándo deben actualizarse. Por ejemplo, cuando un usuario descarta la notificación emergente, puede actualizar userActionState como Descartado. Cuando un usuario hace clic en la notificación emergente e inicia la aplicación para consumir contenido de aplicación correspondiente, puede actualizar userActionState como Activado y readState como Leído.
  3. Después de llamar a la API correspondiente para actualizar o eliminar una notificación, el SDK realizará una llamada al almacén de notificaciones del usuario en la nube para distribuir este cambio a las demás instancias de cliente de la aplicación con el mismo usuario que ha iniciado sesión.
  4. Al recibir la solicitud de actualización o eliminación de un cliente, las notificaciones de Microsoft Graph actualizan el almacén de notificaciones e identifican las demás instancias del cliente de la aplicación que se suscribió a este cambio.
  5. Para cada suscripción del cliente de la aplicación, las notificaciones de Microsoft Graph envían una señal para notificar al cliente de la aplicación, mediante el servicio de inserción nativo que proporciona el sistema operativo. En este caso, la aplicación es una aplicación iOS y usa la notificación de actualización de fondo de Apple Push Notification Service para enviar la señal.
  6. Después de que la notificación de inserción entrante señale la aplicación, se pide al SDK que obtenga los cambios en la tienda de notificación de usuario.
  7. El SDK establece una conexión segura y conforme con el almacén de notificaciones de usuario en Microsoft Graph.
  8. El SDK obtiene los cambios de datos, en este caso, las actualizaciones de estado de notificación o las eliminaciones de las notificaciones.
  9. El SDK desencadena la devolución de la llamada de evento para notificar a la aplicación cuando se recuperen correctamente los cambios.
  10. Lógica de la aplicación. Este paso captura lo que la aplicación decide realizar dentro de la devolución de llamada de evento. Normalmente, esto resulta en cambios de datos de la aplicación local y actualizaciones de la interfaz de usuario local. En este caso, como hay actualizaciones de notificación, la aplicación debe actualizar la interfaz de usuario local para reflejar el cambio de estado. Por ejemplo, si una notificación se marca como activada, puede quitar la interfaz de usuario de la alerta correspondiente en el centro de notificaciones de iOS para lograr el objetivo de "manejada una vez, descartada en todas partes".

Para obtener más información sobre las notificaciones de Microsoft Graph, vea Introducción a las notificaciones de Microsoft Graph. Para obtener más información sobre los pasos necesarios para integrar las notificaciones de Microsoft Graph de un extremo a otro, vea la Introducción a la integración de las notificaciones de Microsoft Graph.

Agregar el SDK al proyecto

La forma más sencilla de agregar la Plataforma de dispositivos conectados a la aplicación de iOS es mediante el administrador de dependencias CocoaPods. Vaya al Podfile de su proyecto iOS e inserte la siguiente entrada:

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

Para poder consumir CocoaPod, debe usar el archivo .xcworkspace en el proyecto.

Iniciar las Plataformas de dispositivos conectados

El SDK del lado cliente se basa en una infraestructura llamada Plataforma de dispositivos conectados. Antes de poder utilizar cualquier característica, debe inicializar la plataforma en la aplicación. Los pasos de inicialización deberían aparecer en el método AppDelegate, ya que son necesarios antes de que puedan tener lugar los escenarios de notificación.

Debe crear e iniciar la plataforma con una instancia de la clase MCDConnectedDevicesPlatform. Antes de hacerlo, asegúrese de conectar los controladores de eventos, como se muestra, porque después de iniciar la plataforma, puede que los eventos comiencen a activarse.

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];

Control de los tokens de acceso de cuentas

Todas las llamadas web que realiza el SDK, incluidas las llamadas para recuperar el contenido de una nueva notificación entrante, actualizar los estados de notificación y mucho más, leen de o escriben en los datos del usuario y, por ello, siempre requieren un token de acceso válido. El SDK requiere que controle los eventos siguientes, invocados cuando se solicita o se invalida un token de acceso, para asegurarse de que una vez iniciada la plataforma, el token de acceso para el usuario se controla correctamente.

accessTokenRequested

Para una implementación completa, vea la aplicación de ejemplo de iOS.

accessTokenInvalidated

Para una implementación completa, vea la aplicación de ejemplo de iOS.

[platform.accountManager.accessTokenInvalidated
    subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
        MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
}];

Controlar la expiración del registro push

Las notificaciones de Microsoft Graph usan Apple Push Notification Service, la plataforma de inserción nativa de iOS, para señalar a la aplicación cliente cambios de datos de notificaciones del usuario. Esto ocurre cuando nuevas notificaciones entrantes se publican desde el servidor de aplicaciones o cuando se actualiza el estado de las notificaciones en otro dispositivo con el mismo usuario que ha iniciado sesión en un escenario con varios dispositivos.

Por este motivo, es necesario un canal Apple Push Notification Service válido que permita que las notificaciones de actualización de segundo plano lleguen correctamente. La siguiente devolución de llamada de evento controla la expiración del token de inserción Apple Push Notification Service.

notificationRegistrationStateChanged

Para una implementación completa, vea la aplicación de ejemplo de iOS.

Iniciar sesión del usuario

Las notificaciones de Microsoft Graph, como muchos otros tipos de recursos de Microsoft Graph, están centralizadas en los usuarios. Para que la aplicación se suscriba y empiece a recibir notificaciones para el usuario que ha iniciado sesión, primero debe obtener un token de OAuth válido que se usará en el proceso de registro. Puede usar el método preferido para crear y administrar los tokens de OAuth. La aplicación de ejemplo usa ADAL.

Si usa una cuenta de Microsoft, deberá incluir los permisos siguientes en la solicitud de inicio de sesión: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry y https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.

Si usa una cuenta de Azure AD, deberá solicitar la audiencia siguiente: https://cdpcs.access.microsoft.com.

Agregar la cuenta del usuario a la plataforma

Debe registrar la cuenta del usuario que ha iniciado sesión con el SDK. Esto implica agregar la cuenta y registrar un canal de inserción para recibir las notificaciones de inserción iniciales por Apple Push Notification Service. Para obtener más información, consulte el método prepareAccountAsync del ejemplo.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
MCDConnectedDevicesAccount* mcdAccount = [MCDConnectedDevicesAccount new];

[platform.accountManager addAccountAsync:mcdAccount callback:adapter]; 

Suscribirse para recibir notificaciones de usuario

Deberá crear una instancia de un objeto UserDataFeed para la aplicación de este usuario que ha iniciado sesión. La aplicación se identifica con el Id. de aplicación multiplataforma que proporcionó durante el proceso de incorporación de las experiencias en varios dispositivos.

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

Recibir y administrar las notificaciones de usuario

El diagrama de flujo representado anteriormente en este tema muestra que los patrones de programación para controlar las nuevas notificaciones entrantes desde un servidor de aplicaciones y una actualización o eliminación de notificación iniciadas desde otra instancia de cliente de la aplicación son similares. A continuación se muestran los pasos para manejar estos cambios de datos.

Controlar la señal de notificación de inserción entrante

Todos los tipos de cambios de datos de notificación de usuario generan una señal que se entrega a los clientes de la aplicación como una notificación de inserción. En el caso de una aplicación de iOS, la señal se entrega como una notificación de actualización de fondo de Apple Push Notification Service. Al recibir la señal del mensaje de datos, la aplicación debe llamar a TryParse para desencadenar el SDK y obtener los cambios de datos reales desde el servicio de notificaciones de Microsoft Graph.

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

Controlar los cambios de datos de notificación de usuario

Después de que el SDK haya obtenido correctamente los cambios de datos, se invoca una devolución de llamada de evento y se espera que el cliente de la aplicación administre la creación, la actualización o la eliminación de la notificación.

[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;
        }
        }
    }
}];

Actualizar el estado de una notificación

Si se inicia un cambio de estado de notificación de esta instancia del cliente de aplicación (por ejemplo, si un usuario ha activado la notificación del sistema emergente en este dispositivo), la aplicación debe llamar al SDK para actualizar el estado de la notificación para que este cambio de estado se sincronice en todos los dispositivos que usa el mismo usuario.

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

Eliminar notificaciones

Si la eliminación de una notificación se inicia desde esta instancia de cliente de aplicación (por ejemplo, si la tarea correspondiente a esta notificación se marca como completada y se elimina de la base de datos de la aplicación), la aplicación debe llamar al SDK para eliminar la notificación y sincronizar esta operación de eliminación en todos los dispositivos que ha usado el mismo usuario.

Una notificación se elimina del almacén de notificaciones del usuario solo si ha expirado o se ha eliminado de forma explícita. No se elimina la notificación de usuario al actualizar UserActionState como Descartado, porque la definición semántica de UserActionState la define la misma aplicación.

- (void)deleteNotification:(MCDUserNotification*)notification {
    [_channel deleteUserNotificationAsync:notification.notificationId
     completion:^(__unused MCDUserNotificationUpdateResult* _Nullable result, NSError* _Nullable error) {
        // handle result;
     }];
}

Vea también