使用英语阅读

通过


借助 Phone Link 实现跨设备的任务连续性

移动应用程序可通过编程方式共享已设置 Phone Link 的 Windows 电脑的近期网站 URL 和文档链接。 此任务连续性功能可在与“连接至 Windows”体验相集成的 Android 设备上使用。

此功能仅适用于可实现 Phone Link 体验的受支持设备

本文档介绍如何将应用与 Phone Link 任务连续性 API 集成,其中包括场景要求、外围应用和受限访问功能 (LAF) 审批。

详细了解 Phone Link:将智能手机同步到 Windows 计算机

场景要求

借助任务连续性 API,可将 Android 应用的内容同步到已设置 Phone Link 的 Windows 电脑。 必须满足以下条件才能授予对此 API 的访问权限:

  • 务必同步 Windows 电脑可访问的有效 Web URL
  • 务必同步 Windows 电脑可访问的云文档链接
  • 务必同步必须能通过应用程序在移动设备上访问的 Windows 电脑的本地文档链接
  • 请勿每分钟同步 60 次以上
  • 如果用户未参与应用体验,则请勿同步内容

Phone Link 可在“最近使用”和“最近访问的网站”下的“应用”节点以及通知浮出控件中显示已同步的内容。

最近使用的应用和网站的手机连接屏幕截图

受限访问功能 (LAF) 审批

Phone Link 任务连续性属于受限访问功能 (LAF)。 若要获取对此 API 的访问权限,则需获得 Microsoft 的批准,以便与 Android 移动设备上预加载的“链接至 Windows”包进行互操作。

若要请求访问权限,请向 wincrossdeviceapi@microsoft.com 发送电子邮件并附带下列信息。

  • 用户体验说明
  • 用户在本地访问 Web 或文档的应用程序的屏幕截图
  • 应用程序的 PackageId
  • 应用程序的 Google Play 商店链接

如果请求获得批准,则会收到有关如何解锁该功能的说明。 审批将以你的通信信息作为依据,但前提是你的场景能满足上文概述的场景要求

数据处理

通过使用 Phone Link 任务连续性 API,Microsoft 将依据 Microsoft 服务协议Microsoft 隐私声明来处理和传输你的数据。 传输到用户的已链接设备的数据可能会通过 Microsoft 的云服务进行处理,从而确保各设备之间的可靠数据传输。 此 API 所处理的数据不会由受最终用户控制约束的 Microsoft 的云服务来保留。

在包中集成的跨设备 SDK 可确保提供给此 API 的数据仅由受信任的 Microsoft 包处理。

若要将 Android 移动应用与 Phone Link 任务连续性 API 集成,则需更新清单声明,然后发送应用上下文。 请参阅以下示例代码示例。

Android 应用清单声明

你的应用应向跨设备应用上下文提供程序注册广播接收器,从而加入此合同。 此注册应位于清单中,如下所示。

<?xml version="1.0" encoding="utf-8"?>   
<manifest xmlns:android="http://schemas.android.com/apk/res/android"   
    <!--   
        If the app targets API 30 or higher, be sure to use the <queries>   
        and add com.microsoft.appmanager to the included packages.   
    -->   
    <queries>   
        <package android:name="com.microsoft.appmanager" />   
    </queries>   
    <application …     
        <!-- … -->   
       <!--   
           This is the receiver declaration for receiving broadcasts from LTW.   
           It needs to be exported with meta-data as this is checked for    

           The package before we send the broadcast.   
       -->   
       <receiver   
           android:name="com.microsoft.crossdevicesdk.continuity.AppContextBroadcastReceiver"  
           android:enabled="true"   
           android:exported="true">   
           <intent-filter>   
               <action android:name="com.microsoft.crossdevice.appcontextrequest" />   
           </intent-filter>   
   
            <meta-data   
                android:name="com.microsoft.crossdevice.sampleProviderMetadataName"   
                android:value="true" />   
        </receiver>   
    </application>   
</manifest>

发送应用上下文的代码示例

添加清单声明后,合作伙伴应用可发送其应用上下文,如以下代码示例所示。

此示例演示如何使用将 IAppContextEventHandler 接口与 Java 搭配使用。

IAppContextEventHandler appContextEventHandler = new IAppContextEventHandler() {  
    @Override  
    public void onContextRequestReceived(ContextRequestInfo contextRequestInfo) {  
        Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.getType()));  
        //Not necessary to do following things in here, just  
        //make sure to send app context after receiving broadcast.  
        AppContext appContext = new AppContext();  
        //...  
        //set parameter  
        appContext.setType(ProtocolConstants.TYPE_APPLICATION_CONTEXT);  
        appContext.setCreateTime(System.currentTimeMillis());  
        appContext.setLastUpdatedTime(System.currentTimeMillis());  
        appContext.setTitle("New PowerPoint Presentation");  
        appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}");  
        //...  
        AppContextManager.INSTANCE.sendAppContext(getApplicationContext(),appContext);  
    }  
  
    @Override  
    public void onInvalidContextRequestReceived(@NonNull Throwable throwable) {  
        Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.getMessage()));  
    }  

    @Override   
    public void onSyncServiceDisconnected() {   
        Log.d(TAG, String.format("onSyncServiceDisconnected"));   
    }  
};  
AppContextManager.INSTANCE.setAppContextEventHandler(appContextEventHandler);

