Integração do aplicativo Android no SDK do lado do cliente para notificações ao usuárioIntegrate your Android app with the client-side SDK for user notifications

Após registrar seu aplicativo no Portal do Azure e integrar suas experiências entre dispositivos no Partner Center de desenvolvimento, a próxima etapa é integrar seu aplicativo de cliente com o SDK do lado do cliente para aplicativos 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.

Com o SDK do cliente, o aplicativo pode executar as etapas necessárias de registro para receber notificações publicadas do servidor do aplicativo direcionadas ao usuário conectado atualmente.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. O SDK então gerencia as notificações no lado do cliente, incluindo receber novas notificações, gerenciar o estado de notificações para alcançar cenários como descartar de forma universal e recuperar o histórico completo de notificações.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.

Fluxo de notificação de entradaNew incoming notification flow

Para receber novas notificações, o fluxo de dados é mostrado no diagrama a seguir.For receiving new incoming notifications, the data flow is shown in the following diagram.

Fluxo de nova notificação para aplicativo Android

O processo envolve alguns componentes:he process involves a few components:

  • Servidor de aplicativo – back-end do aplicativoApp server - The back end of your application
  • Cliente do aplicativo – front-end do aplicativo (um aplicativo UWP, Android ou iOS)App client - The front end of your application (a UWP app, an Android app, or an iOS app)
  • Notificações do Microsoft Graph – o componente do serviço que permite que notificações ao usuário sejam publicadas, armazenadas e sincronizadas em instâncias diferentes dos clientes do aplicativo em vários dispositivos e plataformasMicrosoft 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, o serviço de notificações por push fornecido pelo Android como parte do Google Play Services.FCM - Firebase Cloud Messaging, the push notification service provided by Android as a part of Google Play Services. As notificações do Microsoft Graph usam esse serviço para sinalizar clientes do aplicativo do Android sobre as alterações de dados de notificação do usuário.Microsoft Graph notifications use this service to signal the Android app clients about user notification data changes.

O diagrama mostra as próximas etapas:The diagram shows the following steps:

  1. Lógica do aplicativo.Application logic. Essa etapa captura o que aciona a notificação para ser publicada para o usuário.This step captures what triggers the notification to be published to the user. Isso é lógica específica do aplicativo e pode ser uma atualização de dados ou evento sobre algo diferente do Microsoft Graph, como um novo evento do calendário ou atribuição de tarefas, ou o que o serviço de aplicativo quer notificar o usuário.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. O servidor do aplicativo publica uma notificação para o usuário alvo pela API de notificações do Microsoft Graph.The app server publishes a notification to the targeted user via the Microsoft Graph notifications API. Para saber mais, consulte integração com o lado do servidor.For more details, see server side integration.
  3. Ao receber a solicitação Web com nova notificação, as notificações do Microsoft Graph mantêm o conteúdo da notificação em segurança na nuvem para esse aplicativo e esse usuário.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. Para cada instância do cliente do aplicativo inscrita para receber notificações para esse usuário, as notificações do Microsoft Graph envia um sinal para notificar cliente do aplicativo, por meio do serviço de envio por push nativo fornecido pelo sistema operacional.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. Nesse caso, o aplicativo é um aplicativo Android, e ele usa mensagens de dados FCM para enviar o sinal.In this case, the application is an Android app, and it uses FCM data message to send the signal.
  5. Depois que o aplicativo for sinalizado pelas notificações por push de entrada, ele pede ao SDK para buscar as alterações no repositório de notificações do usuário.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. O SDK estabelece uma conexão segura e compatível com o repositório de notificações do usuário no Microsoft Graph.The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  7. O SDK recebe as alterações de dados – nesse caso, o novo conteúdo de notificação.The SDK gets the data changes - in this case, the new notification contents.
  8. O SDK dispara retornos de evento para notificá-o aplicativo após as alterações são recuperadas com êxito.The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  9. Lógica do aplicativo.Application logic. Essa etapa captura o que o aplicativo escolhe fazer dentro retorno de chamada do evento.This step captures what your app chooses to do inside the event callback. Normalmente, isso resulta em alterações locais de dados do aplicativo e atualizações de interface do usuário locais.Usually, this results in local app data changes and local UI updates. Nesse caso, o aplicativo geralmente cria uma pop-up de notificação do sistema para notificar o usuário sobre o conteúdo de notificação.In this case, the app usually constructs a toast notification popup to notify the user about the notification contents.

Fluxo de atualização de notificaçãoNotification update flow

