构建由 Project Rome 提供支持的跨设备应用Build cross-device apps powered by Project Rome

可以使用 Project Rome 构建无缝跨设备和平台的体验,从而为用户减少摩擦并帮助促进应用参与。You can use Project Rome to build experiences that cross devices and platforms seamlessly, reducing friction for users and helping to drive app engagement. 对于要使用 Project Rome API 跨设备和平台共享数据的应用程序,你需要配置跨设备应用,其中包含有关你特定于平台的应用的信息。For applications to share data across devices and platforms using Project Rome APIs, you need to configure a cross-device app that includes information about your platform-specific apps.

跨设备应用使你能够:A cross-device app enables you to:

  • 使用 Microsoft Graph 中的 Project Rome 活动源 API。Use the Project Rome activity feed API in Microsoft Graph.
  • 使用适用于 Windows、Android 和/或 iOS 的 Project Rome SDK 读取和写入由一组特定于平台的应用程序发布的用户活动。Read and write user activities published by a group of platform-specific applications by using the Project Rome SDK for Windows, Android, and/or iOS.
  • 使用适用于 Android 或 iOS 的 Project Rome SDK 通过 Project Rome 中的设备中继功能定位应用。Target apps via the device relay capabilities in Project Rome by using the Project Rome SDK for Android or iOS.

使用活动源 API 跨设备从中断的位置继续Pick up where you left off across devices with the activity feed API

可以将跨设备应用配置为关联适用于 Windows、iOS、Android、Web 的应用,以便每个平台上的应用都可以读取和写入由组中任意应用发布的用户活动。You can configure a cross-device app to associate your apps for Windows, iOS, Android, and the web so that the app on each platform can read and write user activities that are published by any app in the group.

例如,在与朋友共进晚餐之前,用户在她的 PC 上撰写新闻稿。For example, a user is finishing up a press release on her PC at work before dinner with friends. 在餐厅,她收到来自老板的通知,需要尽快修改一个输入错误。At the restaurant, she gets a notification from her boss about a typo that needs to be fixed asap. 她在她的 Android 手机上打开应用并看到显示早期编辑的新闻稿的卡片。She opens the app on her Android phone and sees a card showing the press release she was editing earlier. 她点击该卡片将其打开,以便可以立即修改新闻稿并回到她的朋友身边。She taps the card to open it so she can fix the release immediately and get back to her friends.

此跨设备应用配置就绪后,毫不费力地跨设备和平台同步用户的活动源,以便可以构建帮助用户在任何应用平台上中断的位置继续执行重要任务的体验。With this cross-device app configuration in place, the user's activity feed is synchronized across devices and platforms effortlessly so you can build experiences that help users pick up important tasks where they left off from any app surface.

使用设备中继 API 在正确的时间选择正确的屏幕Choose the right screen at the right time with the device relay API

可以使用推送通知凭据为你的应用可用的每个平台配置跨设备应用,以便可以在使用应用的任何设备(无论何种平台)上将命令或通知传递给你。You can configure a cross-device app with push notification credentials for each of the platforms your app is available on so that a command or notification can be delivered to you on any device where you use the app, regardless of platform.

例如,用户在下班回家的公交车上观看视频。For example, a user is watching a video on the bus ride home from work. 当她回到家时,她点击应用在她的 Xbox One 上启动视频,则可以继续在大屏幕上观看。When she arrives home, she taps the app to launch the video on her Xbox One so she can continue watching on the big screen.

将你的应用可用的每个平台的推送通知凭据与跨设备应用关联时,用户的应用可以跨设备发送命令,以便可以构建跨多个屏幕的体验或实时将工作流从一个设备转换到另一个设备的体验。When you associate push notification credentials for each of the platforms where your app is available with your cross-device app, the user's app can send commands across devices, so you can build experiences that cross multiple screens or transition a workflow from one device to another in real time.

为跨设备应用配置选择正确的托管方法Select the right hosting method for your cross-device app configuration

可以将跨设备应用配置作为域上的 JSON 文件或作为可通过 Windows 开发人员中心配置的配置文件进行托管。You can host your cross-device app configuration either as a JSON file on your domain or as a profile configurable via the Windows Dev Center. 根据要在应用中启用的 Project Rome 功能选择托管选项。Choose a hosting option based on the Project Rome capabilities you want to enable in your apps.

