Intégrer votre application Android avec le Kit de développement logiciel (SDK) côté client pour les notifications à l’utilisateurIntegrate your Android app with the client-side SDK for user notifications

Une fois l’application inscrite sur le portail Azure et vos expériences inter-appareils intégrées dans le Centre de développement partenaire, vous devez intégrer votre application cliente avec le Kit de développement logiciel (SDK) côté client pour les applications Android.After you register your app in the Azure Portal and onboard your cross-device experiences in the Partner Dev Center, the next step is to integrate your client app with the client-side SDK for Android apps.

Avec le Kit de développement logiciel (SDK) côté client, votre application peut accomplir les étapes d’inscription nécessaires pour commencer à recevoir des notifications publiées par votre serveur d’applications ciblant l’utilisateur actuellement connecté.With the client-side SDK, your app can perform the necessary registration steps to start receiving notifications published from your app server targeted at the user who is currently signed in. Le Kit de développement logiciel (SDK) gère ensuite les notifications côté client, en recevant les nouvelles notifications entrantes, en vérifiant l’état des notifications, par exemple, pour le masquage universel, et en récupérant l’historique complet des notifications.The SDK then manages the notifications on the client side, including receiving new incoming notifications, managing the state of notifications to achieve scenarios like universal dismiss, and retrieving full notification history.

Flux de nouvelle notification entranteNew incoming notification flow

Le flux de données pour la réception de nouvelles notifications entrantes est présenté dans le diagramme suivant.For receiving new incoming notifications, the data flow is shown in the following diagram.

Flux de nouvelle notification pour application Android

Le processus implique quelques composants :he process involves a few components:

  • Serveur d’applications : serveur principal de votre applicationApp server - The back end of your application
  • Client de l’application : serveur frontal de votre application (application UWP, application Android ou application iOS)App client - The front end of your application (a UWP app, an Android app, or an iOS app)
  • Notifications de Microsoft Graph : composant de service qui active la publication, le stockage et la synchronisation des notifications à l’utilisateur dans différentes instances de clients de l’application sur divers appareils et plateformes.Microsoft Graph notifications - The service component that enables user notifications to be published, stored, and synced across different instances of app clients across devices and platforms
  • FCM : Firebase Cloud Messaging, le service de notifications Push fourni par Android dans le cadre des Google Play Services.FCM - Firebase Cloud Messaging, the push notification service provided by Android as a part of Google Play Services. Les notifications de Microsoft Graph utilisent ce service pour signaler aux clients d’applications Android des modifications des données de notification à l’utilisateur.Microsoft Graph notifications use this service to signal the Android app clients about user notification data changes.

Le diagramme présente les étapes suivantes :The diagram shows the following steps:

  1. Logique d’application.Application logic. Cette étape capture ce qui déclenche la publication de la notification à l’utilisateur.This step captures what triggers the notification to be published to the user. Il s’agit d’une logique spécifique de l’application. Ce peut être un événement ou une mise à jour de données concernant quelque chose d’autre dans Microsoft Graph, tel qu’un nouvel événement ou une nouvelle tâche de calendrier, ou quelque chose que votre application souhaite notifier à l’utilisateur.This is app-specific logic, and can be an event or data update about something else in Microsoft Graph, such as a new calendar event or task assignment, or else your app service wants to notify the user about.
  2. Le serveur d’applications publie une notification à l’utilisateur ciblé via l’API de notifications de Microsoft Graph.The app server publishes a notification to the targeted user via the Microsoft Graph notifications API. Pour plus d’informations, voir l’intégration côté serveur.For more details, see server side integration.
  3. À la réception de la demande web contenant la nouvelle notification, l’API de notifications de Microsoft Graph conserve le contenu de la notification en sécurité dans le cloud pour cette application et cet utilisateur.On receiving the web request containing the new notification, Microsoft Graph notifications persists the content of the notification securely in the cloud for this app and this user.
  4. Pour chaque instance de client de l’application qui s’abonne pour recevoir des notifications destinées à cet utilisateur, l’API de notifications de Microsoft Graph envoie un signal pour notifier le client de l’application via le service de notifications Push natif du système d’exploitation.For each app client instance subscribing to receive notifications for this user, Microsoft Graph notifications sends a signal to notify the app client, via the native push service provided by the operating system. En l’occurrence, l’application est une application Android qui utilise le message de données FCM pour envoyer le signal.In this case, the application is an Android app, and it uses FCM data message to send the signal.
  5. Une fois l’application signalée par la notification Push entrante, elle demande au Kit de développement logiciel (SDK) d’extraire les modifications du magasin de notifications à l’utilisateur.After the application is signaled by the incoming push notification, it asks the SDK to fetch for the changes in the user notification store.
  6. Le Kit de développement logiciel (SDK) établit une connexion sécurisée et conforme avec le magasin de notifications à l’utilisateur dans Microsoft Graph.The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  7. Le Kit de développement logiciel (SDK) récupère les modifications des données, en l’occurrence, le contenu de la nouvelle notification.The SDK gets the data changes - in this case, the new notification contents.
  8. Le kit de développement logiciel (SDK) déclenche les rappels d’événements pour notifier l’application une fois les modifications récupérées.The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  9. Logique d’application.Application logic. Cette étape capture ce que votre application choisit de faire dans le rappel d’événement.This step captures what your app chooses to do inside the event callback. Généralement, cela entraîne des modifications des données de l’application locale et des mises à jour de l’interface utilisateur locale.Usually, this results in local app data changes and local UI updates. Dans ce cas, l’application génère habituellement une fenêtre contextuelle de notification toast pour notifier à l’utilisateur le contenu de la notification.In this case, the app usually constructs a toast notification popup to notify the user about the notification contents.

