アクティビティフィード REST API を使用するUse the activity feed REST API

重要

Microsoft Graph の/betaバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported.

Microsoft Graph のアクティビティフィード API を使用して、デバイスとプラットフォーム間でユーザーのアクティビティを再開できます。You can use the activity feed API in Microsoft Graph to resume a user's activity across devices and platforms. アクティビティフィード API 要求は、委任されたアクセス許可ユーザーアクティビティのアクセス許可を使用してユーザーの代理として実行されます。これは、個人用アカウントまたは職場アカウントまたは学校アカウントで使用できます。Activity feed API requests are performed on behalf of a user via delegated permissions and the user activity permission, which can be used with either personal or work and school accounts.

ユーザーアクティビティは、アクティビティリソースによって表され、コレクションの me/アクティビティで表される時間ベースのフィードに整理されます。User activities are represented by the activity resource and are organized in a time-based feed represented by the collection me/activities.

非常に高いユーザーアクティビティになるのは、どのようなものですか。What makes a great user activity?

ユーザーアクティビティはアプリを起動するだけではなく、アプリ内の特定のコンテンツに対する深いリンクです。User activities don’t just launch apps — they are deep links into specific content within your app. 作成したユーザーアクティビティは、独自のアプリで使用するだけではなく、Cortana と Windows タイムラインにも表示されます。これにより、アプリの再利用が向上し、ユーザーが複数のデバイスでアプリを引き続き使用することが容易になります。The user activities you create can not only be used in your own app, but will also appear in Cortana and Windows Timeline — driving more app reengagement and making it easier for your users to continue using your app across multiple devices.

アクティビティになる必要があるものWhat should become an activity?

すべてのアプリが異なるため、アプリケーション内のアクションをユーザーアクティビティにマップするための最善の方法を、各アプリ開発者が理解している必要があります。Because every app is different, it's up to each app developer to understand the best way to map actions within your application to user activities. たとえば、ゲームは各キャンペーンに対してアクティビティを作成し、ドキュメント作成アプリは固有のドキュメントごとにアクティビティを作成し、基幹業務アプリは各ワークフローのアクティビティを作成する場合があります。For example, games might create an activity for each campaign, document authoring apps might create an activity for each unique document, and line-of-business apps might create an activity for each workflow.

アプリで activitites を定義するときに、次のガイドラインを適用します。Apply the following guidlines as you define activitites in your app:

実行: 関連するユーザーアクションのグループに対して1つのアクティビティを記録します。DO: Record a single activity for a group of related user actions. アプリケーションが関連するコンテンツのシーケンスに使用されている場合は、契約セッション全体に対して1つのアクティビティを記録することが適切な場合があります。If your application is used for a sequence of related content, it probably makes sense to record a single activity for the entire engagement session.

再生リストのシナリオ: これは、音楽の再生リストまたはテレビ番組に特に関連しています。1つのユーザーアクティビティを更新して、進行状況を表示することができます。Playlist scenarios: This is especially relevant for music playlists or TV shows — a single user activity can be updated to show your progress. この例では、複数の日数または数週間にわたる契約期間を表す複数の履歴項目を持つ1つのユーザーアクティビティがあります。In this case, you will have a single user activity with multiple history items representing periods of engagement across multiple days or weeks.

実行: ユーザーデータをクラウドに格納します。DO: Store user data to the cloud. クロスデバイスアクティビティをサポートする必要がある場合は、このアクティビティを再利用するために必要なコンテンツがクラウドの場所に格納されていることを確認する必要があります。If you want to support cross-device activities, you need to make sure the content required to reengage this activity is stored to a cloud location. たとえば、ユーザーがドキュメントを編集するたびにアクティビティを発行する場合は、クロスデバイス再契約を有効にするために、ドキュメントをユーザーのデバイス上でローカルに保存するのではなく、クラウドに保存する必要があります。For example, if you publish an activity each time a user edits a document, the document should be stored in the cloud as opposed to locally on the user's device in order to enable cross-device reengagement.

次の操作は行わないでください。 ユーザーが今後再開する必要がない操作のユーザーアクティビティを作成します。DO NOT: Create a user activity for actions that users do not need to resume in the future. アプリケーションを使用して、状態を保持しない簡単なワンタイム操作を実行する場合、今後はユーザーアクティビティを記述する必要はありません。If your application is used to complete simple, one-time operations that do not persist status for you to track in the future, you probably do not need to write a user activity.