可以使用 Windows 开发人员中心中管理的跨设备应用访问所有 Project Rome 功能。You can access all Project Rome capabilities using a cross-device app managed in the Windows Dev Center. Windows 开发人员中心还提供管理任何跨设备应用配置更改的最佳方式。The Windows Dev Center also offers the best way to manage any cross-device app configuration changes. 可以更安全地将更新保存到现有配置文件,直到已准备好将更改发布到生产中。You can save updates to an existing profile more securely until you're ready to publish changes to production. 将更改发布到开发人员中心中的现有跨设备应用时,新配置文件将在大约 1 小时后生效。When you publish changes to an existing cross-device app in the Dev Center, the new profile will be effective after approximately one hour.

外部托管的 JSON 文件(有限)Externally hosted JSON file (limited)

可以通过作为外部托管的 JSON 文件管理的跨设备应用在所有受支持的平台上使用以下 Project Rome 功能:You can use the following Project Rome capabilities on all supported platforms using a cross-device app managed as an externally hosted JSON file:

  • 使用活动源 API 读取和写入所有平台中的用户活动Read and write user activities from all platforms using the activity feed API
  • 使用 Project Rome SDK 写入所有平台(Windows、iOS、Android、Web)中的用户活动。Write user activities from all platforms (Windows, iOS, Android, web) using the Project Rome SDKs.

如果访问这些功能,则可以将跨设备应用配置作为域上的 JSON 文件进行外部托管。If you only access these capabilities, you can host your cross-device app configuration externally on your domain as a JSON file.

使用 Windows 开发人员中心配置跨设备应用Configure a cross-device app using the Windows Dev Center

跨设备应用 ID 表示为你拥有的域。A cross-device app ID is represented as a domain that you own. 域指向作为域上托管的 JSON 文件存储或可通过 Windows 开发人员中心配置的特定于平台的应用 ID 的映射。The domain points to a mapping of your platform-specific app IDs stored either as a JSON file hosted on your domain or configurable via the Windows Dev Center. 确定将用来表示跨设备应用 ID 的域后,将需要收集信息来配置关联的配置文件。After you identify the domain you'll use to represent your cross-device app ID, you'll need to collect information to configure the associated profile.

步骤 1:为跨设备应用 ID 选择安全域并启用域验证Step 1: Select a secure domain for your cross-device app ID and enable domain verification

用作跨设备应用 ID 的域必须为顶级域或子域,且必须通过 TLS 保护。The domain used as your cross-device app ID must either be a top-level domain or a subdomain and must be protected via TLS. 例如:https://contoso.com 或 https://myapp.contoso.com,但不是 https://myapp.contoso.com/somepath。For example: https://contoso.com or https://myapp.contoso.com, but NOT https://myapp.contoso.com/somepath. 每个跨设备应用必须具有唯一域(或子域)。You must have a unique domain (or subdomain) per cross-device app. 但是,根据要支持的跨平台行为决定将哪些应用与单个跨设备应用关联。However, you decide which apps to associate with a single cross-device app based on the cross-platform behavior you want to support.

例如,具有一套游戏应用的应用开发人员可能会对每个游戏应用使用单独的子域,以确保每个应用仅在跨设备和平台读取数据时可以继续执行的用户活动中订阅。For example, an app developer with a suite of game apps might use a separate subdomain for each of these to ensure that each app is only subscribed to the user activities it can resume when reading data across devices and platforms. 另一方面,具有一套旨在协同工作的效率类应用的应用开发人员可能会对所有这些效率类应用使用单个域,以便应用能够跨设备启动该套件的成员。On the other hand, an app developer with a suite of productivity apps designed to work together might use a single domain for all of these so that any app is able to launch a member of the suite across devices.

通过 Windows 开发人员中心声明域所有权Assert domain ownership with the Windows Dev Center

