Guía de How-To: Integración con notificaciones de Graph (Android)

Las notificaciones de Graph permiten a la aplicación enviar y administrar notificaciones de destino de usuario en varios dispositivos.

Con el SDK del lado cliente de Project Rome en Android, la aplicación Android puede registrarse para recibir notificaciones publicadas desde el servidor de aplicaciones destinado a un usuario que ha iniciado sesión. El SDK permite al cliente de la aplicación recibir nuevas cargas de notificación entrantes, administrar el estado de las notificaciones existentes y recuperar el historial de notificaciones. Para obtener más información sobre las notificaciones y cómo habilita la entrega de notificaciones centradas en el usuario, consulte Introducción a las notificaciones de Microsoft Graph.

Todas las características del SDK de Project Rome, incluidas las Notificaciones de Graph y más, se basan en una plataforma subyacente denominada Plataforma de Dispositivos Conectados. Esta guía está diseñada para guiarle a través de los pasos necesarios para empezar a usar la plataforma de dispositivos conectados y explicar cómo consumir las APIs en el SDK para implementar las características de notificaciones de Graph -specific.

Consulte la página de referencia de API para obtener vínculos a los documentos de referencia relevantes para los escenarios de notificación.

En estos pasos se hace referencia al código de la aplicación de ejemplo de Android de Project Rome.

Para todas las características de dispositivos conectados, necesitará un IDE de desarrollo de aplicaciones android y un dispositivo Android con una de las arquitecturas admitidas (armeabi-v7a, arm64-v8a, x86 o x86_64) o un emulador. El sistema debe ejecutar Android 4.4.2 o posterior.

Configuración preliminar de la plataforma y las notificaciones de dispositivos conectados

Antes de implementar la conectividad remota, hay algunos pasos que debe seguir para proporcionar a la aplicación Android la capacidad de conectarse a dispositivos remotos, así como enviar y recibir notificaciones.

Registro de la aplicación

La autenticación de la cuenta Microsoft (MSA) o Azure Active Directory (AAD) es necesaria para casi todas las características del SDK de Project Rome (la excepción es las API de uso compartido cercanas). Si aún no tiene una MSA y desea usar una, regístrese en account.microsoft.com.

Nota:

Las cuentas de Azure Active Directory (AAD) no se admiten con las API de Device Relay.

Con el método de autenticación elegido, debe registrar la aplicación con Microsoft siguiendo las instrucciones del Portal de registro de aplicaciones. Si no tiene una cuenta de desarrollador de Microsoft, deberá crear una.

Al registrar una aplicación mediante una MSA, debe recibir una cadena de identificador de cliente. Guárdelo para más adelante. Esto permitirá que la aplicación acceda a los recursos de la Plataforma de dispositivos conectados de Microsoft. Si usa AAD, consulte Bibliotecas de autenticación de Azure Active Directory para obtener instrucciones sobre cómo obtener la cadena de identificador de cliente.

Adición del SDK

Inserte las referencias del repositorio siguientes en el archivo build.gradle en la raíz del proyecto.

allprojects {
    repositories {
        jcenter()
    }
}

A continuación, inserte la siguiente dependencia en el archivo build.gradle que se encuentra en la carpeta del proyecto.

dependencies { 
    ...
    implementation 'com.microsoft.connecteddevices:connecteddevices-sdk:+'
}

En el archivo AndroidManifest.xml del proyecto, agregue los siguientes permisos dentro del <manifest> elemento (si aún no están presentes). Esto concede a la aplicación permiso para conectarse a Internet y habilitar la detección de Bluetooth en el dispositivo.

Tenga en cuenta que los permisos relacionados con Bluetooth solo son necesarios para usar la detección de Bluetooth; no son necesarios para las otras características de la plataforma de dispositivos conectados. Además, ACCESS_COARSE_LOCATION solo se requiere en los SDK de Android 21 y versiones posteriores. En los SDK de Android 23 y versiones posteriores, el desarrollador también debe pedir al usuario que conceda acceso a la ubicación en tiempo de ejecución.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

A continuación, vaya a la clase(es) de actividad donde desea que viva la funcionalidad Dispositivos conectados. Importe los siguientes paquetes.