Uma das principais vantagens de usar as notificações do Microsoft Graph é que ele mantêm as notificações na nuvem com segurança e as transforma em um tipo de recurso com estado.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. Portanto, ele pode ajudar o aplicativo a gerenciar e a sincronizar o estado correto das notificações em diferentes dispositivos para o usuário conectado em um cenário entre dispositivos.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. Quando uma notificação estiver marcada como descartada ou como lida em um dispositivo, os outros dispositivos podem ser notificados em tempo real.When a notification is marked as dismissed, or marked as read on one device, the other devices can be notified in real-time. "Manipulada uma vez, descartada em qualquer lugar" pode se tornar a promessa real como parte da experiência de notificação para seus usuários."Handled once, dismissed everywhere" can become a true promise as part of the notification experience for your users.

O diagrama a seguir mostra o fluxo de dados para alterar o estado de uma notificação ou excluir a notificação em um dispositivo e receber/manipular a alteração de estado ou a exclusão em outro dispositivo.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.

Atualização de fluxo de notificação para aplicativo Android

Observe que a segunda parte do fluxo é semelhante ao fluxo de tratamento de novas notificações de entrada.Notice that the second part of the flow is similar to the flow for handling new incoming notifications. Isso é esperado – o padrão de programação no SDK foi projetado para que o cliente do aplicativo possa lidar com todos os tipos de alterações de dados de notificações do usuário (novas notificações de entrada, alterações de estado de notificação, notificação excluída) de maneira semelhante.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.

O diagrama mostra as próximas etapas:The diagram shows the following steps:

  1. Lógica do aplicativo.Application logic. Algo aciona a notificação para ser alterada ou excluída.Something triggers the notification to be changed or deleted. Em geral, qualquer evento possível pode acionar a alteração de uma notificação.In general, any event can trigger a notification to change.
  2. Chamada do aplicativo para o SDK do cliente para atualizar ou excluir uma notificação.App calling into the client SDK to update or delete a notification. Atualmente, expomos duas propriedades sobre alterações de estado – userActionState e readState – mas o aplicativo pode definir esses estados e quando eles precisam ser atualizados.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. Por exemplo, quando um usuário descartar a notificação pop-up, você pode atualizar o userActionState para Descartado.For example, when a user dismisses the notification popup, you can update the userActionState to be Dismissed. Quando um usuário clica na notificação pop-up e inicia o aplicativo para consumir o conteúdo correspondente do aplicativo, você pode atualizar o userActionState para ativado e atualizar o readState para Lido.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. Depois que a API correspondente é chamada para atualizar ou excluir uma notificação, o SDK irá chamar o repositório na nuvem de notificação de usuário para dispersar essa alteração para as outras instâncias de cliente do aplicativo com o mesmo usuário conectado.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. Ao receber a solicitação de atualização/exclusão de um cliente, as notificações do Microsoft Graph irão atualizar o repositório de notificação e identificar as outras instâncias de cliente do aplicativo inscritas para essa alteração.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. Para cada inscrição do cliente do aplicativo, as notificações do Microsoft Graph envia um sinal para notificar o cliente do aplicativo, por meio do serviço de envio por push nativo fornecido pelo sistema operacional.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. Nesse caso, esse é um aplicativo Android, e ele usa mensagens de dados FCM para enviar o sinal.In this case, this is an Android app, and it uses FCM data message to send the signal.
  6. Depois que o aplicativo for sinalizado pelas notificações por push de entrada, ele pede ao SDK para buscar as alterações no repositório de notificações do usuário.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. O SDK estabelece uma conexão segura e compatível com o repositório de notificações do usuário no Microsoft Graph.The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  8. O SDK recebe as alterações de dados – nesse caso, as alterações são atualizações de notificação de estado ou exclusões de notificação.The SDK gets the data changes - in this case, the changes are notification state updates or notification deletions.
  9. O SDK dispara retornos de evento para notificá-o aplicativo após as alterações são recuperadas com êxito.The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  10. Lógica do aplicativo.Application logic. Essa etapa captura o que o aplicativo escolhe fazer dentro retorno de chamada do evento.This step captures what your app chooses to do inside the event callback. Normalmente, isso resulta em alterações locais de dados do aplicativo e atualizações de interface do usuário locais.Usually, this results in local app data changes and local UI updates. Nesse caso, como há atualizações de notificação, o aplicativo deve atualizar a interface do usuário no local para refletir a alteração de estado.In this case, because there are notification updates, the app should update the UI locally to reflect the state change. Por exemplo, se uma notificação estiver marcada como ativada, você pode remover a mensagem de notificação correspondente dentro da bandeja de notificação do Android para obter "manipulada uma vez, descartada em todo lugar".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".