使用 Windows 开发人员中心管理跨设备应用配置时,表示跨设备应用 ID 的域会作为跨设备应用配置文件的一部分进行存储,因此 Microsoft 可以确认你是域所有者。When using the Windows Dev Center to manage your cross-device app configuration, the domain representing your cross-device app ID is stored as part of your cross-device app profile so Microsoft can verify that you are the domain owner. 要完成跨设备应用配置的发布,必须验证你的域所有权,因此最好先处理此事。Your domain ownership must be verified in order to finish publishing your cross-device app configuration, so it's a good idea to tackle this first.如果尚未验证域,则可以保存跨设备应用详细信息并在完成此步骤后重新运行验证,以便可以发布跨设备应用。 If your domain is not yet verified, you can save your cross-device app details and rerun the verification after you complete this step so you can publish your cross-device app.

若要声明跨设备应用的域所有权,将需要为域添加具有在开发人员中心中为你提供的唯一值的 DNS TXT 条目。To assert your domain ownership for your cross-device app, you'll need to add a DNS TXT entry for your domain with a unique value provided to you in the Dev Center. 每个跨设备应用的此值都是唯一的。This value is unique per cross-device app. 若要查找应用的唯一值,请登录到 Windows 开发人员中心,然后从左侧菜单中选择“跨设备体验”**** 以开始配置新的跨设备应用。To find the unique value for your app, sign in to the Windows Dev Center and choose Cross-device experiences from the left menu to start configuring a new cross-device app. 为新的跨设备应用提供名称后,从子菜单中选择“验证跨设备应用域”****。After you give your new cross-device app a name, select Verify your cross-device app domain from the submenu. 此页面将显示包含唯一值  inline 的说明(例如,MS=95ff4557-813f-45a5-b2f6-1f94170b979f)。This page will display instructions with a unique value inline (for example, MS=95ff4557-813f-45a5-b2f6-1f94170b979f). 确保复制整个值,包括“MS=”。Make sure to copy the entire value including 'MS='.

步骤 2:收集特定于平台的应用程序 IDStep 2: Collect your platform-specific application IDs

为将使用 Project Rome API 的每个应用程序和平台收集特定于平台的应用程序 ID。Collect the platform-specific application IDs for each application and platform that will use Project Rome APIs.

将需要收集每个特定于平台的应用程序 ID,才能将其与跨设备应用标识关联。You'll need to collect each of the platform-specific application IDs in order to associate them with your cross-device app identity. 使用 Windows 开发人员中心,将能够从与开发人员帐户关联的通用 Windows 平台应用中进行选择,但需要手动提供任何 win32、iOS 或 Android 应用的应用程序 ID 并标识任何关联 Web 应用的主 URL。Using the Windows Dev Center, you'll be able to select from Universal Windows Platform apps associated with your developer account, but you'll need to manually provide application IDs for any of your win32, iOS, or Android apps and identify the primary URL for any associated web apps. 每个平台最多可以关联 10 个 ID。You can associate up to 10 IDs per platform.

若要查找 ID,请执行以下操作:To find the IDs:

步骤 3:配置对 Microsoft 帐户或 Azure AD 的支持Step 3: Configure support for Microsoft account or Azure AD

若要启用跨设备体验,应用用户必须使用 Microsoft 帐户或  Azure Active Directory  (Azure AD) 帐户进行登录。To enable cross-device experiences, your app users must sign in with either a Microsoft account or an Azure Active Directory (Azure AD) account. 你将提供应用 ID/客户端 ID 以在跨设备应用配置过程中支持身份验证,从而启用跨平台支持。You will provide the app ID/client IDs to support authentication as part of your cross-device app configuration to enable cross-platform support. 最多可提供 10 个实例。You can provide up to 10 instances.

可以通过使用你的开发人员帐户登录到应用程序注册门户来查找现有应用 ID/客户端 ID 或预配新应用 ID/客户端 ID。You can find your existing app ID/client IDs or provision new ones by signing in to the Application registration portal with your developer account. 登录到门户后,可以查看任何应用的应用 ID/客户端 ID。When you sign in to the portal, you can view the App ID/client ID for any of your apps. 同时支持 Live SDK(十六进制值)和聚合应用 ID (GUID)。Both Live SDK (hex values) and converged app IDs (GUIDs) are supported.