Flux de mise à jour de notificationNotification update flow

L’un des principaux avantages liés à l’utilisation de l’API de notifications de Microsoft Graph est qu’elle conserve les notifications en sécurité dans le cloud et les convertit en un type de ressource avec état.One of the main benefits for using Microsoft Graph notifications is that it persists notifications in the cloud securely and turns them into a stateful resource type. Elle peut donc aider votre application à gérer et à synchroniser l’état correct des notifications sur différents appareils pour le même utilisateur connecté dans un contexte inter-appareils.Therefore, it can help your application to manage and sync the correct state of the notifications across different devices for the same signed in user in a cross-device scenario. Quand une notification est marquée comme masquée ou lue sur un appareil, les autres appareils peuvent être notifiés en temps réel.When a notification is marked as dismissed, or marked as read on one device, the other devices can be notified in real-time. L’approche « traité une fois, masqué partout » peut devenir réellement prometteuse dans le cadre de l’expérience de notification pour vos utilisateurs."Handled once, dismissed everywhere" can become a true promise as part of the notification experience for your users.

Le diagramme suivant illustre le flux de données pour le changement de l’état d’une notification ou la suppression de celle-ci sur un appareil, ainsi que pour la réception/gestion du changement d’état ou de la suppression sur un autre appareil.The following diagram shows the data flow for changing the state of a notification or deleting the notification on one device, and receiving/handling the state change or the deletion on another device.

Mettre à jour le flux de notification pour une application Android

Notez que la deuxième partie du flux est similaire au flux de traitement des nouvelles notifications entrantes.Notice that the second part of the flow is similar to the flow for handling new incoming notifications. Cela est intentionnel. Le modèle de programmation du Kit de développement logiciel (SDK) est conçu pour permettre au client de l’application de gérer tous les types de changements de données de notification à l’utilisateur (nouvelle notification entrante, changement d’état de notification, suppression de notification) de la même façon.This is by design - the programming pattern of the SDK is designed so that the application client can handle all types of user notification data changes (new incoming notifications, notification state changes, notification deleted) in a similar way.