ユーザーアクティビティが Windows タイムラインに表示される場合でも、バージョン管理ツールとして設計されていませんが、ドキュメントベースのアクティビティを選択すると、そのドキュメントの最新バージョン (他のユーザーによる変更を含む) が常に表示されるようになります。To be clear, even though user activities appear in Windows Timeline, this is not designed as a versioning tool — choosing a document-based activity should always show the latest version of that document (including changes that were made by another user.)

*次の操作は行わないでください。***他のユーザーによって完了したアクションのユーザーアクティビティを作成します。DO NOT: Create a user activity for actions completed by other users. ユーザーがメッセージを送信したり、アプリ内でユーザーに @mentions したりした場合は、新しいアクティビティを作成しないでください。If someone sends the user a message, or @mentions the user within your app, you should not write a new activity. これらの相互作用は、提示された通知により提供されます。These interactions are better served by surfacing notifications.

グループ作業のシナリオ: 複数のユーザーが同じ操作 (Word 文書など) に対して作業を行っている場合、最後に編集した後に別のユーザーがドキュメントを変更した可能性があります。Collaboration scenarios: If multiple people are working on the same activity (such as a Word document), there will be cases when another user has made changes to the document after you last edited it. この場合、アプリ開発者は、ドキュメントに加えられた変更を反映するために、アクティビティ内のビジュアル要素を更新する必要があります。In this case, app developers might want to update the visual elements in the activity to reflect changes made to the document. これを行うために、アプリは新しい履歴アイテムを作成せずに既存のアクティビティを更新する場合があります。To do this, the app might update the existing activity without creating a new history item.

注: Web アプリケーションのアクティビティを発行している場合は、アクティビティごとactivationURL fallbackURLにとの両方を含めることが重要です。Note: If you're publishing activities for a web application, it's important to include both an activationURL and a fallbackURL for each of your activities. アクティビティは、Windows タイムラインのような Microsoft エクスペリエンスから期待したとおりにユーザーをアプリに戻します。The activities will launch the user back into your app as expected from Microsoft experiences like Windows Timeline.

アプリの相互作用パターンとユーザーアクティビティApp interaction patterns and user activities

作成するユーザーアクティビティは、アプリの対話パターンに応じて異なります。The user activities that you create will vary based on the interaction pattern of your app. すべてのアプリは異なりますが、ほとんどは次の相互作用パターンのいずれかに分類されます。While every app is different, most will fall into one of the following interaction patterns:

  • ドキュメントベースのアプリ-使用期間を反映した1つまたは複数の履歴レコードを含む1つのアクティビティをドキュメントごとに作成します。Document-based apps — Create one activity per document with one or more history records reflecting periods of use. ドキュメントが変更されたときに、アクティビティカードを更新することが重要です。It is important to update your activity card as changes are made to the document.
  • メディア再生アプリ—再生リスト、プログラム、スタンドアロンコンテンツなどのコンテンツの論理グループごとに1つのアクティビティを作成します。Media playback apps — Create one activity per logical grouping of content such as a playlist, program, or standalone content.
  • ゲーム-セーブされたゲームまたは world ごとに1つのアクティビティを作成します。Games — Create one activity for each saved game or world. ゲームでサポートされているレベルのシーケンスが1つだけの場合は、時間の経過とともに同じアクティビティを書き込むことができますが、最新の進捗状況やアチーブメントを表示するようにカードを更新する必要がある場合もあります。If your game supports only a single sequence of levels, you can write the same activity over time, although you might want to update your card to show your latest progress or achievements.
  • ユーティリティアプリ: ユーザーが再開することをアプリ内に何もない場合は、アクティビティを発行しないでください。Utility apps — If there is nothing within your app that users would want to resume, you should not publish activities. 良い例として、電卓などの単純な単一用途のアプリがあります。A good example is a simple single-purpose app like calculator.
  • 基幹業務アプリ—単純なタスクやワークフローを管理するための多数のアプリがあります。Line-of-business apps — Many apps exist for managing simple tasks or workflows. アプリを通じてアクセスする個別のワークフローごとに1つのアクティビティを作成します。Create one activity for each separate workflow accessed through your app. たとえば、各経費報告書は個別のアクティビティであるため、そのアクティビティをクリックして承認されたかどうかを確認したい場合があります。For example, each expense report would be a separate activity, because you might want to click that activity to see if it was approved.

一部の複雑なアプリには、複数の相互作用パターンが含まれています。アプリによって処理されるさまざまなシナリオについて、さまざまなユーザーアクティビティ作成パターンに従うことをお勧めします。Some complex apps include multiple interaction patterns. You might want to follow different user activity creation patterns for different scenarios handled by your app.

次のステップNext steps

その他のアイデアをお探しですか?Looking for more ideas?