如果正在构建将支持 Azure AD 用户的应用程序,且不使用通过应用程序注册门户颁发的聚合应用程序 ID,则将需要为 Azure 应用的应用程序 ID 提供 GUID。If you're building an application that will support Azure AD users, and you do not use a converged application ID issued through the Application registration portal, you will need to provide the GUID for the application ID of your Azure app. 若要查找租户的 GUID,请执行以下操作:To find the GUID for your tenant:

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 选择“Azure Active Directory”****。Select Azure Active Directory.
  3. 在“管理”**** 下,选择“应用注册”****。Under Manage, select App registrations.
  4. 从列表中选择你的应用并查看“概要”**** 下列出的应用程序 ID (GUID)。Select your app from the list and view your Application ID (GUID) listed under Essentials.

步骤 4:配置对跨平台推送通知的支持(可选)Step 4: Configure support for cross-platform push notifications (optional)

如果已选择在 Windows 开发人员中心中配置跨设备应用,则可以通过为 Android 和 iOS 推送消息平台提供用于 API 的凭据来启用对跨平台推送通知的支持。If you've opted to configure your cross-device app in the Windows Dev Center, you can enable support for cross-platform push notifications by providing the credentials you use with the APIs for Android and iOS push messaging platforms. 如果使用适用于 iOS 和 Android 的 Project Rome SDK 且希望完成的不止是发布用户活动,则需要执行以上步骤。These are required if you're using the Project Rome SDKs for iOS and Android and you want to do more than publish user activities. 如果仅使用适用于 Microsoft Graph 的 Project Rome API,则无需执行此步骤。If you're using Project Rome APIs for Microsoft Graph only, you don't need to perform this step. 每个平台最多可以关联 10 组凭据。You can associate up to 10 sets of credentials per platform.

重要说明: 不要将推送通知凭据存储在外部托管的 JSON 文件中。Important: Do not store push notification credentials in an externally hosted JSON file.

若要查找 ID,请执行以下操作:To find the IDs:

注意: 如果通过 Firebase 使用 Android 凭据将通知推送到 iOS 设备,将需要在跨设备应用配置过程中提供 APNs 凭据。Note: If you're using Firebase to push notifications to iOS devices using Android credentials, you'll need to provide your APNs credentials as part of your cross-device app configuration.

使用外部托管的 JSON 文件配置跨设备应用Configure a cross-device app using an externally hosted JSON file

跨设备应用 ID 表示为你拥有的域。A cross-device app ID is represented as a domain that you own. 域指向作为域上托管的 JSON 文件存储或可通过 Windows 开发人员中心配置的特定于平台的应用 ID 的映射。The domain points to a mapping of your platform-specific app IDs stored either as a JSON file hosted on your domain or configurable via the Windows Dev Center. 确定将用来表示跨设备应用 ID 的域后,将需要收集信息来配置关联的配置文件。After you identify the domain you'll use to represent your cross-device app ID, you'll need to collect information to configure the associated profile.

步骤 1:为跨设备应用 ID 选择安全域Step 1: Select a secure domain for your cross-device app ID

跨设备应用 ID 表示为你拥有的域。A cross-device app ID is represented as a domain that you own. 该域必须为顶级域或子域,且必须通过 TLS 保护。This must either be a top-level domain or a subdomain, and must be protected via TLS. 例如:https://contoso.com 或 https://myapp.contoso.com,但不是 https://myapp.contoso.com/somepath。For example: https://contoso.com or https://myapp.contoso.com but NOT https://myapp.contoso.com/somepath. 每个跨设备应用必须具有唯一域(或子域)。You must have a unique domain (or subdomain) per cross-device app. 但是,根据要支持的跨平台行为决定将哪些应用与单个跨设备应用关联。However, you decide which apps to associate with a single cross-device app based on the cross-platform behavior you want to support.

例如,具有一套游戏应用的应用开发人员可能会对每个游戏应用使用单独的子域,以确保每个应用仅在跨设备和平台读取数据时可以继续执行的用户活动中订阅。For example, an app developer with a suite of game apps might use a separate subdomain for each to ensure that each app is only subscribed to the user activities it can resume when reading data across devices and platforms. 具有一套旨在协同工作的效率类应用的应用开发人员可能会对所有这些效率类应用使用单个域,以便应用能够跨设备启动该套件的成员。An app developer with a suite of productivity apps designed to work together might use a single domain for all of these so that any app is able to launch a member of the suite across devices.

