共用方式為


How-To 指南:與圖形通知整合 (iOS)

圖形通知可讓您的應用程式跨多個裝置傳送及管理用戶目標通知。

在 iOS 上使用 Project Rome 用戶端 SDK,您的 iOS 應用程式可以註冊以接收從以登入使用者為目標的應用程式伺服器發佈的通知。 SDK 可讓應用程式用戶端接收新的傳入通知承載、管理現有通知的狀態,以及復原通知歷程記錄。 如需有關通知和如何啟用以人為本的通知傳遞方式的詳細資訊,請參閱 Microsoft Graph 通知概觀

Project Rome SDK 中的所有功能,包括圖形通知等等,都是建置在稱為連線裝置平臺的基礎平臺之上。 本指南旨在引導您完成開始使用連線裝置平臺的必要步驟,並說明如何使用 SDK 中的 API 來實作 Graph 通知 -specific 功能。

下列步驟會參考 GitHub 上提供的 Project Rome iOS 範例應用程式 的程式代碼。

如需與通知案例相關的參考文件連結,請參閱 API 參考 頁面。

設定連線的裝置平臺和通知

註冊您的應用程式

Microsoft帳戶(MSA)或 Azure Active Directory(AAD)驗證幾乎是使用 Project Rome SDK 所有功能的必要條件(唯一的例外是附近分享的 API)。 如果您還沒有 MSA 且想要使用 MSA,請在 account.microsoft.com 註冊。

備註

裝置轉接 API 不支援 Azure Active Directory (AAD) 帳戶。

使用您選擇的驗證方法,您必須依照 應用程式註冊入口網站的指示,向Microsoft註冊應用程式。 如果您沒有Microsoft開發人員帳戶,則必須建立一個帳戶。

當您使用 MSA 註冊應用程式時,應該會收到用戶端識別符字串。 儲存此專案以供稍後使用。 這可讓您的應用程式存取Microsoft的連線裝置平台資源。 如果您使用 AAD,請參閱 Azure Active Directory 驗證連結庫 ,以取得用戶端標識符字串的指示。

新增 SDK

將連線裝置平臺新增至 iOS 應用程式最簡單的方式是使用 CocoaPods 相依性管理員。 進入 iOS 專案的 Podfile,並插入下列條目:

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

備註

若要取用 CocoaPod,您必須在專案中使用 .xcworkspace 檔案。

設定驗證和帳戶管理

聯機裝置平臺需要有效的 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"

備註

裝置轉接 API 不支援 Azure Active Directory (AAD) 帳戶。

如果您使用 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 > 應用程式註冊):

  • Microsoft活動推送服務
    • 傳遞和修改此應用程式的使用者通知
    • 讀取和寫入用戶的應用程式活動訊息摘要
  • Windows 通知服務
    • 將裝置連線到 Windows 通知服務
  • Microsoft裝置目錄服務
    • 查看您的裝置清單
    • 新增至裝置和應用程式清單
  • Microsoft命令服務
    • 與使用者裝置通訊
    • 讀取用戶裝置

註冊應用程式以啟用推播通知

向 Apple 註冊您的應用程式以取得 Apple 推播通知 支援。 請務必記下您收到的發件者標識碼和伺服器密鑰,因為稍後會用到這些密鑰。

註冊之後,您必須將推播通知功能與應用程式中的連線裝置平臺產生關聯。

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 開發人員中心註冊您的應用程式,以取得跨裝置體驗

警告

只有在您想要使用 Project Rome 功能來存取非 Windows 裝置的數據或提出要求時,才需要此步驟。 如果您只以 Windows 裝置為目標,就不需要完成此步驟。

註冊您的應用程式以取得 Microsoft開發人員儀錶板的跨裝置體驗功能。 這是與上述 MSA 和 AAD 應用程式註冊不同的程序。 此流程的主要目標是將平台特定的應用程式身分識別對應到連接裝置平台所辨識的跨平台應用程式身分識別。 此步驟也會使用與您應用程式所使用的行動平台相對應的原生推播通知服務來啟用傳送通知。 針對 iOS,它可讓通知透過 APNS – Apple Push Notification Service 傳送至 iOS 應用程式端點。

移至開發人員中心儀錶板,從左側流覽窗格流覽至 [跨裝置體驗],然後選取 [設定新的跨裝置應用程式]。 開發人員中心儀錶板 – 跨裝置體驗

