ユーザー通知用に iOS アプリをクライアント側のSDKと統合するIntegrate your iOS app with the client-side SDK for user notifications

Azure ポータルでアプリを登録し、パートナー デベロッパー センターでクロスデバイス体験を始めたら、次の手順で、クライアント側のiOS 版 SDK アプリとクライアント アプリケーションを統合します。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 iOS apps.

クライアント側 SDK を使用することで、アプリは、アプリケーション サーバーから現在サインインしているユーザーを対象に発行された通知の受信を開始するために必要な登録手順を実行できるようになります。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. その後で、この SDK はクライアント側での通知の管理を実行します。これには、新しい着信通知の受信、すべて消去のようなシナリオを実現するための通知状態の管理、および完全な通知履歴の取得が含まれます。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.

新しい着信通知のフローNew incoming notification flow

新しい受信通知を受け取ると、次の図のようなデータ フローが表示されます。For receiving new incoming notifications, the data flow is shown in the following diagram.

iOS アプリの新しい通知のフロー

プロセスには、いくつかのコンポーネントが含まれます:The process involves a few components:

  • アプリケーション サーバー: アプリケーションのバックエンドApp server - The back end of your application
  • アプリケーション クライアント: アプリケーションのフロント エンド (UWP アプリ、Android アプリ、または iOS アプリ)App client - The front end of your application (a UWP app, an Android app, or an iOS app)
  • Microsoft Graph notifications - デバイスおよびプラットフォームを跨ぐアプリケーション クライアント の異なるインスタンス間でのユーザー通知の発行と格納、同期を可能にするサービス コンポーネント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
  • APNs - Apple for ios アプリによって提供される Apple プッシュ通知サービスです。APNs - The Apple Push Notification Service provided by Apple for iOS apps. Microsoft Graph notifications は、このサービスを使用して、ユーザーの通知データの変更についてiOS アプリ クライアントに通知します。Microsoft Graph notifications use this service to signal the iOS app clients about user notification data changes.

この図は次の手順を示します。The diagram shows the following steps:

  1. アプリケーションのロジック。Application logic. この手順では、ユーザーに通知を発行するトリガーになるものを取り込みます。This step captures what triggers the notification to be published to the user. これは、アプリケーション固有のロジックであり、Microsoft Graph の別のもの (予定表イベントやタスクの割り当てなど) に関するイベントまたはデータの更新になることも、それとは別にアプリ サービスでユーザーに通知しようとしているものになることもあります。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. アプリケーション サーバーから対象ユーザーへの通知は、Microsoft Graph 通知 API 経由で発行されます。The app server publishes a notification to the targeted user via the Microsoft Graph notifications API. 詳細については、サーバー側との統合を参照してください。For more details, see server side integration.
  3. 新しい通知が含まれている Web 要求を受信すると、Microsoft Graph 通知は、このアプリとユーザーのためにクラウドで通知の内容を安全に保持します。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. このユーザーが通知を受け取るための各アプリケーション クライアント インスタンスのサブスクリプションには、Microsoft Graph notifications がオペレーティング システムによって提供されるネイティブ プッシュ サービスを使用して、アプリのクライアントに通知を送信します。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. この例ではアプリケーションはiOS のアプリで、 [APNs バック グラウンド更新の通知] を使用して通知を送ります。In this case, the application is an iOS app, and it uses [APNs background update notification] to send the signal.
  5. 受信プッシュ通知によって通知がアプリケーションに送られた後、アプリケーションはユーザー通知ストア内の変更の取得を SDK に求めます。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. SDK は、Microsoft Graph 内で、ユーザー通知ストアとの安全で準拠した接続を確立します。The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  7. SDK は、データの変更 (この場合は新しい通知の内容) を取得します。The SDK gets the data changes - in this case, the new notification contents.
  8. 変更が正常に取得された後、アプリに通知するためのイベント コールバックが SDK で発生します。The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  9. アプリケーションのロジック。Application logic. この手順では、アプリがイベント コールバック内で実行する内容を取得します。This step captures what your app chooses to do inside the event callback. 通常、ローカルのアプリデータが変更され、ローカルの UI 更新が発生します。Usually, this results in local app data changes and local UI updates. この場合、アプリは通常、通知コンテンツをユーザーに通知する iOS アラートを作成します。In this case, the app usually constructs an iOS alert to notify the user about the notification contents.