使用外部托管的 JSON 文件声明域所有权Assert domain ownership with an externally hosted JSON file

如果使用外部托管的 JSON 文件管理跨设备应用,则通过将 Microsoft 帐户或 Azure AD 应用 ID 包含在 cross-platform-app-identifiers 文件中来声明域所有权。If you're using an externally hosted JSON file to manage your cross-device app, you assert domain ownership by including your Microsoft account or Azure AD app IDs in the cross-platform-app-identifiers file. 如果使用活动源 API 创建用户活动,则在发布过程中将验证你的域所有权。Your domain ownership will be verified as part of the publish process when you use the activity feed API to create user activities.

系统将缓存 JSON 文件的内容以避免在域上生成频繁请求。The system will cache the contents of the JSON file to avoid generating frequent requests on your domain. 如果已配置,该服务将在评估何时刷新缓存时考虑 HTTP 缓存标头。If configured, the service will respect HTTP cache headers when evaluating when to refresh the cache. 如果未配置,该服务将每 24 小时刷新一次。If not configured, the service will refresh every 24 hours.

步骤 2:收集特定于平台的应用程序 ID 并构造 JSON 文件Step 2: Collect your platform-specific application IDs and construct your JSON file

为将使用活动源和/或设备中继 API 的每个应用程序和平台收集特定于平台的应用程序 ID。Collect the platform-specific application IDs for each application and platform that will use the activity feed and/or device relay API.

将需要收集每个特定于平台的应用程序 ID,才能将其与跨设备应用标识关联。You'll need to collect each of the platform-specific application IDs in order to associate them with your cross-device app identity. 使用外部托管的 JSON 文件,将需要收集每个特定于平台的应用的应用 ID,以配置为跨设备应用的一部分并将其组合为指定格式。Using an externally hosted JSON file, you'll need to collect app IDs for each of the platform-specific apps to configure as part of your cross-device app and assemble them into the specified format. 每个平台最多可以关联 10 个 ID。You can associate up to 10 IDs per platform.

构造 cross-platform-app-identifiers 文件Constructing your cross-platform-app-identifiers file

JSON 文件本身必须命名为 cross-platform-app-identifiers 并托管在 HTTPS 域的根目录中。The JSON file itself must be named cross-platform-app-identifiers and hosted at root of your HTTPS domain. 该文件的内容是应用程序的支持平台与这些平台上的应用程序 ID 之间的映射的 JSON 数组。The contents of the file are a JSON array of mappings between your application's supported platforms and the application IDs on those platforms. 构造该文件时,包括将使用 Project Rome API 的每个应用程序和平台的 JSON 对象。When constructing the file, include a JSON object for each application and platform that will use Project Rome APIs.   该文件将允许多个 JSON 对象具有相同平台标识符。The file will allow for multiple JSON objects with the same platform identifier. 例如,iPhone 应用和 iPad 应用应作为单独的 JSON 对象列出,每个应用的平台值均为 iOS。For example, an iPhone app and an iPad app should be listed as separate JSON objects, each with a platform value of iOS. 以下示例中显示了 Web 平台标识符。The web platform identifier is shown in the following example.   不需要包括所有平台的 JSON 对象。You don't need to include a JSON object for all platforms. 仅包括应用程序使用 Project Rome API 的平台的 JSON 对象。Only include JSON objects for platforms where your application is using Project Rome APIs.例如,如果没有适用于 Android 平台的应用客户端,则不需要在 Android 文件中进行输入。 For example, if you don't have an app client for the Android platform, you don’t need an entry in the file for Android.   以下示例包含当前接受的所有有效平台标识符。The following example includes all the valid platform identifiers currently accepted. 将删除包含无效平台值的 JSON 对象。JSON objects that include an invalid platform value will be stripped out. 

{"platform":"windows_universal", "application":"Microsoft.Contoso_8wekyb3d8bbwe"},
{"platform":"windows_win32", "application":"DefaultBrowser_NOPUBLISHERID!Microsoft.Contoso.Default"},
{"platform":"android","application":"com.example.myapp"},
{"platform":"ios", "application":"com.example.myapp"},
{"platform":"web", "application":"https://contoso.com"},
{"platform":"web", "application":"https://chat.contoso.com"},
{"platform":"msa", "application":"00000000603E0BF"},
{"platform":"msa", "application":"48932b46-98b1-4020-9be4-cc7a65643c9e"},
]