import com.microsoft.connecteddevices;
import com.microsoft.connecteddevices.remotesystems;
import com.microsoft.connecteddevices.remotesystems.commanding;

Configuración de la autenticación y la administración de cuentas

La plataforma de dispositivos conectados requiere que se use un token de OAuth válido en el proceso de registro. Puede usar el método preferido para generar y administrar los tokens de OAuth. Sin embargo, para ayudar a los desarrolladores a empezar a usar la plataforma, hemos incluido un proveedor de autenticación como parte de la aplicación de ejemplo de Android que genera y administra tokens de actualización para su comodidad.

Si desea implementar la interfaz ConnectedDevicesAccountManager usted mismo, tome nota de la siguiente información:

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

Si usa una cuenta de AAD, deberá solicitar las siguientes audiencias: "https://cdpcs.access.microsoft.com", "https://cs.dds.microsoft.com", "https://wns.windows.com/", y "https://activity.microsoft.com".

Nota:

Las cuentas de Azure Active Directory (AAD) no se admiten con las API de Device Relay.

Tanto si usa la implementación proporcionada de ConnectedDevicesAccountManager o no, si usa AAD, deberá especificar los siguientes permisos en el registro de su aplicación en el Azure Portal (portal.azure.com > Azure Active Directory > registros de aplicaciones):

• Servicio de flujo de actividades de Microsoft
  • Entrega y modificación de notificaciones de usuario para esta aplicación
  • Leer y escribir la actividad de la aplicación en la fuente de actividades de los usuarios
• Servicio de notificaciones de Windows
  • Conexión del dispositivo al servicio de notificaciones de Windows
• Servicio de directorio de dispositivos de Microsoft
  • Ver la lista de dispositivos
  • Se añadirá a tu lista de dispositivos y aplicaciones.
• Servicio de comandos de Microsoft
  • Comunicarse con los dispositivos del usuario
  • Leer los dispositivos del usuario

Registro de la aplicación para notificaciones push

Registre la aplicación con el soporte técnico de Google for Firebase Cloud Messaging . Asegúrese de anotar el identificador del remitente y la clave de servidor que recibe; los necesitará más adelante.

Una vez registrado, debe asociar la funcionalidad de notificación push con la Plataforma de Dispositivos Conectados en su aplicación.

mNotificationRegistration = new ConnectedDevicesNotificationRegistration();
mNotificationRegistration.setType(ConnectedDevicesNotificationType.FCM);
mNotificationRegistration.setToken(token);
mNotificationRegistration.setAppId(Secrets.FCM_SENDER_ID);
mNotificationRegistration.setAppDisplayName("SampleApp");

Registrar la aplicación en el Centro de desarrollo de Microsoft Windows para experiencias entre dispositivos

Importante

Este paso solo es necesario si desea usar las características de Project Rome para acceder a los datos o realizar solicitudes de dispositivos que no son Windows. Si solo tiene como destino dispositivos Windows, no es necesario completar este paso.

Vaya al Panel del Centro de desarrollo, vaya a Experiencias entre dispositivos en el panel de navegación izquierdo y seleccione Configurar una nueva aplicación entre dispositivos, como se muestra a continuación.

El proceso de incorporación del Centro de desarrollo requiere los pasos siguientes:

• Seleccione plataformas admitidas: seleccione las plataformas en las que la aplicación tendrá presencia y se habilitará para experiencias entre dispositivos. En el caso de la integración de Notificaciones de Graph, puede seleccionar entre Windows, Android y/o iOS.

• Proporcionar identificadores de aplicación: proporcione identificadores de aplicación para cada una de las plataformas donde la aplicación tenga presencia. En el caso de las aplicaciones Android, este es el nombre del paquete que asignó a la aplicación al crear el proyecto. El nombre del paquete se puede encontrar en la consola de Firebase en Información general del proyecto:> General. Puede agregar identificadores diferentes (hasta diez) por plataforma: en caso de que tenga varias versiones de la misma aplicación, o incluso aplicaciones diferentes, que quieran poder recibir las mismas notificaciones enviadas por el servidor de aplicaciones destinado al mismo usuario.

