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

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

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

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

Шаги ниже будут ссылаться на код из iOS-приложения Project Rome, доступного на GitHub.

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

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

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

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

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

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

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

Самый простой способ добавить платформу подключенных устройств в приложение iOS — использовать диспетчер зависимостей CocoaPods . Перейдите в podfile проекта iOS и вставьте следующую запись:

platform :ios, "10.0"
workspace 'iOSSample'

target 'iOSSample' do
  # Uncomment the next line if you're using Swift or would like to use dynamic frameworks
  # use_frameworks!

	pod 'ProjectRomeSdk'

  # Pods for iOSSample

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

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

Если вы не используете предоставленный код, вам потребуется реализовать интерфейс MCDConnectedDevicesAccountManager самостоятельно.

Если вы используете 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".

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

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

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

Зарегистрируйте приложение в Apple для поддержки Apple Push Notification. Обязательно запишите идентификатор отправителя и ключ сервера, которые вы получаете, как вам потребуется позже.

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

self.notificationRegistration = [[MCDConnectedDevicesNotificationRegistration alloc] init];
    if ([[UIApplication sharedApplication] isRegisteredForRemoteNotifications])
    {
        self.notificationRegistration.type = MCDNotificationTypeAPN;
    }
    else
    {
        self.notificationRegistration.type = MCDNotificationTypePolling;
    }
    self.notificationRegistration.appId = [[NSBundle mainBundle] bundleIdentifier];
    self.notificationRegistration.appDisplayName = (NSString*)[[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleDisplayName"];
    self.notificationRegistration.token = deviceToken;
    self.isRegisteredWithToken = YES;

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

Зарегистрируйте приложение для функции взаимодействия с несколькими устройствами на панели мониторинга разработчика Майкрософт. Это отличается от процедуры регистрации приложений MSA и AAD выше. Основной целью этого процесса является сопоставление идентификаторов приложений, специфичных для платформы, с кроссплатформенным идентификатором приложения, распознаваемым платформой подключённых устройств. Этот шаг также позволит отправлять уведомления с помощью собственных служб push-уведомлений, соответствующих мобильным платформам, которые использует ваше приложение. Для iOS это позволяет отправлять уведомления в конечные точки приложений iOS через APNS — службу push-уведомлений Apple.

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

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

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

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

• Предоставьте или выберите идентификаторы приложений из MSA и(или) AAD, полученные на предыдущих шагах вышеупомянутой регистрации приложений MSA/AAD.

• Укажите учетные данные для собственных платформ уведомлений, относящихся к приложению (т. е. WNS для Windows, FCM для Android и /или APNS для iOS), чтобы обеспечить доставку уведомлений с сервера приложений при публикации пользовательских уведомлений.

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

Использование платформы

Создайте экземпляр платформы

Чтобы приступить к работе, просто создайте экземпляр платформы.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];

Подписка на MCDConnectedDevicesAccountManager

Для доступа к платформе требуется прошедший проверку подлинности пользователь. Необходимо подписаться на события MCDConnectedDevicesAccountManager , чтобы убедиться, что используется допустимая учетная запись.

[MCDConnectedDevicesPlatform* platform.accountManager.accessTokenRequested
     subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
                 MCDConnectedDevicesAccessTokenRequestedEventArgs* _Nonnull request __unused) {

                    // Get access token

                 }

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

                      // Refresh and renew existing access token

                 }

Подпишитесь на MCDConnectedDevicesNotificationRegistrationManager

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