Le diagramme présente les étapes suivantes :The diagram shows the following steps:

  1. Logique d’application.Application logic. Quelque chose déclenche la modification ou la suppression de la notification.Something triggers the notification to be changed or deleted. En général, tout événement peut déclencher une modification de notification.In general, any event can trigger a notification to change.
  2. Application faisant appel au Kit de développement logiciel (SDK) client pour mettre à jour ou supprimer une notification.App calling into the client SDK to update or delete a notification. Actuellement, nous exposons deux propriétés concernant les changements d’état (userActionState et readState) mais votre application peut définir ces états et le moment où ils doivent être mis à jour.Currently, we expose two properties regarding state changes - userActionState and readState - but your application can define these states and when they need to be updated. Par exemple, quand un utilisateur masque la fenêtre contextuelle de notification, vous pouvez mettre à jour l’état userActionState afin qu’il soit masqué.For example, when a user dismisses the notification popup, you can update the userActionState to be Dismissed. Quand un utilisateur clique sur la fenêtre contextuelle de notification et lance l’application pour utiliser le contenu correspondant, vous pouvez mettre à jour l’état userActionState en le définissant comme Activé, et l’état readState en le définissant comme Lu.When a user clicks the notification popup and launches the app to consume corresponding app content, you can update the userActionState to be Activated and update the readState to be Read.
  3. Une fois l’API correspondante appelée pour mettre à jour ou supprimer une notification, le Kit de développement logiciel (SDK) fait appel au magasin de notifications à l’utilisateur dans le cloud pour propager ce changement aux autres instances du client de l’application avec le même utilisateur connecté.After the corresponding API is called to update or delete a notification, the SDK will call into the user notification store in the cloud in order to fan-out this change to the other app client instances with the same signed in user.
  4. Lors de la réception de la demande de mise à jour/suppression d’un client, l’API de notifications de Microsoft Graph met à jour le magasin de notifications et identifie les autres instances du client de l’application abonnées à cette modification.On receiving the update/delete request from a client, Microsoft Graph notifications will update the notification store, and identify the other app client instances that subscribed to this change.
  5. Pour chaque abonnement client, l’API de notifications de Microsoft Graph envoie un signal pour notifier le client de l’application via le service de notifications Push natif du système d’exploitation.For each app client subscription, Microsoft Graph notifications sends a signal to notify the app client, via the native push service provided by the operating system. En l’occurrence, il s’agit d’une application Android qui utilise le message de données FCM pour envoyer le signal.In this case, this is an Android app, and it uses FCM data message to send the signal.
  6. Une fois l’application signalée par la notification Push entrante, elle demande au Kit de développement logiciel (SDK) d’extraire les modifications du magasin de notifications à l’utilisateur.After the application is signaled by the incoming push notification, it asks the SDK to fetch for the changes in the user notification store.
  7. Le Kit de développement logiciel (SDK) établit une connexion sécurisée et conforme avec le magasin de notifications à l’utilisateur dans Microsoft Graph.The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  8. Le Kit de développement logiciel (SDK) récupère les modifications des données, en l’occurrence les mises à jour d’état de notification ou les suppressions de notification.The SDK gets the data changes - in this case, the changes are notification state updates or notification deletions.
  9. Le kit de développement logiciel (SDK) déclenche les rappels d’événements pour notifier l’application une fois les modifications récupérées.The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  10. Logique d’application.Application logic. Cette étape capture ce que votre application choisit de faire dans le rappel d’événement.This step captures what your app chooses to do inside the event callback. Généralement, cela entraîne des modifications des données de l’application locale et des mises à jour de l’interface utilisateur locale.Usually, this results in local app data changes and local UI updates. Dans ce cas, étant donné qu’il existe des mises à jour de notification, l’application doit mettre à jour l’interface utilisateur localement afin qu’elle reflète le changement d’état.In this case, because there are notification updates, the app should update the UI locally to reflect the state change. Par exemple, si une notification est marquée comme activée, vous pouvez supprimer le message de notification correspondant dans la barre de notification d’Android conformément à l’approche « traité une fois, masqué partout ».For example, if a notification is marked as activated, you can remove the corresponding notification message inside Android's notification tray to achieve "handled once, dismissed everywhere".

Pour plus d’informations sur les notifications de Microsoft Graph, voir la vue d’ensemble des notifications de Microsoft Graph.For more information about Microsoft Graph notifications, see Microsoft Graph Notifications overview. Pour plus d’informations sur la procédure à suivre pour l’intégration de bout en bout avec l’API de notifications de Microsoft Graph, voir la vue d’ensemble de l’intégration de l’API de notifications de Microsoft Graph.For more information about the steps required to integrate with Microsoft Graph notifications from end to end, see Microsoft Graph notifications integration overview.

Environnement de développement et configuration requiseDevelopment environment and requirements

