使用活动源 REST APIUse the activity feed REST API

您可以使用的活动源 API 在 Microsoft Graph 中恢复用户的 actiity 设备和平台。You can use the activity feed API in Microsoft Graph to resume a user's actiity 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.

用户活动由活动资源和组织中的基于时间的源表示在集合中的我 / 活动。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 时间线 — 推动多个应用程序 reengagement 和简化您的用户可以继续使用多个设备的应用程序。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:

执行操作: 记录一组相关的用户操作的单个活动。DO: Record a single activity for a group of related user actions. 如果您的应用程序用于序列的相关内容,可能有意义的整个项目会话记录的单个活动。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.

播放列表方案: 这是音乐播放列表或 TV 显示密切相关 — 单个用户活动可以更新以显示您的进度。Playlist scenarios: This is especially relevant for music playlists or TV shows — a single user activity can be updated to show your progress. 在这种情况下,您将拥有多个历史记录项的项目的时间段代表跨多个天或数周单个用户活动。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. 如果您想要支持跨设备活动,您需要确保所需 reengage 此活动的内容存储到云位置。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. 例如,如果用户在编辑文档的每次发布活动时,文档应存储在云中而不是用户的设备上的本地以启用跨设备 reengagement。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 应用程序的活动,请务必同时包括activationURLfallbackURL您的活动的每个。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. 活动将回您的应用程序启动用户,按预期方式从 Microsoft Windows 日程表类似的体验。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:

  • 基于文档的应用程序— 这就反映了使用时段的一个或多个历史记录具有创建每个文档的一个活动。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.
  • 媒体播放应用程序— 创建的内容,例如播放列表、 程序或独立内容的逻辑分组每一个活动。Media playback apps — Create one activity per logical grouping of content such as a playlist, program, or standalone content.
  • 游戏— 游戏或打造为每保存创建一个活动。Games — Create one activity for each saved game or world. 如果您的游戏支持单个序列的级别,您可以随时间推移,编写同一个活动,但您可能要更新您的卡片显示您最新的进度或成绩。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. 创建一个通过您的应用程序访问每个单独的工作流活动。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?