若要查找 ID,请执行以下操作:To find the IDs:

步骤 3:配置对 Microsoft 帐户或 Azure AD 的支持Step 3: Configure support for Microsoft account or Azure AD

若要启用跨设备体验,应用用户必须使用 Microsoft 帐户或 Azure AD 帐户进行登录。To enable cross-device experiences, your app users must sign in with either a Microsoft account or an Azure AD account. 你将提供应用 ID/客户端 ID 以在跨设备应用配置过程中支持身份验证,从而启用跨平台支持。You will provide the app ID/client IDs to support authentication as part of your cross-device app configuration to enable cross-platform support. 最多可提供 10 个实例。You can provide up to 10 instances.

{"platform":"windows_universal", "application":"Microsoft.Contoso_8wekyb3d8bbwe"},
{"platform":"windows_win32", "application":"DefaultBrowser_NOPUBLISHERID!Microsoft.Contoso.Default"},
{"platform":"android","application":"com.example.myapp"},
{"platform":"ios", "application":"com.example.myapp"},
{"platform":"web", "application":"https://contoso.com"},
{"platform":"web", "application":"https://chat.contoso.com"},
{"platform":"msa", "application":"00000000603E0BF"},
{"platform":"msa", "application":"48932b46-98b1-4020-9be4-cc7a65643c9e"},
]

可以通过使用你的开发人员帐户登录到 应用程序注册门户来查找现有应用 ID/客户端 ID 或预配新应用 ID/客户端 ID。You can find your existing app ID/client IDs or provision new ones by signing in to the Application Registration Portal with your developer account. 登录后,可以查看任何应用的应用 ID/客户端 ID。When you sign in, you can view the App ID/client ID for any of your apps. 同时支持 Live SDK(十六进制值)和聚合应用 ID (GUID)。Both Live SDK (hex values) and converged app IDs (GUIDs) are supported. 添加用于启用对 Microsoft 帐户或 Azure AD 的支持的 ID 时使用平台类型“msa”,如前一个示例中所示。Use the platform type "msa" when you add the IDs used to enable support for a Microsoft account or Azure AD, as shown in the previous example.

注意: 如果正在构建支持 Azure AD 用户的应用程序,且不使用通过 应用程序注册门户颁发的聚合应用程序 ID,则将需要为 Azure 应用的应用程序 ID 提供 GUID。Note: If you're building an application that supports Azure AD users, and you do not use a converged application ID issued through the Application Registration Portal, you will need to provide the GUID for the application ID of your Azure app. 此类型的 ID 还应配置为平台类型“msa”。This type of ID should also be configured as platform type "msa".

若要在 Azure 门户中查找租户的 GUID,请执行以下操作:To find the GUID in the Azure Portal for your tenant:

  1. 登录到 Azure 门户Sign in to the Azure portal.
  2. 选择“Azure Active Directory”****。Select Azure Active Directory.
  3. 在“管理”**** 下,选择“应用注册”****。Under Manage, select App registrations.
  4. 从列表中选择你的应用。Select your app from the list. 可以在“概要”**** 下查看应用程序 ID (GUID)。You can view your application ID (GUID) under Essentials.

对 cross-platform-app-identifiers 文件进行编码Encoding the cross-platform-app-identifiers file

如果未看到活动在正确的本机应用程序中跨平台恢复,或无法读取由组中的所有成员发布的活动,则可能无法正确分析 JSON 文件。If you're not seeing activities resume in the correct native applications across platforms, or you're unable to read activities published by all members in the group, your JSON file might not be getting parsed appropriately. 输出此文件时,请确保使用“Unicode (UTF-8 无签名) - 代码页 65001”编码保存 cross-platform-app-identifiers 文件。When outputting this file, make sure you're saving the cross-platform-app-identifiers file with "Unicode (UTF-8 without signature) - Codepage 65001" encoding.

更新 cross-platform-app-identifiers JSON 文件Updating the cross-platform-app-identifiers JSON file