Pour utiliser les notifications de Microsoft Graph, vous devez disposer d’un environnement de développement intégré (IDE) d’applications Android et d’un appareil Android doté de l’une des architectures prises en charge (armeabi-v7a, arm64-v8a, x86 ou x86_64) ou d’un émulateur.To use Microsoft Graph notifications, you will need an Android app development IDE and an Android device with one of the supported architectures (armeabi-v7a, arm64-v8a, x86, or x86_64) or an emulator. Le système doit exécuter Android 4.4.2 ou une version ultérieure.The system must be running Android 4.4.2 or later.

Ajout du Kit de développement logiciel (SDK) à votre projetAdding the SDK to your project

Insérez les références de référentiel suivantes dans le fichier build.gradle situé à la racine de votre projet.Insert the following repository references into the build.gradle file at the root of your project.

allprojects {
    repositories {
    jcenter()
    maven { url 'https://maven.google.com' }
    maven { url 'https://projectrome.bintray.com/maven/' }
    }
}

Ensuite, insérez la dépendance suivante dans le fichier build.gradle situé dans le dossier de votre projet.Then, insert the following dependency into the build.gradle file that is in your project folder.

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

Si vous souhaitez utiliser ProGuard dans votre application, ajoutez les règles ProGuard pour ces nouvelles API.If you want to use ProGuard in your app, add the ProGuard Rules for these new APIs. Créez un fichier nommé proguard-rules.txt dans le dossier App de votre projet, puis collez-y le contenu du fichier ProGuard_Rules_for_Android_Rome_SDK.txt.Create a file called proguard-rules.txt in the App folder of your project, and paste in the contents of ProGuard_Rules_for_Android_Rome_SDK.txt. Dans le fichier * AndroidManifest.xml * de votre projet, ajoutez les autorisations suivantes dans l’élément manifest (si elles n’y figurent pas encore).In your project's AndroidManifest.xml file, add the following permissions inside the manifest element (if they are not already present). Cela autorise votre application à se connecter à Internet et à activer la détection Bluetooth sur votre appareil.This gives your app permission to connect to the Internet and to enable Bluetooth discovery on your device. Notez que les autorisations liées à Bluetooth ne sont nécessaires que pour utiliser la détection Bluetooth. Elles ne sont pas nécessaires pour d’autres fonctionnalités de la plateforme des appareils connectés.Note that the Bluetooth-related permissions are only necessary for using Bluetooth discovery; they are not needed for the other features in the Connected Devices Platform. De plus, ACCESS_COARSE_LOCATION n’est requis que sur les kits de développement logiciel (SDK) Android 21 et ultérieurs.Additionally, ACCESS_COARSE_LOCATION is only required on Android SDKs 21 and later. Sur les kits de développement logiciel (SDK) Android 23 et ultérieurs, vous devez également inviter l’utilisateur a accorder l’accès à l’emplacement au moment de l’exécution du runtime.On Android SDKs 23 and later, you must also prompt the user to grant location access at runtime.

<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" />

Ensuite, accédez aux classes d’activité dans lesquelles vous souhaitez que la fonctionnalité Appareils connectés soit située.Next, go to the activity classes where you would like the Connected Devices functionality to be located. Importez les espaces de noms suivants.Import the following namespaces.

import com.microsoft.connecteddevices;
import com.microsoft.connecteddevices.userdata;
import com.microsoft.connecteddevices.userdata.usernotifications;

Initialisation des plateformes d’appareils connectésInitializing the Connected Device Platforms

Le Kit de développement logiciel (SDK) côté client est construit sur une infrastructure appelée plateforme d’appareil connecté.The client-side SDK is built on top of an infrastructure called Connected Device Platform. Pour qu’une fonctionnalité soit utilisable, la plateforme doit être initialisée dans votre application.Before any feature can be used, the platform must be initialized within your app. Les étapes d’initialisation doivent avoir lieu dans votre méthode OnCreate de la classe principale, car elles sont indispensables pour l’exécution des scénarios de notification.The initialization steps should occur in your main class OnCreate method, because they are required before the notification scenarios can take place.

