共用方式為

繼續使用者活動，甚至是在各個裝置之間

  • 發行項

這個主題描述了如何幫助使用者在電腦上和跨裝置恢復在您應用程式中正在進行的工作。

注意

從 2021 年 7 月開始，透過其 Microsoft 帳戶 (MSA) 跨 Windows 裝置同步處理活動歷程記錄的使用者將無法再選擇在時間軸中上傳新活動。 他們仍然可以使用時間軸，並在其本機電腦上查看其活動歷程記錄 (最新應用程式、網站和檔案的相關資訊)。 AAD 連線的帳戶不會受到影響。

使用者活動和時間軸

我們每天的時間分散在多個裝置上。 我們可能會在公共汽車上使用手機，白天使用電腦，然後在晚上使用手機或平板電腦。 從 Windows 10 組建 1803 或更新版本開始，建立使用者活動會使該活動出現在 Windows 時間軸和 Cortana 的接續未完成的部分功能。 時間軸是豐富的工作檢視，利用使用者活動來顯示您一直在處理的內容時間檢視。 它也可以包含您在裝置上執行的工作。

Windows 時間軸影像

同樣地，將手機連結至 Windows 電腦可讓您繼續先前在 iOS 或 Android 裝置上執行的動作。

將 UserActivity 視為使用者在您的應用程式內所處理的特定項目。 例如，如果您使用 RSS 閱讀程式，UserActivity 可能是您正在閱讀的摘要。 如果您正在玩遊戲，UserActivity 可能是您正在玩的關卡。 如果您正在聆聽音樂應用程式，UserActivity 可能是您正在收聽的播放清單。 如果您正在處理文件，UserActivity 可能就是您上次處理文件時的進度，依此類推。 簡言之，UserActivity 代表您應用程式內的目的地，讓使用者能夠繼續他們正在執行的動作。

當您透過呼叫 UserActivity.CreateSession 與 UserActivity 互動時，系統會建立記錄記錄，指出該 UserActivity 的開始和結束時間。 當您隨著時間重新與 UserActivity 重新互動時，系統會為其記錄多筆記錄。

將使用者活動新增至應用程式

UserActivity 是 Windows 中使用者參與的單位。 它有三個部分：用來啟動活動所屬應用程式的 URI、描述活動的視覺效果和中繼資料。

  1. ActivationUri 用於以特定內容恢復應用程式。 通常，這種連結的形式為通訊協定處理常式，用於配置 (例如，“my-app://page2?action=edit”)，或者是 AppUriHandler (例如，http://contoso.com/page2?action=edit)。
  2. VisualElements 會公開類別，讓使用者以視覺化方式識別具有標題、描述或調適型卡片項目的活動。
  3. 最後，內容是您可以儲存活動中繼資料的位置，該活動可用來在特定內容下分組和擷取活動。 這通常採用 https://schema.org 資料的形式。

若要將 UserActivity 新增至您的應用程式：

  1. 當使用者的內容在應用程式內變更時產生 UserActivity 物件 (例如頁面導覽、新的遊戲關卡等)。
  2. 在 UserActivity 物件中填入必要欄位的最小集合：ActivityId、ActivationUri 和 UserActivity.VisualElements.DisplayText。
  3. 將自訂配置處理常式新增至您的應用程式，讓 UserActivity 可以重新啟用它。

UserActivity 可以整合至只有幾行程式碼的應用程式。 例如，假設在 MainPage 類別內 MainPage.xaml.cs 這個程式碼 (注意：假設 using Windows.ApplicationModel.UserActivities;)：

UserActivitySession _currentActivity;
private async Task GenerateActivityAsync()
{
    // Get the default UserActivityChannel and query it for our UserActivity. If the activity doesn't exist, one is created.
    UserActivityChannel channel = UserActivityChannel.GetDefault();
    UserActivity userActivity = await channel.GetOrCreateUserActivityAsync("MainPage");
 
    // Populate required properties
    userActivity.VisualElements.DisplayText = "Hello Activities";
    userActivity.ActivationUri = new Uri("my-app://page2?action=edit");
     
    //Save
    await userActivity.SaveAsync(); //save the new metadata
 
    // Dispose of any current UserActivitySession, and create a new one.
    _currentActivity?.Dispose();
    _currentActivity = userActivity.CreateSession();
}

上述 GenerateActivityAsync() 方法中的第一行會取得使用者的 UserActivityChannel。 這是此應用程式活動將發佈目標的摘要。 下一行會查詢名為 MainPage 的活動通道。

  • 您的應用程式應該以相同的識別碼命名活動，如此一來，每次使用者位於應用程式的特定位置時，都會產生相同的識別碼。 例如，如果您的應用程式是以頁面為基礎，請使用頁面的識別碼；如果以文件為基礎，請使用文件的名稱 (或名稱的雜湊)。
  • 如果在摘要中存在具有相同識別碼的活動，將會從頻道中返回該活動，其中 UserActivity.State會設定為 [已發佈]。 如果沒有具有該名稱的活動，且新的活動會以 UserActivity.State 設定為 New 傳回。
  • 活動的範圍會限定於您的應用程式。 您不需要擔心活動識別碼與其他應用程式中的識別碼衝突。

取得或建立 UserActivity 之後，請指定其他兩個必要欄位：[UserActivity.VisualElements.DisplayText] 和 [UserActivity.ActivationUri]。

接下來，呼叫 SaveAsync 儲存 UserActivity 中繼資料，最後再呼叫 CreateSession，以傳回 UserActivitySession。 UserActivitySession 是使用者實際與 UserActivity 互動時，可用來管理的物件。 例如，當使用者離開頁面時，我們應該在 UserActivitySession 上呼叫 Dispose()。 在上面的例子中，我們在呼叫 CreateSession() 之前也會在 _currentActivity，上呼叫 Dispose()。 這是因為我們在頁面建立 [_currentActivity] 成員欄位，而且我們想要在開始新的活動之前停止任何現有的活動 (注意：? 是 Null 條件運算子，它會在執行成員存取之前先測試 null)。

因為在此情況下，ActivationUri 是自訂配置，所以我們也需要在應用程式指令清單中註冊通訊協定。 這是在 Package.appmanifest XML 檔案中完成，或使用設計工具來完成。

若要使用設計工具進行變更，請按兩下專案中的 Package.appmanifest 檔案來啟動設計工具，選取 [宣告] 索引標籤並新增 [通訊協定] 定義。 目前唯一需要填寫的屬性是 Name。 它應該符合我們在上面指定的 URI，my-app。

現在，我們需要撰寫一些程式碼，告訴應用程式在通訊協定啟用時該怎麼做。 我們將覆寫 App.xaml.cs 中的 OnActivated 方法，將 URI 傳遞至主頁面，如下所示：

protected override void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.Protocol)
    {
        var uriArgs = e as ProtocolActivatedEventArgs;
        if (uriArgs != null)
        {
            if (uriArgs.Uri.Host == "page2")
            {
                // Navigate to the 2nd page of the  app
            }
        }
    }
    Window.Current.Activate();
}