• Proporcione o seleccione los identificadores de aplicación de los registros de aplicaciones de MSA y/o AAD. Estos identificadores de cliente correspondientes al registro de aplicaciones MSA o AAD se obtuvieron en los pasos anteriores.

• Las Graph Notifications y otras funcionalidades de la plataforma de dispositivos conectados aprovechan cada una de las plataformas de notificación nativas en los sistemas operativos principales para enviar notificaciones a los puntos finales de los clientes de la aplicación, es decir, WNS (para UWP de Windows), FCM (para Android) y APNS (para iOS). Proporcione sus credenciales para estas plataformas de notificación para permitir que las notificaciones de Graph entreguen las notificaciones del servidor de aplicaciones al publicar notificaciones dirigidas al usuario. Para Android, habilitar el servicio de mensajería en la nube es un requisito previo para usar las notificaciones de Microsoft Graph. Además, tenga en cuenta que el identificador de remitente necesario corresponde al identificador de remitente de Firebase Cloud Messaging y la clave de API corresponde a la clave de servidor heredado. Ambos se pueden encontrar en Firebase Console - Project - Settings (Consola de Firebase:> Proyecto:> configuración), en la pestaña Mensajería en la nube, como se muestra en la captura de pantalla.

• El último paso es comprobar el dominio de la aplicación entre dispositivos, que actúa como un proceso de comprobación para demostrar que la aplicación tiene la propiedad de este dominio que actúa como una identidad de aplicación entre dispositivos para la aplicación que registró.

Inicialización de un canal de notificación de Graph

El SDK de Project Rome permite a la aplicación suscribirse a diferentes canales con el fin de recibir y administrar varios tipos de datos de usuario, incluidas las notificaciones de grafos, las actividades de usuario, etc. Todos se almacenan y sincronizan en UserDataFeed. UserNotification es la clase y el tipo de datos correspondiente a una notificación dirigida al usuario enviada a través de notificaciones de Graph. Para integrar con Graph Notification y empezar a recibir UserNotification publicado por el servidor de aplicaciones, primero deberá inicializar la fuente de distribución de datos de usuario mediante la creación de un userNotificationChannel. Debe tratar esto como el paso de inicialización de la plataforma mencionado anteriormente: debe comprobarse y, posiblemente, rehacerlo cada vez que la aplicación llegue al primer plano (pero no antes de la inicialización de la plataforma).

Los métodos siguientes inicializan userNotificationChannel.

private UserNotificationChannel mNotificationChannel;
private UserDataFeed mUserDataFeed;

// ...

/**
 * Initializes the UserNotificationFeed.
 */
public void initializeUserNotificationFeed() {

    // define what scope of data this app needs
    SyncScope[] scopes = { UserNotificationChannel.getSyncScope() };

    // Get a reference to the UserDataFeed. This method is defined below
    mUserDataFeed = getUserDataFeed(scopes, new EventListener<UserDataFeed, Void>() {
        @Override
        public void onEvent(UserDataFeed userDataFeed, Void aVoid) {
            if (userDataFeed.getSyncStatus() == UserDataSyncStatus.SYNCHRONIZED) {
                // log synchronized.
            } else {
                // log synchronization not completed.
            }
        }
    });

    // this method is defined below
    mNotificationChannel = getUserNotificationChannel();
}

// instantiate the UserDataFeed
private UserDataFeed getUserDataFeed(SyncScope[] scopes, EventListener<UserDataFeed, Void> listener) {
    UserAccount[] accounts = AccountProviderBroker.getSignInHelper().getUserAccounts();
    if (accounts.length <= 0) {
        // notify the user that sign-in is required
        return null;
    }

    // use the initialized Platform instance, along with the cross-device app ID.
    UserDataFeed feed = UserDataFeed.getForAccount(accounts[0], PlatformBroker.getPlatform(), Secrets.APP_HOST_NAME);
    feed.addSyncStatusChangedListener(listener);
    feed.addSyncScopes(scopes);
    // sync data with the server
    feed.startSync();
    return feed;
}