Vous devez construire et initialiser la plateforme en instanciant la classe ConnectedDevicesPlatform.You must construct and initialize the platform by instantiating the ConnectedDevicesPlatform class. Avant cela, veillez à raccorder les gestionnaires d’événements car, une fois la plateforme démarrée, les événements pourraient commencer à se déclencher.Before doing that, make sure to hook up event handlers, because after the platform is started, the events might begin to fire.

ConnectedDevicesPlatform platform = new ConnectedDevicesPlatform(context);

platform.getAccountManager().accessTokenRequested().subscribe((accountManager, args) -> onAccessTokenRequested(accountManager, args));
platform.getAccountManager().accessTokenInvalidated().subscribe((accountManager, args) -> onAccessTokenInvalidated(accountManager, args));
platform.getNotificationRegistrationManager().notificationRegistrationStateChanged().subscribe((notificationRegistrationManager, args) -> onNotificationRegistrationStateChanged(notificationRegistrationManager, args));

platform.start();

Gestion de jeton d’accès au compteHandling account access token

Tous les appels web effectués par le Kit de développement logiciel (SDK), par exemple, pour la récupération du contenu d’une nouvelle notification entrante ou la mise à jour d’états de notification, lisent ou écrivent des données de l’utilisateur. Ils nécessitent donc toujours un jeton d’accès valide.All the web calls the SDK makes, including retrieving the content of a new incoming notification, updating notification states, and more, are reading from or writing to the user's data, and therefore always require a valid access token. Le Kit de développement logiciel (SDK) requiert que vous gériez les événements suivants (appelés quand un jeton d’accès est demandé ou invalidé) pour vous assurer qu’une fois la plateforme initialisée, votre jeton d’accès pour l’utilisateur soit correctement géré.The SDK requires you to handle the following events - invoked when an access token is requested or invalidated - to make sure that after the platform is initialized, your access token for the user is handled correctly.

accessTokenRequestedaccessTokenRequested

Pour une implémentation complète, voir l’exemple d’application Android.For a full implementation, see the Android sample app.

private void onAccessTokenRequested(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenRequestedEventArgs args) {
    ConnectedDevicesAccessTokenRequest request = args.getRequest();
    List<String> scopes = request.getScopes();

    // We always need to complete the request, even if a matching account is not found
    if (account == null) {
        request.completeWithErrorMessage("The app could not find a matching ConnectedDevicesAccount to get a token");
        return;
    }

    // Complete the request with a token
    account.getAccessTokenAsync(scopes)
        .thenAcceptAsync((String token) -> {
            request.completeWithAccessToken(token);
        }).exceptionally(throwable -> {
            request.completeWithErrorMessage("The Account could not return a token with those scopes");
            return null;
    });
}

accessTokenInvalidatedaccessTokenInvalidated

Pour une implémentation complète, voir l’exemple d’application Android.For a full implementation, see the Android sample app.

private void onAccessTokenInvalidated(ConnectedDevicesAccountManager sender, ConnectedDevicesAccessTokenInvalidatedEventArgs args, List<Account> accounts) {
    Log.i(TAG, "Token invalidated for account: " + args.getAccount().getId());
}

Gestion de l’expiration d’inscription de notification PushHandling push registration expiration

L’API de notifications de Microsoft Graph utilise FCM, la plateforme de notifications Push native d’Android, pour signaler à l’application cliente les modifications des données des notifications à l’utilisateur.Microsoft Graph notifications uses FCM, the native push platform on Android, to signal the client application on user notifications data changes. Cela se produit quand de nouvelles notifications entrantes sont publiées à partir de votre serveur d’applications ou quand l’état d’une notification est mis à jour sur un autre appareil du même utilisateur connecté dans un contexte inter-appareils.This happens when new incoming notifications are published from your app server, or when any notification's state is updated on a different device with the same signed in user in a cross-device scenario.

Par conséquent, un jeton FCM valide permettant le passage des messages de notification de données est requis.Therefore, a valid FCM token that allows data notification messages to come through successfully is required. Le rappel d’événement suivant gère les expirations de jeton Push de Firebase Cloud Messaging (FCM).The following event callback handles FCM push token expirations.

notificationRegistrationStateChangednotificationRegistrationStateChanged

Pour une implémentation complète, voir l’exemple d’application Android.For a full implementation, see the Android sample app.