通知の更新フローNotification update flow

Microsoft Graph 通知を使用する主な利点の 1 つは、通知が安全にクラウドで保持され、ステートフル リソース タイプに変更できることです。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. そのため、アプリケーションはクロスデバイス シナリオにおいて、サインインしている同一のユーザーに対して、異なるデバイス間で通知の正しい状態を管理および同期できます。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. あるデバイスで通知が消去または既読になったときには、その他のデバイスにリアルタイムで通知されます。When a notification is marked as dismissed, or marked as read on one device, the other devices can be notified in real-time. "一度処理すれば、すべての場所で消去される" ということが、ユーザーの通知体験の一部として実現されます。"Handled once, dismissed everywhere" can become a true promise as part of the notification experience for your users.

次の図は、通知の状態を変更したり、一つのデバイスでの通知を削除したり、別のデバイスで状態の変更または削除を受信/処理するためのデータフローを示しています。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.

iOS アプリの更新通知のフロー

フローの2番目の部分の通知は、新しい受信通知の処理の流れと似ています。Notice that the second part of the flow is similar to the flow for handling new incoming notifications. これは仕様によるものです。SDK のプログラミング パターンでは、あらゆる種類のユーザー通知データの変更 (新規に受信した通知、通知状態の変更、通知の削除など) をアプリケーション クライアントが同じような方法で処理できるように設計されています。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.

この図は、次の手順を示しています。The diagram shows the following steps:

  1. アプリケーションのロジック。Application logic. 何らかのものが、通知の変更または削除をトリガーします。Something triggers the notification to be changed or deleted. 一般に、あらゆるイベントが通知を変更するトリガーになり得ます。In general, any event can trigger a notification to change.
  2. 通知を更新または削除するクライアント SDK のアプリによる呼び出し。App calling into the client SDK to update or delete a notification. 現在、状態の変更に関して 2 つのプロパティ (userActionState および readState) が公開されていますが、こうした状態とその状態の更新時期はアプリケーションで定義できます。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. たとえば、ユーザーが通知ポップアップを消去したときには、userActionState が消去済み (Dismissed) になるように更新します。For example, when a user dismisses the notification popup, you can update the userActionState to be Dismissed. ユーザーが通知ポップアップをクリックして、それに対応するアプリのコンテンツを利用するアプリを起動したときに、userActionState をアクティブ化済み (Activated) に更新し、readState を読み取り (Read) に更新します。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. 通知を更新または削除するために対応する API が呼び出された後、SDK は、クラウド内のユーザー通知ストアに送信して、この変更をサインインしている同一ユーザーの別のアプリクライアント インスタンスに展開します。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. クライアントから更新/削除要求を受信した Microsoft Graph 通知は、通知ストアを更新して、この変更をサブスクライブしている別のアプリ クライアント インスタンスを特定します。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. 各アプリケーションの クライアント サブスクリプションには、Microsoft Graph notifications がオペレーティング システムによって提供されるネイティブ プッシュ サービスを使用して、アプリのクライアントに通知を送信します。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. この例では、iOS のアプリで、 APNs バック グラウンド更新の通知を使用して通知を送ります。In this case, this is an iOS, and it uses APNs background update notification to send the signal.
  6. 受信プッシュ通知によって通知がアプリケーションに送られた後、アプリケーションはユーザー通知ストア内の変更の取得を SDK に求めます。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. SDK は、Microsoft Graph 内で、ユーザー通知ストアとの安全で準拠した接続を確立します。The SDK establishes a secure and compliant connection with the user notifications store in Microsoft Graph.
  8. SDK によってデータが変更されます。ここでは、変更内容は通知状態の更新または通知の削除です。The SDK gets the data changes - in this case, the changes are notification state updates or notification deletions.
  9. 変更が正常に取得された後、アプリに通知するためのイベント コールバックが SDK で発生します。The SDK fires event callbacks to notify the app after the changes are successfully retrieved.
  10. アプリケーションのロジック。Application logic. この手順では、アプリがイベント コールバック内で実行する内容を取得します。This step captures what your app chooses to do inside the event callback. 通常、ローカルのアプリ データが変更され、ローカルの UI 更新が発生します。Usually, this results in local app data changes and local UI updates. この場合、通知の更新があるため、アプリはローカルに UI を更新して状態の変更を反映させる必要があります。In this case, because there are notification updates, the app should update the UI locally to reflect the state change. たとえば、通知がアクティブ化されている場合、iOS 通知センター内の対応するアラート UI を削除すると、"一度処理すれば、すべての場所で消去" することができます。For example, if a notification is marked as activated, you can remove the corresponding alert UI inside the iOS notification center to achieve "handled once, dismissed everywhere".