// use the UserDataFeed reference to create a UserActivityChannel
@Nullable
private UserNotificationChannel getUserNotificationChannel() {
    UserNotificationChannel channel = null;
    try {
        // create a UserNotificationChannel for the signed in account
        channel = new UserNotificationChannel(mUserDataFeed);
    } catch (Exception e) {
        e.printStackTrace();
        // handle exception
    }
    return channel;
}

En este momento, debe tener una referencia UserNotificationChannel en mNotificationChannel.

Crear un UserNotificationReader para recibir userNotifications entrantes y acceder al historial de UserNotification

Como se mostró anteriormente, la notificación inicial de Google Cloud Messaging que llega al cliente de la aplicación solo contiene una pulsación en el hombro y debe pasar esa carga de pulsación de hombro a la Plataforma de dispositivos conectados para desencadenar el SDK para realizar una sincronización completa con el servidor de dispositivos conectados, que contiene todos los UserNotifications publicados por el servidor de aplicaciones. Esto extraerá la carga de notificación completa publicada por el servidor de aplicaciones correspondiente a esta pulsación de hombro (y, en caso de que se publiquen notificaciones anteriores, pero no se hayan recibido en este cliente de la aplicación debido a la conectividad del dispositivo u otros problemas, también se extraerán). Con estas sincronizaciones en tiempo real realizadas constantemente por el SDK, el cliente de la aplicación puede tener acceso a una caché local de esta fuente de datos UserNotification del usuario que ha iniciado sesión. Un UserNotificationReader en este caso permite el acceso del cliente de la aplicación a esta fuente de distribución de datos: para recibir la carga de notificación más reciente a través del agente de escucha de eventos o para acceder a la colección UserNotification completa que se puede usar como modelo de vista del historial de notificaciones del usuario.

Recepción de Notificaciones de Usuario

En primer lugar, debe crear una instancia de UserNotificationReader y obtener todas las notificaciones de usuario existentes presentes en el lector si desea utilizar esa información en la experiencia que está intentando habilitar. Siempre es seguro suponer que el servidor de aplicaciones ya ha publicado notificaciones para este usuario que ha iniciado sesión, dado que este punto de conexión de dispositivo determinado podría no ser el único o el primer punto de conexión que el usuario ha instalado la aplicación.

private static UserNotificationReader mReader;
private static final ArrayList<UserNotification> mHistoricalNotifications = new ArrayList<>();
// Instantiate UserNotificationReader
UserNotificationReaderOptions options = new UserNotificationReaderOptions();
mReader = mNotificationChannel.createReaderWithOptions(options);
// Read any previously published UserNotifications that have not expired yet
mReader.readBatchAsync(Long.MAX_VALUE).thenAccept(new AsyncOperation.ResultConsumer<UserNotification[]>() {
    @Override
    public void accept(UserNotification[] userNotifications) throws Throwable {
        synchronized (mHistoricalNotifications) {
            for (UserNotification notification : userNotifications) {
                if (notification.getReadState() == UserNotificationReadState.UNREAD) {
                    mHistoricalNotifications.add(notification);
                }
            }
        }
 
        if (RunnableManager.getHistoryUpdated() != null) {
            activity.runOnUiThread(RunnableManager.getHistoryUpdated());
        }
    }
});

Ahora, agregue un agente de escucha de eventos que se desencadene cuando la plataforma de dispositivos conectados complete una sincronización y tenga nuevos cambios para notificarle. En el caso de las notificaciones de Graph, los nuevos cambios podrían ser nuevas notificaciones de usuario entrantes publicadas por el servidor de aplicaciones o actualizaciones, eliminaciones y expiraciones de notificaciones de usuario que se produjeron desde el servidor o desde otros puntos de conexión registrados en los que el mismo usuario ha iniciado sesión.

Sugerencia

Este agente de escucha de eventos es donde controlas la lógica empresarial principal y "consumes" el contenido de la carga útil de notificación según tus escenarios. Si actualmente usa el mensaje de datos de Google Cloud Messaging para construir una notificación visual en la bandeja de notificaciones de nivel de sistema operativo, o si usa el contenido de la notificación para actualizar alguna interfaz de usuario en la aplicación, este es el lugar para hacerlo.

