How-To Руководство: Интеграция с уведомлениями Graph (Android)

Уведомления Graph позволяют приложению отправлять уведомления, предназначенные для пользователей, и управлять ими на нескольких устройствах.

С помощью клиентского пакета SDK Project Rome на Android приложение Android может зарегистрировать уведомления, опубликованные с сервера приложений, предназначенные для пользователя, вошедшего в систему. Пакет SDK позволяет клиенту приложения получать новые данные входящих уведомлений, управлять состоянием существующих уведомлений и получать историю уведомлений. Дополнительные сведения о уведомлениях и о том, как она обеспечивает доставку уведомлений, ориентированных на человека, см. в обзоре уведомлений Microsoft Graph.

Все функции пакета SDK Project Rome, включаемые уведомления Graph и многое другое, основаны на базовой платформе, называемой платформой подключенных устройств. Это руководство поможет вам выполнить необходимые действия, чтобы приступить к работе с платформой подключенных устройств и объяснить, как использовать API в пакете SDK для реализации функций уведомлений Graph -specific.

См. справочную страницу API для ссылок на справочные документы, относящиеся к сценариям уведомлений.

На следующих шагах будут ссылаться на код из примера приложения Project Rome Android.

Для всех функций подключенных устройств вам потребуется интегрированная среда разработки приложений Android и устройство Android с одной из поддерживаемых архитектур (armeabi-v7a, arm64-v8a, x86 или x86_64) или эмулятор. Система должна работать под управлением Android 4.4.2 или более поздней версии.

Предварительная настройка платформы подключенных устройств и уведомлений

Перед реализацией удаленного подключения необходимо выполнить несколько шагов, чтобы предоставить приложению Android возможность подключения к удаленным устройствам, а также отправлять и получать уведомления.

Регистрация приложения

Проверка подлинности учетной записи Майкрософт (MSA) или Azure Active Directory (AAD) требуется почти для всех функций SDK Project Rome (исключение составляют интерфейсы программирования приложений (API) для передачи в ближнем доступе). Если у вас еще нет MSA и вы хотите использовать его, зарегистрируйтесь в account.microsoft.com.

Используя выбранный метод проверки подлинности, необходимо зарегистрировать приложение в Корпорации Майкрософт, следуя инструкциям на портале регистрации приложений. Если у вас нет учетной записи разработчика Майкрософт, необходимо создать ее.

При регистрации приложения с помощью MSA необходимо получить строку идентификатора клиента. Сохраните это для дальнейшего использования. Это позволит приложению получить доступ к ресурсам платформы подключенных устройств Майкрософт. Если вы используете AAD, ознакомьтесь с библиотеками проверки подлинности Azure Active Directory , чтобы получить строку идентификатора клиента.

Добавление пакета SDK

Вставьте следующие ссылки на репозиторий в файл build.gradle в корне проекта.

allprojects {
    repositories {
        jcenter()
    }
}

Затем вставьте следующую зависимость в файл build.gradle , который находится в папке проекта.

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

В файле AndroidManifest.xml вашего проекта добавьте следующие разрешения внутрь элемента <manifest> (если они еще не присутствуют). Это дает приложению разрешение на подключение к Интернету и включение обнаружения Bluetooth на устройстве.

Обратите внимание, что разрешения, связанные с Bluetooth, необходимы только для использования обнаружения Bluetooth; Они не требуются для других функций платформы подключенных устройств. Кроме того, ACCESS_COARSE_LOCATION требуется только в пакетах SDK для Android 21 и более поздних версий. В Android SDK 23 и более поздних версиях разработчик также должен предложить пользователю разрешить доступ к местоположению во время выполнения.

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

Затем перейдите к классу(ам) активностей, где вы хотите, чтобы функции подключенных устройств находились. Импортируйте следующие пакеты.

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

Настройка проверки подлинности и управления учетными записями

Платформа подключенных устройств требует, чтобы действительный маркер OAuth использовался в процессе регистрации. Вы можете использовать предпочитаемый метод создания маркеров OAuth и управления ими. Однако, чтобы помочь разработчикам начать использовать платформу, мы включили провайдера аутентификации в виде части примера приложения Android, который создает токены обновления и управляет ими для вашего удобства.

Если вы хотите реализовать интерфейс ConnectedDevicesAccountManager самостоятельно, обратите внимание на следующие сведения:

Если вы используете MSA, вам потребуется включить в запрос входа следующие области: "wl.offline_access", "ccs.ReadWrite", "dds.read", "dds.register", "wns.connect", "asimovrome.telemetry" и "https://activity.windows.com/UserActivity.ReadWrite.CreatedByApp".

Если вы используете учетную запись AAD, вам потребуется запросить следующие аудитории: "https://cdpcs.access.microsoft.com", "https://cs.dds.microsoft.com", "https://wns.windows.com/", и "https://activity.microsoft.com".

Независимо от того, используете ли вы предоставленную реализацию ConnectedDevicesAccountManager или нет, если вы используете AAD, вам потребуется указать следующие разрешения для регистрации приложения на портале Azure (portal.azure.com > Azure Active Directory > регистрации приложений):

• Служба ленты активности Microsoft
  • Доставка и изменение уведомлений пользователей для этого приложения
  • Чтение и запись действий приложений в вашем веб-канале активности
• Служба уведомлений Windows
  • Подключение устройства к службе уведомлений Windows
• Служба каталогов устройств Майкрософт
  • Просмотр списка устройств
  • Добавление в список устройств и приложений
• Служба команд Майкрософт
  • Обмен данными с устройствами пользователей
  • Считывание списка устройств пользователя

Регистрация приложения для работы с push-уведомлениями

Зарегистрируйте приложение в службе поддержки Google для Firebase Cloud Messaging . Обязательно запишите полученный идентификатор отправителя и ключ сервера; Вам потребуется их позже.

После регистрации необходимо связать функции push-уведомлений с платформой подключенных устройств в приложении.

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

Регистрация приложения в Центре разработки Microsoft Windows для взаимодействия с несколькими устройствами

Перейдите на панель мониторинга Центра разработки, перейдите к интерфейсам между устройствами из области навигации слева и выберите новое приложение для нескольких устройств, как показано ниже.

Для процесса подключения центра разработки требуются следующие действия.

• Выберите поддерживаемые платформы— выберите платформы, на которых ваше приложение будет иметь присутствие и включено для взаимодействия с несколькими устройствами. В случае интеграции с уведомлениями Graph можно выбрать из Windows, Android и (или) iOS.

• Укажите идентификаторы приложений— предоставьте идентификаторы приложений для каждой платформы, в которой ваше приложение имеет присутствие. Для приложений Android это имя пакета, назначенное приложению при создании проекта. Имя пакета можно найти в консоли Firebase в разделе "Общие сведения> о проекте". Вы можете добавить разные идентификаторы (до десяти) на платформу— это в случае, если у вас есть несколько версий одного приложения или даже разных приложений, которые хотят иметь возможность получать те же уведомления, отправленные сервером приложений, предназначенным для одного пользователя.

• Укажите или выберите идентификаторы приложений из регистрации приложений MSA и/или AAD. Идентификаторы клиентов, соответствующие регистрации приложений MSA или AAD, были получены на предыдущих шагах описанной выше регистрации приложений MSA/AAD.

• Уведомления Graph и другие возможности платформы подключенных устройств используют каждую из собственных платформ уведомлений на основных платформах для отправки уведомлений в конечные точки клиента приложения, а именно WNS (для Windows UWP), FCM (для Android) и APNS (для iOS). Предоставьте учетные данные для этих платформ уведомлений, чтобы уведомления Graph Notifications могли доставлять уведомления на сервер вашего приложения при публикации уведомлений, нацеленных на пользователя. Для Android включение службы Cloud Messaging является обязательным условием для использования уведомлений Microsoft Graph. Кроме того, обратите внимание, что обязательный идентификатор отправителя соответствует идентификатору отправителя Cloud Messaging Firebase, а ключ API соответствует ключу устаревшего сервера. Оба элемента можно найти в консоли Firebase —> Проект —> Параметры на вкладке Cloud Messaging, как показано на снимке экрана.

• Последний шаг — проверить домен приложения между устройствами, который служит процессом проверки, чтобы доказать, что у вашего приложения есть владение этим доменом, который действует как удостоверение приложения между устройствами для зарегистрированного приложения.

Инициализация канала уведомлений Graph