Microsoft Graph 通知の詳細については、Microsoft Graph Notifications の概要を参照してください。For more information about Microsoft Graph notifications, see Microsoft Graph Notifications overview. 全てを Microsoft Graph notifications と統合するために必要な手順の詳細については、Microsoft Graph notifications の統合の概要を参照してください。For more information about the steps required to integrate with Microsoft Graph notifications from end to end, see Microsoft Graph notifications integration overview.

プロジェクトに SDK を追加するAdding the SDK to your project

Connected Devices Platform にiOS アプリを追加する最も簡単な方法は、CocoaPods 依存管理マネージャーを使用することです。The simplest way to add the Connected Devices Platform to your iOS app is by using the CocoaPods dependency manager. iOS プロジェクトのPodfileに移動し、次のエントリを挿入します。Go to your iOS project's Podfile and insert the following entry:

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 ファイルを使用する必要があります。In order to consume CocoaPod, you must use the .xcworkspace file in your project.

Connected Device Platforms の初期化Initializing the Connected Device Platforms

クライアント側のSDKは、Connected Device Platforms と呼ばれるインフラストラクチャの上に構築されています。The client-side SDK is built on top of an infrastructure called Connected Device Platform. 機能を使用するには、アプリ内でプラットフォームを初期化する必要があります。Before any feature can be used, the platform must be initialized within your app. この初期化手順は、通知シナリオを実行する前に必須であるため、AppDelegate メソッド内で実行する必要があります。The initialization steps should occur in your AppDelegate method, because they are required before the notification scenarios can take place.

MCDConnectedDevicesPlatform クラスをインスタンス化して、プラットフォームを構築および初期化する必要があります。You must construct and initialize the platform by instantiating the MCDConnectedDevicesPlatform class. これを行う前に、プラットフォームが起動した後、イベントが発生する可能性があるため、以下のようにイベントハンドラーを接続してください。efore doing that, make sure to hook up event handlers, as shown, because after platform is started, the events might begin to fire.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
        
[platform.accountManager.accessTokenRequested subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager, MCDConnectedDevicesAccessTokenRequestedEventArgs* _Nonnull args) {
    // implement the callback;
}];
        
[self.platform.accountManager.accessTokenInvalidated
    subscribe:^(MCDConnectedDevicesAccountManager* _Nonnull manager __unused,
        MCDConnectedDevicesAccessTokenInvalidatedEventArgs* _Nonnull request) {
    // implement the callback;
}];
        
[self.platform.notificationRegistrationManager.notificationRegistrationStateChanged subscribe:^(MCDConnectedDevicesNotificationRegistrationManager* _Nonnull manager __unused, MCDConnectedDevicesNotificationRegistrationStateChangedEventArgs* _Nonnull args) {
    // implement the callback
}];
        
[platform start];

アカウント アクセス トークンの処理Handling account access token

新しい着信通知のコンテンツの取得、通知状態の更新など、SDK で実行されるすべての Web 呼び出しは、ユーザーのデータに対する読み取りと書き込みになるため、常に有効なアクセス トークンが必要になります。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. プラットフォームが初期化された後に、ユーザーのアクセストークンが正常に機能するために、SDK は次のイベント - アクセス トークン が要求または無効化されたときに呼び出された - の処理を必要とします。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

