您的行動應用程式可以以程式設計方式，將最近的網站 URL 和文件連結共用到已設定手機連結 的 Windows 電腦。 此工作持續性功能可在整合了「連結到 Windows」體驗的 Android 裝置上使用。
此功能僅適用於支援手機連結體驗的裝置。
本文件將介紹如何將您的應用程式與手機連結工作持續性 API 整合，包括案例需求、介面區和限制存取功能 (LAF) 核准。
深入了解手機連結：將您的智慧型手機同步到您的 Windows 電腦。
案例需求
工作持續性 API 可讓您將 Android 應用程式的內容同步到已設定手機連結的 Windows 電腦。 必須符合下列條件，才能授與此 API 的存取權：
- 請同步 Windows 電腦可以存取的有效 URL 的 Web URL
- 請同步 Windows 電腦可以存取的雲端文件連結
- 請將本機文件連結同步到 Windows 電腦，必須可以透過您的應用程式在行動裝置上存取該連結
- 每分鐘請勿同步處理超過 60 次
- 如果使用者未與您的應用程式體驗互動，請勿同步處理內容
手機連結介面
手機連結會在 [應用程式] 節點的 [最近使用] 和 [最近使用的網站] 和 [通知] 飛出視窗中顯示同步處理的內容。
限制存取功能 (LAF) 核准
手機連結工作持續性是一種限制存取功能 (LAF)。 若要取得此 API 的存取權，您必須取得 Microsoft 的核准，才能與 Android 行動裝置上預先載入的「連結至 Windows」套件交互操作。
若要要求存取權，請傳送電子郵件 wincrossdeviceapi@microsoft.com 並附上下列資訊。
- 使用者體驗的描述
- 使用者原生存取 Web 或文件之應用程式的螢幕擷取畫面
- 應用程式的 PackageId
- 您應用程式的 Google Play 商店連結
如果已核准要求，您將會收到如何解除鎖定功能的指示。 核准將基於您的溝通，前提是您的案例需求滿足上述案例要求。
資料處理
透過使用手機連結工作持續性 API，Microsoft 會根據 Microsoft 服務合約和 Microsoft 隱私權聲明來處理和傳輸您的資料。 傳送至使用者連結裝置的資料，可透過 Microsoft 的雲端服務進行處理，以確保裝置之間的可靠資料傳輸。 最終使用者控制的 Microsoft 雲端服務，不會保留此 API 處理的資料。
您將整合到套件中的跨裝置 SDK，可確保提供給 API 的資料僅由受信任的 Microsoft 套件處理。
如何將您的應用程式與手機連結工作持續性 API 整合
若要整合 Android 行動應用程式與手機連結工作持續性 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>
傳送應用程式內容的程式碼範例
新增資訊清單宣告之後，合作夥伴應用程式就可以傳送其應用程式內容，如下列程式碼範例所示。
此範例示範如何搭配 Java 使用 IAppContextEventHandler 介面。
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」傳送到支援特定類型的應用程式內容功能的每個套件。
| 意圖欄位 | 機碼 | 值 |
|---|---|---|
| 動作 | N/A |
com.microsoft.crossdevice.appcontextrequest 修復了與 Windows 的連結。 要求者將會是 com.microsoft.appmanager |
| 額外項目 (配套) | version |
2.0 (版本 [minor].[major]) |
| 額外項目 (配套) | 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。 如果提供更多，則會將其忽略。 |
合作夥伴應用程式可以呼叫 addBrowserContext 方法來新增瀏覽器記錄。
新增瀏覽器記錄時，應該提供下列值：
| 機碼 | 值 |
|---|---|
browserWebUri |
將在電腦瀏覽器中開啟的 Web URI。 |
| (http: 或 https:) | |
title |
網頁的標題。 |
timestamp |
網頁第一次開啟或上次重新整理的時間戳記。 |
favIcon[選填] |
網頁的 favicon，以位元組為單位，一般應該很小。 |
GitHub 上的 Windows 跨裝置存放庫
在 GitHub 上的 Windows 跨裝置存放庫中尋找有關將 Windows 跨裝置 SDK 整合到專案中的資訊。
手機連結常見問題
如需常見問題的清單，請參閱手機連結常見問題。