Connexion de votre utilisateurSigning in your user

Les notifications de Microsoft Graph, ainsi que celles de nombreux autres types de ressources dans Microsoft Graph, sont centralisées autour des utilisateurs.Microsoft Graph notifications, like many other resource types in Microsoft Graph, are centralized around users. Pour que votre application puisse s’abonner au notifications destinées à l’utilisateur connecté et commencer à les recevoir, vous devez commencer par obtenir un jeton OAuth valide à utiliser dans le processus d’inscription.In order for your app to subscribe to and start receiving notifications for the signed in user, you first need to obtain a valid OAuth token to be used in the registration process. Vous pouvez utiliser votre méthode préférée de génération et gestion des jetons OAuth.You can use your preferred method of generating and managing the OAuth tokens. L’exemple d’application a utilisé une bibliothèque d’authentification Active Directory (ADAL).The sample app used ADAL.

Si vous utilisez un compte Microsoft, vous devez inclure dans votre demande de connexion les autorisations suivantes : wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry et https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.If you're using a Microsoft account, you will need to include the following permissions in your sign-in request: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry, and https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp.

Si vous utilisez un compte Azure AD, vous devez demander l’audience suivante : https://cdpcs.access.microsoft.com.If you're using an Azure AD account, you'll need to request the following audience: https://cdpcs.access.microsoft.com.

Ajout du compte d’utilisateur à la plateformeAdding the user account to the platform

Vous devez inscrire le compte d’utilisateur connecté avec le Kit de développement logiciel (SDK), ce qui implique l’ajout du compte et l’inscription d’un canal de notifications Push pour recevoir les notifications Push initiales via FCM.You need to register the signed in user account with the SDK, which involves adding the account and registering a push channel in order to receive the initial push notifications through FCM.

public AsyncOperation<Boolean> prepareAccountAsync(final Context context) {
    // Accounts can be in 3 different scenarios:
    // 1: cached account in good standing (initialized in the SDK and our token cache).
    // 2: account missing from the SDK but present in our cache: Add and initialize account.
    // 3: account missing from our cache but present in the SDK. Log the account out async

    // Subcomponents (e.g. UserDataFeed) can only be initialized when an account is in both the app cache
    // and the SDK cache.
    // For scenario 1, initialize our subcomponents.
    // For scenario 2, subcomponents will be initialized after InitializeAccountAsync registers the account with the SDK.
    // For scenario 3, InitializeAccountAsync will unregister the account and subcomponents will never be initialized.
    switch (mState) {
        // Scenario 1
        case IN_APP_CACHE_AND_SDK_CACHE:
            mUserNotificationsManager = new UserNotificationsManager(context, mAccount, mPlatform);
            return registerAccountWithSdkAsync();
        // Scenario 2
        case IN_APP_CACHE_ONLY: {
            // Add the this account to the ConnectedDevicesPlatform.AccountManager
            return mPlatform.getAccountManager().addAccountAsync(mAccount).thenComposeAsync((ConnectedDevicesAddAccountResult result) -> {
                // We failed to add the account, so exit with a failure to prepare bool
                if (result.getStatus() != ConnectedDevicesAccountAddedStatus.SUCCESS) {
                    result.getStatus());
                    return AsyncOperation.completedFuture(false);
                }

                // Set the registration state of this account as in both app and sdk cache
                mState = AccountRegistrationState.IN_APP_CACHE_AND_SDK_CACHE;
                mUserNotificationsManager = new UserNotificationsManager(context, mAccount, mPlatform);
                return registerAccountWithSdkAsync();
            });
        }
        // Scenario 3
        case IN_SDK_CACHE_ONLY:
            // Remove the account from the SDK since the app has no knowledge of it
            mPlatform.getAccountManager().removeAccountAsync(mAccount);
            // This account could not be prepared
            return AsyncOperation.completedFuture(false);
        default:
            // This account could not be prepared
            Log.e(TAG, "Failed to prepare account " + mAccount.getId() + " due to unknown state!");
            return AsyncOperation.completedFuture(false);
    }
}
public AsyncOperation<Boolean> registerAccountWithSdkAsync() {
    if (mState != AccountRegistrationState.IN_APP_CACHE_AND_SDK_CACHE) {
        AsyncOperation<Boolean> toReturn = new AsyncOperation<>();
        toReturn.completeExceptionally(new IllegalStateException("Cannot register this account due to bad state: " + mAccount.getId()));
        return toReturn;
    }

    // Grab the shared GCM/FCM notification token from this app's BroadcastReceiver
    return RomeNotificationReceiver.getNotificationRegistrationAsync().thenComposeAsync((ConnectedDevicesNotificationRegistration notificationRegistration) -> {
        // Perform the registration using the NotificationRegistration
        return mPlatform.getNotificationRegistrationManager().registerAsync(mAccount, notificationRegistration)
            .thenComposeAsync((result) -> {
                if (result.getStatus() == ConnectedDevicesNotificationRegistrationStatus.SUCCESS) {
                    Log.i(TAG, "Successfully registered account " + mAccount.getId() + " for cloud notifications");
                } else {
                    // It would be a good idea for apps to take a look at the different statuses here and perhaps attempt some sort of remediation.
                    // For example, token request failed could mean that the user needs to sign in again. An app could prompt the user for this action 
                    // and retry the operation afterwards.
                    Log.e(TAG, "Failed to register account " + mAccount.getId() + " for cloud notifications!");
                    return AsyncOperation.completedFuture(false);
                }

                return mUserNotificationsManager.registerForAccountAsync();
            });
    });
}