完全に実装するには、 iOS サンプルアプリを参照してください。For a full implementation, see the iOS sample app.

accessTokenInvalidatedaccessTokenInvalidated

完全に実装するには、 iOS サンプルアプリを参照してください。For a full implementation, see the iOS sample app.

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

プッシュ登録の有効期限を処理するHandling push registration expiration

Microsoft Graph notifications は、Apn、iOSのネイティブのプッシュ プラットフォームを使用して、ユーザー通知のデータ変更をクライアント アプリケーションに通知します。Microsoft Graph notifications use APNs, the native push platform on iOS, to signal the client application on user notifications data changes. これは、新しい受信通知がアプリサーバーから発行されている場合、またはクロスデバイス シナリオにおいてサインインした同じユーザーの別のデバイスで通知の状態が更新された場合に発生します。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.

このような理由から、バックグラウンドでの更新通知を正常に受信するための有効な APNs トークンが必要です。For this reason, a valid APNs token that allows background update notifications to come through successfully is required. 次のイベントコールバックでは、APNs プッシュトークンの有効期限を処理します。The following event callback handles APNs push token expirations.

notificationRegistrationStateChangednotificationRegistrationStateChanged

完全に実装するには、 iOS サンプルアプリを参照してください。For a full implementation, see the iOS sample app.

ユーザーにサインインするSigning in your user

Microsoft Graph通知は、その他の Microsoft Graph の多くのリソース タイプと同様に、ユーザーが中心になります。Microsoft Graph notifications, like many other resource types inside Microsoft Graph, are centralized around users. サインインしているユーザーの通知にアプリでサブスクライブして受信を開始するには、まず、登録プロセスで使用する有効な OAuth トークンを取得する必要があります。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. OAuth トークンの生成方法と管理方法、は適切なものを選択できます。You can use your preferred method of generating and managing the OAuth tokens. サンプル アプリでは ADAL を使用します。The sample app uses ADAL.

Microsoft アカウントを使用している場合は、サインイン要求に次のアクセス許可を含める必要があります: wl.offline_access"ccs.ReadWritewns.connectasimovrome.telemetry、および https://activity.windows.com/UserActivity.ReadWrite.CreatedByAppIf 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.

Azure AD アカウントを使用している場合は、次の対象ユーザーを要求する必要があります: https://cdpcs.access.microsoft.comIf you're using an Azure AD account, you'll need to request the following audience: https://cdpcs.access.microsoft.com.

プラットフォームにユーザー アカウントを追加するAdding the user account to the platform

サインインしたユーザーアカウントを SDK に登録する必要があります。You need to register the signed in user account with the SDK. これは、アカウントの追加と、 APN を通じて初期通知を受信するプッシュチャネルの登録を伴います。This involves adding the account and registering a push channel to receive the initial push notifications through APNs. 詳細については、サンプルのprepareAccountAsync メソッドを参照してください。For details, see the prepareAccountAsync method in the sample.

MCDConnectedDevicesPlatform* platform = [MCDConnectedDevicesPlatform new];
MCDConnectedDevicesAccount* mcdAccount = [MCDConnectedDevicesAccount new];

[platform.accountManager addAccountAsync:mcdAccount callback:adapter]; 

ユーザーの通知を受信するためのサブスクライブSubscribing to receive user's notifications

このサインインしているユーザーのアプリケーション用に、UserDataFeed オブジェクトをインスタンス化する必要があります。You need to instantiate a UserDataFeed object for your application for this signed in user. アプリケーションは、クロスデバイス エクスペリエンスの開始時に指定したクロスプラットフォーム アプリ ID によって識別されます。Your application is identified by the cross-platform app ID you provided during the Cross-Device Experiences onboarding process.

// Initialize the feed and subscribe for notifications
MCDUserDataFeed* feed = [MCDUserDataFeed getForAccount:account
                        platform:platform
                        activitySourceHost:APP_HOST_NAME];