此示例演示如何使用对象表达式来实现面向 Kotlin 的 IAppContextEventHandler 接口。

val appContextEventHandler = object : IAppContextEventHandler { 
    override fun onContextRequestReceived(contextRequestInfo: ContextRequestInfo) { 
        Log.d(TAG, String.format("onContextRequestReceived, type:%s", contextRequestInfo.type)); 
        //Not necessary to do following things in here, just 
        //make sure to send app context after receiving broadcast. 
        var appContext = AppContext() 
        //... 
        //set parameter 
        appContext.type = ProtocolConstants.TYPE_APPLICATION_CONTEXT 
        appContext.createTime = System.currentTimeMillis() 
        appContext.lastUpdatedTime = System.currentTimeMillis() 
        appContext.setTitle("New PowerPoint Presentation") 
        appContext.setExtras("{\"DocInfo\":\"[{\"timestamp\":1672,\"DocTitle\":\"Book Sharing\",\"Index\":\"8\"}]\"}") 
        //... 
        AppContextManager.sendAppContext(applicationContext,appContext) 
    } 
 
    override fun onInvalidContextRequestReceived(throwable: Throwable) { 
        Log.e(TAG, String.format("onInvalidContextRequestReceived: " + throwable.message)) 
    } 
 
    override fun onSyncServiceDisconnected() { 
        Log.d(TAG, String.format("onSyncServiceDisconnected")) 
    } 
} 
AppContextManager.setAppContextEventHandler(appContextEventHandler)

协议说明

协议是一种简易广播;当“链接至 Windows”准备好获取应用上下文时,可将此广播从“链接至 Windows”发送到支持特定类型的应用上下文功能的每个包。

意向字段 密钥
操作 空值 com.microsoft.crossdevice.appcontextrequest 已修复 Windows 链接的问题。 请求者为 com.microsoft.appmanager
附加程序(捆绑包) version 2.0(版本 [次要].[主要])
附加程序(捆绑包) contentProviderUri content://com.microsoft.taskcontinuity/b695d1d8 为每个包唯一生成。
附加程序(捆绑包) requestedContextType 如果提供,则表示请求的应用上下文类型。 它是一个二进制标志,而目前有两种类型:应用程序上下文:0x01,浏览器历史记录上下文:0x02。

收到此广播后,SDK 将负责验证和处理该信息。 接收此广播的包应发送应用上下文以链接到 Windows。 发送应用上下文时,合作伙伴应用应提供以下值:

密钥 额外的信息
type [必需] 用于表示发送到 LTW 的应用上下文类型的二进制标志。 该值应与 requestedContextType 一致。
createTime [必需] 表示应用上下文创建时间的时间戳。
lastUpdatedTime [必需] 表示应用上下文的上次更新时间的时间戳。 每当更新应用上下文的任意字段时,均需记录更新时间。
teamId [可选] 用于标识应用所属的组织或组。
intentUri [可选] 用于指示哪个应用可继续处理从原始设备移交的应用上下文。
appId [可选] 该上下文所针对的应用程序包。 只有上下文服务提供程序才需使用此包。 请参阅 Java 文档。如果省略,则会使用调用响应提供程序的包。
title [可选] 此应用上下文的标题,例如文档名称或网页标题。
weblink [可选] 要在浏览器中进行加载以便继续处理应用上下文的网页的 URL。
preview [可选] 可表示应用上下文的预览图像的字节数。
extras [可选] 一个键值对对象,其中包含在继续处理设备上继续处理应用上下文所需的应用特定状态信息。 当应用上下文具有其唯一数据时,需提供。
LifeTime [可选] 应用上下文的生存期(以毫秒为单位)。 仅用于正在进行的场景;如果未设置,则默认值为 -1。

为实现与使用 X-Device SDK 1.0 的先前“浏览器连续性”功能的兼容,我们添加了另外两种方法。 使用此功能时应提供以下值:

意向字段 密钥
browserContextEmptyFlag [可选] 用于表示浏览器上下文是否为空的标志。 它仅适用于浏览器连续性功能。
browserHistory [可选] 浏览应用的历史记录上下文。 它仅适用于浏览器连续性功能。 目前建议最多提供 3 个 URI。 如果提供更多 URI,则会将其忽略。

合作伙伴应用可调用 addBrowserContext 方法来添加浏览器历史记录。 添加浏览器历史记录时应提供以下值:

密钥
browserWebUri 将在电脑上的浏览器中打开的 Web URI。
(http: 或 https:)
title 网页的标题。
timestamp 首次打开或上次刷新网页的时间戳。
favIcon [可选] 网页的网站图标(以字节为单位),且通常应较小。

GitHub 上的 Windows 跨设备存储库

GitHub 上的 Windows 跨设备存储库中查找有关将 Windows 跨设备 SDK 集成到项目中的信息。

有关常见问题解答的列表,请参阅 Phone Link 常见问题