系统将缓存 JSON 文件的内容以避免在域上生成频繁请求。The system will cache the contents of the JSON file to avoid generating frequent requests on your domain. 如果已配置,该服务将在评估何时刷新缓存时考虑 HTTP 缓存标头。If configured, the service will respect HTTP cache headers when evaluating when to refresh the cache. 如果未配置,该服务将每 24 小时刷新一次。If not configured, the service will refresh every 24 hours.

配置应用客户端Configure your app client

如果使用适用于 Windows、iOS 或 Android 的客户端 API,将需要确保使用表示跨设备应用标识的主机值(例如,contoso.com)配置应用客户端。If you're using the client-side APIs for Windows, iOS, or Android, you'll need to make sure your app client is configured with the host value that represents your cross-device app identity (for example, contoso.com).

Microsoft Graph 应用Microsoft Graph apps

如果你的应用使用 Microsoft Graph 中的活动源 API,则必须在 activitySourceHost 属性中提供主机值。If you have an app using the activity feed API in Microsoft Graph, your host value must be supplied in the activitySourceHost property. 有关详细信息,请参阅活动资源类型For details, see activity resource type.

通用 Windows 应用Universal Windows apps

如果具有 Windows 应用,将需要在发布数据之前在应用清单中配置主机值。If you have a Windows app, you will need to configure the host value in your app manifest before publishing data. 有关详细信息,请参阅 uap5:UserActivityFor details, see uap5:UserActivity.

维护跨设备应用配置Maintaining your cross-device app configuration

发布将生成用户活动的新应用程序时,请务必提前使用新配置值更新跨设备应用,以便发布的任何新活动与跨设备应用正确关联。When releasing a new application that will generate user activities, it's important to update the cross-device app with the new configuration values in advance so that any new activities published are correctly associated with the cross-device app. 不会自动更新与在配置发生更改之前已发布的用户活动关联的跨设备应用配置。The cross-device app configuration associated with user activities that have been published prior to a change in configuration will not be updated automatically. 使用旧配置对任何活动执行的更新操作将更新为文件上的最新版本。However, an update operation performed on any activity with an old configuration will be updated to the most recent version on file.

疑难解答Troubleshooting

下面是活动源 API 可能会出现的一些常见问题。The following are some common issues that can occur with the activity feed API.

无法读取和写入跨设备应用配置中的所有应用的活动Activities are not available to read and write for all apps in the cross-device app configuration

活动源 API 异步引入跨设备应用配置,因此在发布用户活动时配置错误可能不会很明显。The activity feed API ingests the cross-device app configuration asynchronously, so configuration errors might not be readily apparent when publishing user activities. 如果该服务由于 TLS 或格式错误而无法引入 JSON 文件,则已发布的任何活动将仅归于发布活动的应用 ID。In the event the service fails to ingest the JSON file, either due to TLS or formatting error, any activities that have been published will be attributed to the app ID that posted the activity, only. 如果通过 Microsoft Graph 发布活动,则将使用 Microsoft 帐户应用 ID 授权对 Microsoft Graph 的请求。In the case of activities published via Microsoft Graph, this is the Microsoft account app ID used to authorize requests to Microsoft Graph. 如果通过客户端 API 发布活动,activity.applicationId 将仅记录发布活动的特定于平台的应用的 ID。In the case of activities published via client-side APIs, the activity.applicationId will record the ID of the platform-specific app that posted the activity, only. 这将防止对跨设备应用配置中标识的任何其他特定于平台的应用中的活动执行读取和写入操作。This will prevent read and write operations on activities from any other platform-specific apps identified in the cross-device app configuration.

平台不会在 Android 或 iOS 上进行初始化Platform will not initialize on Android or iOS

适用于 Android 或 iOS 的设备中继 API 需要跨设备应用配置,才能实例化与 Android 或 iOS 应用的连接。The device relay API for Android or iOS requires the cross-device app configuration in order to instantiate connections to the Android or iOS app. 如果平台无法成功初始化,请确保已正确标识Microsoft 帐户应用 ID 和推送通知凭据,它们用于在 Windows 开发人员中心中配置跨设备并使用标识跨设备应用的域配置客户端应用的主机值。In the event that the platform fails to initialize successfully, make sure you have correctly identified the Microsoft account app IDs and push notification credentials used to configure your cross-device app in the Windows Dev Center, and configure your client apps' host value with the domain that identifies your cross-device app.