Abonnement pour recevoir les notifications à l’utilisateurSubscribing to receive user's notifications

Vous devez instancier un objet UserDataFeed pour votre application pour cet utilisateur connecté.You need to instantiate a UserDataFeed object for your application for this logged in user. Votre application est identifiée par l’ID d’application multiplateforme que vous avez fourni durant l’intégration d’expériences inter-appareils.Your application is identified by the cross-platform app ID you provided during the Cross-Device Experiences onboarding.

public UserNotificationsManager(@NonNull Context context, @NonNull ConnectedDevicesAccount account, @NonNull ConnectedDevicesPlatform platform)
{
    Context context = new Context;
    UserDataFeed feed = UserDataFeed.getForAccount(account, platform, Secrets.APP_HOST_NAME);
    UserNotificationChannel channel = new UserNotificationChannel(feed);
    UserNotificationReader reader = channel.createReader();
    reader.dataChanged().subscribe((reader, aVoid) -> readFromCache(reader));
    }
}

Réception et gestion de notifications à l’utilisateurReceiving and managing user notifications

Le diagramme de flux présenté plus haut dans cette rubrique montre que les modèles de programmation pour gérer une nouvelle notification entrante provenant d’un serveur d’applications ou une mise à jour ou suppression de notification lancée par une autre instance du client de l’application sont similaires.The flow diagram earlier in this topic shows that the programming patterns to handle a new incoming notifications from an app server and a notification update or deletion initiated from another app client instance are similar. Les étapes ci-après ont trait à la gestion de ces modifications des données.The following are the steps for handling these data changes.

Traitement du signal de notification Push entranteHandling incoming push notification signal

Tous les types de modifications des données de notification à l’utilisateur génèrent un signal qui est transmis aux clients de l’application sous forme de notification Push.All types of user notification data changes generate a signal that gets delivered to the app clients as a push notification. Pour les applications Android, le signal est délivré en temps que message de données de notification Push FCM.For Android apps, the signal is delivered as a FCM push data message. Lors de la réception du signal de message de données, l’application doit appeler la méthode TryParse pour déclencher l’extraction par le Kit de développement logiciel (SDK) des modifications des données à partir du service de notifications de Microsoft Graph.On receiving the data message signal, the app should call TryParse to trigger the SDK to fetch from the Microsoft Graph notifications service for the actual data changes.

public void onMessageReceived(RemoteMessage message) {
    Map data = message.getData();
    ConnectedDevicesNotification notification = ConnectedDevicesNotification.tryParse(data);

    if (notification != null) {
        try {
            ConnectedDevicesPlatform platform = ConnectedDevicesManager.getConnectedDevicesManager(getApplicationContext()).getPlatform();

            // 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.
            platform.processNotificationAsync(notification);
        } catch (Exception e) {
            Log.e(TAG, "Failed to process FCM notification" + e.getMessage());
        }
    }
}