NSArray<MCDUserDataFeedSyncScope*>* syncScopes = @[ [MCDUserNotificationChannel syncScope] ];
[feed subscribeToSyncScopesAsync:syncScopes
        callback:^(BOOL success __unused, NSError* _Nullable error __unused) {
    // Start syncing down notifications
    [feed startSync];
}];

ユーザー通知を受信および管理するReceiving and managing user notifications

このトピックの前半のフロー図では、アプリ サーバーからの新しい着信通知や、別のアプリケーション クライアント インスタンスで開始された通知の更新または削除を処理するためのプログラミング パターンを示しました。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. このようなデータの変更を処理する手順は次のとおりです。The following are the steps for handling these data changes.

着信プッシュ通知シグナルの処理Handling incoming push notification signal

全ての種類のユーザー通知データの変更について、プッシュ通知としてアプリクライアントに配信されるシグナルが生成されます。All types of user notification data changes generate a signal that gets delivered to the app clients as a push notification. iOS アプリの場合、シグナルは APNs バックグラウンド更新通知として配信されます。In the case of an iOS app, the signal is delivered as an APNs background update notification. データ メッセージ シグナルを受信するには、アプリがTryParseを呼び出し、実際のデータ変更のためのSDKによる Microsoft Graph notifications サービスからの取得をトリガーします。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.

// App running in background and received a push notification, launched by user tapping the alert view
MCDConnectedDevicesNotification* notification = [MCDConnectedDevicesNotification tryParse:notificationInfo];
if (notification != nil) {
    [_platformManager.platform processNotificationAsync:notification
            completion:^(NSError* error __unused) {
        // 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.
    }];
} else {
    NSLog(@"Remote notification is not for ConnectedDevicesPlatform, skip processing");
}

ユーザー通知のデータ変更の処理Handling user notification data changes

SDK によってデータ変更が正常にフェッチされると、イベント コールバックが呼び出され、アプリ クライアントによる通知の作成、更新、または削除の処理が求められます。After the SDK successfully fetches the data changes, an event callback is invoked and the app client is expected to handle notification creation, update, or deletion.

[reader readBatchAsyncWithMaxSize:100 completion:^(NSArray<MCDUserNotification *> * _Nullable notifications,
                                                    NSError * _Nullable error) {
    if (error) {
    } else {
        for (MCDUserNotification* notification in self.notifications) {
        // Handle notification change based on change type;
        }
        }
    }
}];

通知の更新状態Update state of a notification

このアプリクライアントインスタンスから通知状態が変更された場合 (たとえば、このデバイスのトースト通知ポップアップがユーザーによって有効化された場合)、アプリは 同じユーザーが使用する全てのデバイスでこの状態の変更を同期するために、SDK を呼び出して通知の状態を更新する必要があります。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.

- (void)dismissNotification:(MCDUserNotification*)notification {
    if (notification.userActionState == MCDUserNotificationUserActionStateNoInteraction) {
        [self dismissNotificationFromTrayWithId:notification.notificationId];
        notification.userActionState = MCDUserNotificationUserActionStateDismissed;
        [notification saveAsync:^(__unused MCDUserNotificationUpdateResult * _Nullable result, __unused NSError * _Nullable error) {
        // handle result;
         }];
    }
}

通知を削除するDelete a notifications

このアプリクライアントインスタンスから通知の削除が行われた場合 (たとえば、この通知に対応するタスクが完了とマークされ、アプリのデータベースから削除された場合)、アプリは同じユーザーが使用する全てのデバイスでこの削除の操作を同期するために、SDK を呼び出して通知を削除する必要があります。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.

通知は、有効期限が切れているか、明示的に削除された場合にのみ、ユーザー通知ストアから削除されます。A notification is removed from the user notification store only if it is expired or explicitly deleted. UserActionState のセマンティック定義はアプリケーション自体によって定義されているため、UserActionState が消去済み (Dismissed) になるように更新しても、ユーザー通知は削除されません。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.

- (void)deleteNotification:(MCDUserNotification*)notification {
    [_channel deleteUserNotificationAsync:notification.notificationId
     completion:^(__unused MCDUserNotificationUpdateResult* _Nullable result, NSError* _Nullable error) {
        // handle result;
     }];
}

関連項目See also