mReader.addDataChangedListener(new EventListener<UserNotificationReader, Void>() {
    @Override
    public void onEvent(UserNotificationReader userNotificationReader, Void aVoid) {
        userNotificationReader.readBatchAsync(Long.MAX_VALUE).thenAccept(new AsyncOperation.ResultConsumer<UserNotification[]>() {
        @Override
        public void accept(UserNotification[] userNotifications) throws Throwable {
            boolean updatedNew = false;
            boolean updatedHistorical = false;
            synchronized (sHistoricalNotifications) {
                for (final UserNotification notification : userNotifications) {
                    if (notification.getStatus() == UserNotificationStatus.ACTIVE && notification.getReadState() == UserNotificationReadState.UNREAD) {
                        switch (notification.getUserActionState()) {
                            case NO_INTERACTION:
                                // Brand new notification
                                // Insert business logic to construct a new visual notification in Android notification tray for the user to see
                                // ...
                            case DISMISSED:
                                // Existing notification that is marked as dismissed
                                // An app client receive this type of changes because another app client logged in by the same user has marked the notification as dismissed and the change is fanned-out to everywhere
                                // This state sync across app clients on different devices enable universal dismiss of notifications and other scenarios across multiple devices owned by the same user
                                // Insert business logic to dismiss the corresponding visual notification inside Android system notification tray, to make sure users don’t have to deal with redundant information across devices, and potentially insert this notification in your app’s notification history view
                                // ...
                            default:
                                // Unexpected
                        }
                    } else {
                        // ...
                    }
                }
            }
        }
    });
}
});

Actualizar el estado de un userNotification existente

En la sección anterior, mencionamos que a veces un cambio en la notificación de usuario recibido a través del lector podría ser una actualización de estado de una notificación de usuario existente, ya sea que se marque como descartada o como leída. En este caso, el cliente de la aplicación puede elegir qué hacer, como habilitar el descarte universal quitando la notificación visual correspondiente en este dispositivo en particular. Dando un paso atrás, es posible que el cliente de la aplicación sea quien haya iniciado esta actualización del cambio de notificación de usuario, desde un dispositivo diferente. Puede elegir el momento para actualizar el estado de sus UserNotifications, pero normalmente se actualizan cuando el usuario gestiona la notificación visual correspondiente en ese dispositivo, o cuando el usuario gestiona la notificación más a fondo en alguna funcionalidad dentro de la aplicación que hayas habilitado. Este es un ejemplo del aspecto que tendría el flujo: el servidor de aplicaciones publica una notificación dirigida al usuario A. El usuario A recibe esta notificación tanto en su PC como en su teléfono donde están instalados los clientes de la aplicación. El usuario hace clic en la notificación en el equipo y se dirige a la aplicación para gestionar la tarea correspondiente. A continuación, el cliente de la aplicación de este equipo llamará al SDK de la plataforma de dispositivos conectados para actualizar el estado de userNotification correspondiente para que esta actualización se sincronice en todos los dispositivos de este usuario. Al recibir esta actualización de estado en tiempo real, los demás clientes de la aplicación quitarán la alerta visual correspondiente, mensaje o notificación del sistema del centro de notificaciones del dispositivo, bandeja de notificaciones o centro de actividades. Así es como las notificaciones se descartan universalmente en los dispositivos de un usuario.

Sugerencia

La clase UserNotification proporciona actualmente dos tipos de actualizaciones de estado: puede modificar UserNotificationReadState o UserNotificationUserActionState y definir su propia lógica sobre lo que debe ocurrir cuando se actualizan las notificaciones. Por ejemplo, puede marcar UserActionState para activarlo o descartarlo, y utilizar ese valor como referencia para implementar el descarte universal. Como alternativa, o al mismo tiempo, puede marcar el estado de lectura como Leído o No Leído y, en función de ello, determinar qué notificaciones deben aparecer en la vista de historial de notificaciones en la aplicación. En el fragmento de código siguiente se muestra cómo marcar UserNotificationUserActionState de una notificación como Descartada.

public void dismissNotification(int position) {
    final UserNotification notification = mNewNotifications.get(position);
          
    notification.setUserActionState(UserNotificationUserActionState.DISMISSED);
    notification.saveAsync();
}