Para obter mais informações sobre as notificações do Microsoft Graph, consulte a visão geral das notificações do Microsoft Graph.For more information about Microsoft Graph notifications, see Microsoft Graph Notifications overview. Para saber mais sobre as etapas necessárias para integrar com as notificações do Microsoft Graph de ponta a ponta, confira a visão geral de integração das notificações do 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.

Ambiente e os requisitos de desenvolvimentoDevelopment environment and requirements

Para usar as notificações do Microsoft Graph, será necessário um IDE de desenvolvimento de aplicativos Android e um dispositivo Android com uma das arquiteturas suportadas (armeabi-v7a, arm64-v8a, x86, ou x86_64) ou um emulador.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. O sistema deve ser o Android 4.4.2 ou posterior.The system must be running Android 4.4.2 or later.

Adicionar o SDK ao seu projetoAdding the SDK to your project

Insira as seguintes referências do repositório para o arquivo build.gradle na raiz do seu projeto.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/' }
    }
}

Depois insira a dependência a seguir para o arquivo build.gradle que está na pasta do projeto.Then, insert the following dependency into the build.gradle file that is in your project folder.

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

Se você quiser usar ProGuard em seu aplicativo, adicione as regras ProGuard dessas novas APIs.If you want to use ProGuard in your app, add the ProGuard Rules for these new APIs. Crie um arquivo chamado proguard-rules.txt na pasta Aplicativo do seu projeto e cole nos conteúdos de 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. No arquivo do projeto AndroidManifest.xml, adicione as seguintes permissões dentro do elemento manifest (se já não estiverem presentes).In your project's AndroidManifest.xml file, add the following permissions inside the manifest element (if they are not already present). Isso dá permissão ao aplicativo para se conectar à Internet e permitem a descoberta Bluetooth em seu dispositivo.This gives your app permission to connect to the Internet and to enable Bluetooth discovery on your device. Observe que as permissões relacionadas ao Bluetooth só são necessárias para usar a descoberta Bluetooth; elas não são necessárias para os recursos da plataformas de dispositivos conectados.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. Além disso, ACCESS_COARSE_LOCATION só é necessário em SDKs 21 do Android e versões posteriores.Additionally, ACCESS_COARSE_LOCATION is only required on Android SDKs 21 and later. Em SDKs 23 do Android e versões posteriores, você também deve solicitar ao usuário para conceder acesso à localização no tempo de execução.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" />

Em seguida, acesse as classes de atividade onde desejar que a funcionalidade dos Dispositivos Conectados seja localizada.Next, go to the activity classes where you would like the Connected Devices functionality to be located. Importar os namespaces a seguir.Import the following namespaces.

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

Inicializar as Plataformas do Dispositivo ConectadoInitializing the Connected Device Platforms

No SDK do lado do cliente é desenvolvido com base em uma infraestrutura chamada Plataforma de Dispositivo Conectado.The client-side SDK is built on top of an infrastructure called Connected Device Platform. Antes de poder usar qualquer recurso, a plataforma deve ser inicializada em seu aplicativo.Before any feature can be used, the platform must be initialized within your app. As etapas de inicialização que devem ocorrer em sua classe principal no método OnCreate, porque eles são necessários para ocorrer os cenários de notificação.The initialization steps should occur in your main class OnCreate method, because they are required before the notification scenarios can take place.

Você deve criar e inicializar a plataforma ao instanciar a classe ConnectedDevicesPlatform.You must construct and initialize the platform by instantiating the ConnectedDevicesPlatform class. Antes de fazer isso, certifique-se de conectar manipuladores de eventos, pois depois que a plataforma é iniciada, os eventos podem começar a acionar.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();

Gerenciar tokens de acesso à contaHandling account access token

Todas as chamadas de Web que o SDK realiza, incluindo a recuperação do conteúdo de uma nova notificação de entrada, atualização de notificação de estado e muito mais, são leituras de ou escrevendo para os dados do usuário e, portanto, sempre exigem um token de acesso válido.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. O SDK requer que você trate os seguintes eventos – chamados quando um token de acesso for solicitado ou invalidado – para garantir que, depois da plataforma inicializar, o token de acesso do usuário seja tratado corretamente.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

Para uma implementação completa, confira o exemplo de aplicativo 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

Para uma implementação completa, confira o exemplo de aplicativo 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());
}

Gerenciar validade de registro de pushHandling push registration expiration

As notificações do Microsoft Graph usa o WNS, a plataforma de push nativa no Android, para sinalizar o aplicativo de cliente sobre alterações de dados de notificações do usuário.Microsoft Graph notifications uses FCM, the native push platform on Android, to signal the client application on user notifications data changes. Isso acontece quando novas notificações recebidas forem publicadas do servidor de aplicativos, ou quando o estado de qualquer notificação é atualizado em outro dispositivo com o mesmo usuário conectado em um cenário entre dispositivos.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.