開發人員中心上線程式需要下列步驟:

  • 選取支援的平臺 – 選取您的應用程式將存在並啟用跨裝置體驗的平臺。 在 Graph 通知整合的情況下,您可以根據您使用的平臺,從 Windows、Android 和/或 iOS 中選取。 跨裝置體驗 – 支持的平臺

  • 提供應用程式識別碼 – 提供您所使用的每個平台的應用程式識別碼。 針對 iOS 應用程式,這是您在建立專案時指派給應用程式的套件名稱。 請注意,您可以為每個平臺新增不同的標識碼(最多10個),以防您有多個版本的相同應用程式,甚至是不同的應用程式,而想要接收應用程式伺服器針對相同使用者所傳送的相同通知。 跨裝置體驗 – 應用程式識別碼

  • 提供或選取上述 MSA/AAD 應用程式註冊步驟中取得的 MSA 和/或 AAD 應用程式註冊的應用程式識別碼。 跨裝置體驗 – MSA 和 AAD 應用程式註冊

  • 為與您的應用程式相關的原生通知平臺提供認證(例如適用於 Windows 的 WNS、適用於 Android 的 FCM 和/或 iOS 版 APNS),以在發佈使用者目標通知時,啟用從應用程式伺服器傳遞通知。 跨裝置體驗 – 推送認證

  • 最後,確認您的跨裝置應用程式網域,以確定您的應用程式擁有網域的擁有權,並可以使用它作為應用程式的跨裝置身分識別。 跨裝置體驗 – 網域驗證

使用平台

建立平台的實例

若要開始使用,只需具現化平臺即可。

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];

訂閱 MCD 連接設備帳戶管理員

平臺需要已驗證的使用者才能存取平臺。 您必須訂閱 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

     }

初始化圖形通知通道

Project Rome SDK 可讓您的應用程式訂閱不同的頻道,以便接收和管理各種類型的用戶數據,包括圖形通知、用戶活動等等。 這些全都會儲存並同步處理於 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!";
}

此時,您應該在channel內具有MCDUserNotificationChannel的參考。

建立 MCDUserNotificationReader 以接收傳入的 MCDUserNotifications 並存取 MCDUserNotification 歷程記錄

如先前所示,抵達應用程式用戶端的初始 APNS 靜默訊息只包含肩部提醒,您需要將肩部提醒的有效載荷傳遞至連接設備平台,以觸發 SDK 與連接設備伺服器完成完整同步,其中包含應用程式伺服器發佈的所有 MCDUserNotifications。 這將提取應用程式伺服器所發佈並與此通知請求對應的完整通知承載(如果之前有任何因裝置連接或其他問題而未在此應用程式客戶端接收到的通知,也會被一併提取)。 透過 SDK 持續執行的這些即時同步處理,應用程式用戶端能夠存取此登入使用者 MCDUserNotification 數據摘要的本機快取。 在此情況下,MCDUserNotificationReader 可讓應用程式用戶端存取此數據摘要 – 透過事件接聽程式接收最新的通知承載,或存取完整的 MCDUserNotification 集合,以做為使用者通知記錄的檢視模型。

接收 MCDUserNotifications

首先,您需要實例化一個 MCDUserNotificationReader,然後取得讀取器中所有現有的 MCDUserNotifications。如果您有興趣使用這些資訊來提升您嘗試啟用的體驗,請執行此操作。 一律假設應用程式伺服器已將此登入的使用者發佈通知,因為此特定裝置端點可能不是使用者已安裝您應用程式的唯一或第一個端點。 然後,新增事件接聽程式,此接聽程式會在連線的裝置平臺完成同步處理時觸發,並有新的變更通知您。 在圖形通知的情況下,新的變更可能是由您的應用程式伺服器發佈的新傳入 MCDUserNotification,或是來自伺服器或相同使用者登入的其他已註冊端點的 MCDUserNotification 更新、刪除和過期。

小提示

此事件接聽程式是您處理主要商業規則,並根據案例「取用」通知承載的內容。 如果您目前使用APNS無訊息通知在OS層級通知中心建構視覺通知,或者如果您使用無訊息通知中的內容來更新一些應用程式內UI,這就是執行此動作的地方。

// 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 為目標的通知。使用者 A 會在安裝應用程式用戶端的電腦上和手機上收到此通知。 用戶點擊電腦上的通知,進入應用程式以處理相應的任務。 然後,此電腦上的應用程式用戶端會呼叫連線裝置平臺 SDK 來更新對應使用者通知的狀態,以便讓此更新同步處理到所有使用者的裝置。 其他應用程式用戶端會在即時收到此狀態更新時,從裝置的通知中心/通知匣/控制中心移除對應的視覺警示/訊息/快顯通知。 這就是通知如何在用戶的各個裝置上被統一清除的方式。

小提示

MCDUserNotification 類別目前提供 2 種類型的狀態更新 – 您可以修改 MCDUserNotificationReadState 或 MCDUserNotificationUserActionState,並定義通知更新時應該發生的狀況您自己的邏輯。 例如,您可以將動作狀態標示為 Activated 或 Dismissed,並依據該值進行處理,以實作統一取消。 或者,或者同時,您可以將讀取狀態標示為 [讀取] 或 [未讀取],並根據該決定哪些通知應該顯示在應用程式內通知歷程記錄檢視中。

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