此程式碼會偵測應用程式是否透過通訊協定啟用。 如果是，則會查看應用程式應該執行的動作，以繼續啟動它的工作。 作為簡單的應用程式，此應用程式繼續的唯一活動就是在應用程式出現時，將您放在次要頁面上。

使用調適型卡片來改善時間軸體驗

使用者活動會出現在 Cortana 和時間軸中。 當活動出現在時間軸時，我們會使用調適型卡片架構來顯示它們。 如果您未為每個活動提供調適型卡片，時間軸就會根據您的應用程式名稱和圖示、標題欄位和選擇性描述欄位，自動建立簡單的活動卡片。 以下是調適型卡片的範例承載及其產生的卡片。

調適型卡片]

調適型卡片承載 JSON 字串範例：

{ 
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", 
  "type": "AdaptiveCard", 
  "version": "1.0",
  "backgroundImage": "https://winblogs.azureedge.net/win/2017/11/eb5d872c743f8f54b957ff3f5ef3066b.jpg", 
  "body": [ 
    { 
      "type": "Container", 
      "items": [ 
        { 
          "type": "TextBlock", 
          "text": "Windows Blog", 
          "weight": "bolder", 
          "size": "large", 
          "wrap": true, 
          "maxLines": 3 
        }, 
        { 
          "type": "TextBlock", 
          "text": "Training Haiti’s radiologists: St. Louis doctor takes her teaching global", 
          "size": "default", 
          "wrap": true, 
          "maxLines": 3 
        } 
      ] 
    } 
  ]
}

將調適型卡片承載新增為 JSON 字串至 UserActivity，如下所示：

activity.VisualElements.Content = 
Windows.UI.Shell.AdaptiveCardBuilder.CreateAdaptiveCardFromJson(jsonCardText); // where jsonCardText is a JSON string that represents the card

跨平台和服務對服務整合

如果您的應用程式執行跨平台 (例如在 Android 和 iOS 上)，或維護雲端中的使用者狀態，您可以透過 Microsoft Graph 發佈 UserActivities。 一旦您的應用程式或服務使用 Microsoft 帳戶進行驗證，只需要兩個簡單的 REST 呼叫，即可產生 Activity 與 History 物件，其資料與上述資料相同。

摘要

您可以使用 UserActivity API 讓您的應用程式出現在時間軸和 Cortana 中。

金鑰 API