[MCDConnectedDevicesPlatform* platform.notificationRegistrationManager.notificationRegistrationStateChanged
     subscribe:^(MCDConnectedDevicesNotificationRegistrationManager* manager __unused,
                 MCDConnectedDevicesNotificationRegistrationStateChangedEventArgs* args __unused) {

                     // Check state using MCDConnectedDevicesNotificationRegistrationState enum

                 }

Запуск платформы

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

[MCDConnectedDevicesPlatform* platform start];

Получение учетных записей пользователей, известных приложению

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

Используйте MCDConnectedDevicesAccountManager.addAccountAsync , чтобы добавить новую учетную запись пользователя.

[MCDConnectedDevicesPlatform* platform.accountManager
     addAccountAsync:self.mcdAccount
     callback:^(MCDConnectedDevicesAddAccountResult* _Nonnull result, NSError* _Nullable error) {

     // Check state using **MCDConnectedDevicesAccountAddedStatus** enum

     }

Чтобы удалить недопустимую учетную запись, можно использовать MCDConnectedDevicesAccountManager.removeAccountAsync

 [MCDConnectedDevicesPlatform* platform.accountManager
     removeAccountAsync:existingAccount
     callback:^(MCDConnectedDevicesRemoveAccountResult* _Nonnull result __unused, NSError* _Nullable error) {

                    // Remove invalid user account

     }

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

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

Следующие методы инициализируют MCDUserNotificationChannel.

// You must be logged in to use UserNotifications
NSArray<MCDUserAccount*>* accounts = [[AppDataSource sharedInstance].accountProvider getUserAccounts];
if (accounts.count > 0)
{
    // Get a UserNotification channel, getting the default channel
    NSLog(@"Creating UserNotificationChannel");
    NSArray<MCDUserAccount*>* accounts = [[AppDataSource sharedInstance].accountProvider getUserAccounts];
    MCDUserDataFeed* userDataFeed = [MCDUserDataFeed userDataFeedForAccount:accounts[0]
        platform:[AppDataSource sharedInstance].platform
        activitySourceHost:CROSS_PLATFORM_APP_ID];
    NSArray<MCDSyncScope*>* syncScopes = @[ [MCDUserNotificationChannel syncScope] ];
    [userDataFeed addSyncScopes:syncScopes];
    self.channel = [MCDUserNotificationChannel userNotificationChannelWithUserDataFeed:userDataFeed];
}
else
{
    NSLog(@"Must log in to receive notifications for the logged in user!");
    self.createNotificationStatusField.text = @"Need to be logged in!";
}

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

Создайте MCDUserNotificationReader для получения входящих MCDUserNotifications и доступа к журналу MCDUserNotification.

Как было показано ранее, первоначальное автоматическое сообщение APNS, поступающее на клиент приложения, содержит только касание плеча, и вам нужно передать полезные данные касания плеча на платформу подключенных устройств, чтобы активировать пакет SDK для выполнения полной синхронизации с сервером подключенных устройств, который содержит все mcDUserNotifications, опубликованные сервером приложений. Это приведет к загрузке полного объема данных уведомлений, опубликованных сервером вашего приложения и соответствующих этому касанию по плечу (и если какие-либо предыдущие уведомления были опубликованы, но не получены на этом клиенте приложения из-за проблем с подключением устройства или других неполадок, они также будут загружены). С помощью этих синхронизаций в реальном времени, которые постоянно выполняются SDK, приложение может получить доступ к локальному кэшу потока данных MCDUserNotification для данного вошедшего пользователя. MCDUserNotificationReader в данном случае позволяет клиенту приложения получать последние данные полезной нагрузки уведомления через слушатель событий или получить доступ к полной коллекции MCDUserNotification, которая может использоваться в качестве модели представления истории уведомлений пользователя.

Получение MCDUserNotifications

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

// Instantiate the reader from a MCDUserNotificationChannel
// Add a data change listener to subscribe to new changes when new notifications or notification updates are received
- (void)setupWithAccount:(MCDUserAccount*)account {
    dispatch_async(dispatch_get_global_queue(QOS_CLASS_DEFAULT, 0), ^{
        @synchronized (self) {
            MCDUserDataFeed* dataFeed = [MCDUserDataFeed userDataFeedForAccount:account platform:_platform activitySourceHost:@"graphnotifications.sample.windows.com"];
            [dataFeed addSyncScopes:@[[MCDUserNotificationChannel syncScope]]];
            self.channel = [MCDUserNotificationChannel userNotificationChannelWithUserDataFeed:dataFeed];
            self.reader = [self.channel createReader];
            
            __weak typeof(self) weakSelf = self;
            _readerRegistrationToken = [self.reader addDataChangedListener:^(__unused MCDUserNotificationReader* source) {
                NSLog(@"ME123 Got a change!");
                if (weakSelf) {
                    [weakSelf forceRead];
                } else {
                    NSLog(@"ME123 WEAKSELF FOR CHANGES IS NULL!!!");
                }
            }];
            
            [self forceRead];
        }
    });
}

// this is your own business logic when the event listener is fired
// In this case, the app reads the existing batch of notifications in the store and handle any new incoming notifications or notification updates after that
- (void)forceRead {
    NSLog(@"ME123 Forced to read!");
    [self.reader readBatchAsyncWithMaxSize:NSUIntegerMax completion:^(NSArray<MCDUserNotification *> * _Nullable notifications, NSError * _Nullable error) {
        if (error) {
            NSLog(@"ME123 Failed to read batch with error %@", error);
        } else {
            [self _handleNotifications:notifications];
            NSLog(@"ME123 Have %ld listeners", self.listenerMap.count);
            for (void (^listener)(void) in self.listenerMap.allValues) {
                NSLog(@"ME123 Calling a listener about an update!");
                listener();
            }
        }
    }];
}

Обновите состояние существующего уведомления MCDUserNotification

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

- (void)dismissNotification:(MCDUserNotification*)notification {
    @synchronized (self) {
        notification.userActionState = MCDUserNotificationUserActionStateDismissed;
        [notification saveAsync:^(__unused MCDUserNotificationUpdateResult * _Nullable result, __unused NSError * _Nullable err) {
            NSLog(@"ME123 Dismiss notification with result %d error %@", result.succeeded, err);
        }];
    }
}