Пакет SDK Project Rome позволяет приложению подписываться на различные каналы, чтобы получать и управлять различными типами пользовательских данных, включая уведомления Graph, действия пользователей и многое другое. Они хранятся и синхронизируются в UserDataFeed. UserNotification — это класс и тип данных, соответствующий пользовательскому уведомлению, отправленном с помощью уведомлений Graph. Чтобы интегрироваться с уведомлениями Graph Notification и начать получать уведомления пользователя, опубликованные сервером приложений, сначала необходимо инициализировать канал уведомлений пользователя, создав UserNotificationChannel. Это следует рассматривать как шаг инициализации платформы выше: он должен быть проверен и, возможно, переопределен всякий раз, когда приложение приходит на передний план (но не до инициализации платформы).

Следующие методы инициализируют 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;
}

На этом этапе у вас должна быть ссылка UserNotificationChannel в mNotificationChannel.

Создайте UserNotificationReader для получения входящих UserNotifications и доступа к истории UserNotification

Как было показано ранее, начальное уведомление Google Cloud Messaging, поступающее на клиент приложения, содержит только касание плеча, и вам нужно передать полезные данные касания плеча на платформу подключенных устройств, чтобы активировать пакет SDK для выполнения полной синхронизации с подключенным сервером устройств, который содержит все пользовательские данные, опубликованные сервером приложений. Это приведет к загрузке полной полезной нагрузки уведомлений, опубликованных сервером вашего приложения, соответствующей этому касанию плеча (и в случае, если предыдущие уведомления были опубликованы, но не получены на этом клиенте приложения из-за проблем с подключением устройства или других проблем, они также будут загружены). С помощью этих синхронизаций в режиме реального времени, постоянно выполняемых пакетом SDK, клиент приложения может иметь доступ к локальному кэшу этого веб-канала данных userNotification пользователя, вошедшего в систему. UserNotificationReader в этом случае предоставляет клиенту приложения доступ к этому источнику данных - возможность получать информацию уведомления через прослушиватель событий или доступ к полной коллекции UserNotification, которая может использоваться как модель для просмотра истории уведомлений пользователя.

Получение уведомлений пользователя

Сначала необходимо создать экземпляр UserNotificationReader и получить все существующие уведомления пользователя в средстве чтения, если вы хотите использовать эти сведения для функциональности, которую вы пытаетесь включить. Можно смело предположить, что сервер приложений уже опубликовал уведомления для данного пользователя, который авторизован в системе, учитывая, что эта конкретная точка доступа может не быть единственной или первой точкой доступа, куда пользователь установил ваше приложение.

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

Теперь добавьте прослушиватель событий, который активируется, когда платформа подключенных устройств завершает синхронизацию и имеет новые изменения, чтобы уведомить вас об этом. В случае уведомлений Graph новые изменения могут быть новыми входящими UserNotifications, опубликованными сервером приложений, или обновлениями, удалениями и истечением срока действия UserNotifications, которые произошли на сервере или на других зарегистрированных конечных точках, где тот же пользователь вошел в систему.

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

Обновите состояние существующих уведомлений пользователя.

В предыдущем разделе мы упоминали, что иногда изменение уведомления пользователя, полученное через чтение, может быть обновлением состояния существующего уведомления пользователя — независимо от того, помечено ли оно как отклонённое или прочитанное. В этом случае клиент приложения может выбрать, что делать, например включить универсальное закрытие, удалив соответствующее визуальное уведомление на этом конкретном устройстве. Если посмотреть на ситуацию в целом, клиент приложения часто инициирует это изменение UserNotification, сделанное с другого устройства. Вы можете выбрать время обновления состояния ваших UserNotifications, но обычно они обновляются, когда соответствующее визуальное уведомление обрабатывается пользователем на этом устройстве, или уведомление дополнительно обрабатывается пользователем в некоторых внутренних приложениях, которые вы включаете. Ниже приведен пример того, как будет выглядеть поток: сервер приложений публикует уведомление, предназначенное для пользователя A. Пользователь А получает это уведомление как на своем компьютере, так и на своем телефоне, где установлены клиенты приложений. Пользователь нажимает на уведомление на компьютере и переходит в приложение, чтобы выполнить соответствующую задачу. Затем клиент приложения на этом компьютере вызовет SDK для Платформы подключенных устройств, чтобы обновить состояние соответствующего уведомления пользователя, что позволит синхронизировать это обновление на всех устройствах данного пользователя. Другие клиенты приложений, получая это обновление состояния в режиме реального времени, будут удалять соответствующее визуальное оповещение, сообщение или всплывающее уведомление из центра уведомлений устройства, области уведомлений или панели действий. Это способ, как уведомления отклоняются на всех устройствах пользователя.

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