Gestion des modifications des données de notification à l’utilisateurHandling user notification data changes

Après que le Kit de développement logiciel (SDK) a extrait les modifications des données, un rappel d’événement est lancé, et le client de l’application doit gérer la création, la mise à jour ou la suppression de la notification.After the SDK successfully completes fetching the data changes, an event callback is invoked and the app client is expected to handle notification creation, update, or deletion.

private void readFromCache(final UserNotificationReader reader)
{
    reader.readBatchAsync(Long.MAX_VALUE).thenAccept(notifications -> {
        synchronized (this) {
            for (final UserNotification notification : notifications) {
                if (notification.getStatus() == UserNotificationStatus.ACTIVE) {
                    removeIf(mNewNotifications, item -> notification.getId().equals(item.getId()));

                    if (notification.getUserActionState() == UserNotificationUserActionState.NO_INTERACTION) {
                        mNewNotifications.add(notification);
                        if (notification.getReadState() != UserNotificationReadState.READ) {
                            clearNotification(mContext.getApplicationContext(), notification.getId());
                            addNotification(mContext.getApplicationContext(), notification.getContent(), notification.getId());
                        }
                    } else {
                        clearNotification(mContext.getApplicationContext(), notification.getId());
                    }

                    removeIf(mHistoricalNotifications, item -> notification.getId().equals(item.getId()));
                    mHistoricalNotifications.add(0, notification);
                } else {
                    removeIf(mNewNotifications, item -> notification.getId().equals(item.getId()));
                    removeIf(mHistoricalNotifications, item -> notification.getId().equals(item.getId()));
                    clearNotification(mContext.getApplicationContext(), notification.getId());
                }
            }
        }

    });
}

Mettre à jour l’état d’une notificationUpdate state of a notification

Si un changement d’état d’une notification est déclenché par cette instance du client de l’application (par exemple, si la fenêtre contextuelle de notification toast sur cet appareil est activée par l’utilisateur), l’application doit appeler le Kit de développement logiciel (SDK) pour mettre à jour l’état de la notification afin que ce changement d’état soit synchronisé sur tous les appareils utilisés par le même utilisateur.If a notification state change is initiated from this app client instance (for example, if the toast notification popup on this device is activated by the user), the app needs to call the SDK to update the notification's state in order to have this state change synced across all devices used by the same user.

notification.setUserActionState(UserNotificationUserActionState.ACTIVATED);
notification.saveAsync().whenCompleteAsync((userNotificationUpdateResult, throwable) -> {
    if (throwable == null && userNotificationUpdateResult != null && userNotificationUpdateResult.getSucceeded()) {
        Log.d(TAG, "Successfully activated the notification");
    }
});

Supprimer une notificationDelete a notification

Si une suppression de notification est déclenchée par cette instance de client de l’application (par exemple, si la tâche correspondant à cette notification est marquée comme terminée et supprimée de la base de données de votre application), l’application doit appeler le Kit de développement logiciel (SDK) pour supprimer la notification afin que cette opération de suppression soit synchronisée sur tous les appareils utilisés par le même utilisateur.If a notification deletion is initiated from this app client instance (for example, if the task corresponding to this notification is marked as complete and is removed from your app's database), the app needs to call the SDK to delete the notification in order to have this delete operation synced across all devices used by the same user.

Une notification n’est supprimée du magasin de notifications à l’utilisateur que si elle a expiré ou été explicitement supprimée.A notification is removed from the user notification store only if it is expired or explicitly deleted. Une notification à l’utilisateur n’est pas supprimée quand vous mettez à jour l’état UserActionState sur Masqué, car la définition sémantique de celui-ci est définie par l’application elle-même.A user notification is not deleted when you update the UserActionState to be Dismissed, because the semantic definition of UserActionState is defined by the application itself.

channel.deleteUserNotificationAsync(notification.getId()).whenCompleteAsync((userNotificationUpdateResult, throwable) -> {
    if (throwable == null && userNotificationUpdateResult != null && userNotificationUpdateResult.getSucceeded()) {
        Log.d(TAG, "Successfully deleted the notification");
    }
});

Voir aussiSee also