Portanto, é necessário um token FCM válido que permite mensagens de notificação de dados para ter êxito.Therefore, a valid FCM token that allows data notification messages to come through successfully is required. O seguinte retorno de chamada de evento trata da validade de tokens FCM por push.The following event callback handles FCM push token expirations.

notificationRegistrationStateChangednotificationRegistrationStateChanged

Para uma implementação completa, confira o exemplo de aplicativo Android.For a full implementation, see the Android sample app.

Entrar com seu usuárioSigning in your user

As notificações do Microsoft Graph, como vários outros tipos de recursos no Microsoft Graph, são centralizadas em torno dos usuários.Microsoft Graph notifications, like many other resource types in Microsoft Graph, are centralized around users. Para que o aplicativo assine e comece a receber notificações para o usuário conectado, primeiro é necessário obter um token OAuth válido a ser usado no processo de registro.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. Você pode usar o método que preferir para gerar e gerenciamento os tokens OAuth.You can use your preferred method of generating and managing the OAuth tokens. Exemplo de aplicativo que usa ADAL.The sample app used ADAL.

Se você estiver usando uma conta da Microsoft, será necessário incluir as seguintes permissões em uma solicitação de entrada: wl.offline_access", ccs.ReadWrite, wns.connect, asimovrome.telemetry, e 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.

Se você estiver usando uma conta do Azure AD, você precisará solicitar o seguinte público: 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.

Adicionar a conta de usuário à plataformaAdding the user account to the platform

Será preciso registrar a conta do usuário conectado com um SDK, o que envolve a adição de contas e o registro de um canal push para receber as notificações por push iniciais através de 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();
            });
    });
}

Inscrever-se para receber notificações do usuárioSubscribing to receive user's notifications

Você precisa instanciar um objeto UserDataFeed para o aplicativo para este usuário conectado.You need to instantiate a UserDataFeed object for your application for this logged in user. O aplicativo é identificado pela ID de aplicativo multiplataforma fornecidas durante a integração de experiências entre dispositivos.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));
    }
}

Receber e gerenciar as notificações do usuárioReceiving and managing user notifications

O diagrama de fluxo já apresentado nesse tópico mostra que os padrões de programação para lidar com novas notificações de entrada de um servidor do aplicativo e uma atualização de notificação ou exclusão iniciado de outra instância do aplicativo do cliente são semelhantes.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. A seguir estão as etapas para lidar com essas alterações de dados.The following are the steps for handling these data changes.

Gerenciar sinal de notificações por push de entradaHandling incoming push notification signal

Todos os tipos de alterações de dados de notificações do usuário geram um sinal que é entregue para os clientes do aplicativo como uma notificação por push.All types of user notification data changes generate a signal that gets delivered to the app clients as a push notification. Para aplicativos Android, o sinal será enviado como uma mensagem de dados FCM por push.For Android apps, the signal is delivered as a FCM push data message. Ao receber sinal de mensagem de dados, o aplicativo deve chamar TryParse para acionar o SDK para buscar no serviço de notificações do Microsoft Graph para as alterações de dados reais.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());
        }
    }
}

Gerenciar alterações de dados de notificação do usuárioHandling user notification data changes

Após o SDK buscar com êxito as alterações de dados, um retorno de chamada do evento é invocado e o cliente de aplicativo deve lidar com a criação, atualização ou exclusão da notificação.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());
                }
            }
        }

    });
}

Atualização do estado de uma notificaçãoUpdate state of a notification

Se a alteração do estado de notificação é iniciada da instância do cliente do aplicativo (por exemplo, se a notificação pop-up do sistema nesse dispositivo é ativada pelo usuário), o aplicativo deve chamar o SDK para atualizar o estado de notificação para que essa alteração de estado seja sincronizada em todos os dispositivos usados pelo mesmo usuário.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");
    }
});

Excluir uma notificaçãoDelete a notification

Se a exclusão de uma notificação é iniciada da instância do cliente de aplicativo (por exemplo, se a tarefa correspondente a essa notificação for marcada como concluída e removida do banco de dados do aplicativo), o aplicativo deve chamar o SDK para excluir a notificação para que essa operação de exclusão seja sincronizada em todos os dispositivos usados pelo mesmo usuário.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.

Uma notificação é removida do repositório de notificação do usuário apenas se expirada ou explicitamente excluída.A notification is removed from the user notification store only if it is expired or explicitly deleted. Uma notificação do usuário não é excluída quando você atualiza o UserActionState para Descartado, porque a definição semântica do UserActionState é definida pelo próprio aplicativo.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");
    }
});

Confira tambémSee also