使用者活動最佳做法User Activities best practices

本指南概述建立和更新使用者活動的建議作法。This guide outlines the recommended practices for creating and updating User Activities. 如需 Windows 上使用者活動功能的總覽,請參閱 繼續進行使用者活動,即使是跨裝置也是一樣。For an overview of the User Activities feature on Windows, see Continue user activity, even across devices. 或者,請參閱 Project 羅馬的「 使用者活動」一節 ,以瞭解其他開發平臺上的活動。Or, see the User Activities section of Project Rome for the implementations of Activities on other development platforms.

建立或更新使用者活動的時機When to create or update User Activities

由於每個應用程式都不同,因此每個開發人員都能判斷將應用程式中的動作對應至使用者活動的最佳方式。Because every app is different, it's up to each developer to determine the best way to map actions within the app to User Activities. 您的使用者活動將會展示在 Cortana 和時間軸中,其著重于提升使用者的生產力和效率,方法是協助他們回頭查看過去所造訪的內容。Your User Activities will be showcased in Cortana and Timeline, which are focused on increasing users' productivity and efficiency by helping them get back to content they visited in the past.

一般指導方針General guidelines

  • 為一組相關的使用者動作記錄單一活動。Record a single activity for a group of related user actions. 這與音樂播放清單或電視節目特別相關:單一活動可以定期更新,以反映使用者的進度。This is especially relevant for music playlists or TV Shows: a single Activity can be updated at regular intervals to reflect the user's progress. 在此情況下,您將會有單一使用者活動,其中包含多個記錄專案,代表在多天或數周的參與時間。In this case, you will have a single User Activity with multiple History Items representing periods of engagement across multiple days or weeks. 這同樣適用于以檔為基礎的活動,使用者在您的應用程式中進行逐步進度。The same applies to document-based activities on which the user makes gradual progress within your app.
  • 在雲端中儲存使用者資料。Store user data in the cloud. 如果您想要支援跨裝置活動,您必須確定重新參與此活動所需的內容會儲存至雲端位置。If you want to support cross-device Activities, you'll need to make sure the content required to re-engage this Activity is stored to a cloud location. 裝置特定活動會顯示在建立活動的裝置上,但可能不會出現在其他裝置上的時間軸上。Device-specific Activities will appear on Timeline on the device where the activity was created but may not appear on other devices.
  • 請勿針對使用者不需要繼續的動作建立活動。Do not create Activities for actions that users will not need to resume. 如果您的應用程式用來完成不會保存狀態的簡單一次性作業,您可能不需要建立使用者活動。If your application is used to complete simple, one-time operations that do not persist status, you probably do not need to create a User Activity.
  • 請勿為其他使用者所完成的動作建立活動。Do not create Activities for actions completed by other users. 如果外部帳戶在您的應用程式中傳送訊息或傳送給使用者 @-mentions ,您就不應該為此建立活動。If an external account sends the user a message or @-mentions them within your app, you should not create an Activity for this. 這種類型的動作是由動作中心通知提供更佳的服務。This type of action is better served by Action Center Notifications.
    • 共同作業案例是例外:如果有多個使用者同時處理相同活動 (例如 Word 檔) ,則會有其他使用者在您的使用者進行變更的情況。Collaboration scenarios are an exception: If multiple users are working on the same activity together (such as a Word document), there will be cases in which another user has made changes after your user. 在此情況下,您可能會想要更新現有的活動,以反映對檔所做的變更。In this case, you may want to update the existing Activity to reflect changes that were made to the document. 這會牽涉到更新現有的使用者活動內容資料,而不需要建立新的記錄專案。This would involve updating the existing User Activity content data without creating a new History Item.

特定應用程式類型的指導方針Guidelines for specific types of apps

雖然每個應用程式都不同,但大部分的應用程式都屬於下列其中一種互動模式。While every app is different, most apps will fall into one of the following interaction patterns.

  • 檔為基礎的應用程式-每份檔建立一個活動,其中有一或多個歷程記錄專案會反映使用期間。Document-based apps — Create one Activity per document, with one or more History Items reflecting periods of use. 當對檔進行變更時,請務必更新您的活動。It is important to update your Activity as changes are made to the document.
  • 遊戲 —為每個遊戲的儲存或世界建立一個活動。Games — Create one Activity for each game save or world. 如果您的遊戲只支援一系列的層級,您可以在一段時間內重新發佈相同的活動,不過您可能會想要更新內容資料,以顯示最新的進度或成就。If your game supports only a single sequence of levels, you can re-publish the same Activity over time, although you may wish to update the content data to show the latest progress or achievements.
  • 公用程式應用 程式-如果您的應用程式中沒有使用者需要離開和繼續的內容,您就不需要使用使用者活動。Utility apps — If there is nothing within your app that users would need to leave and resume, you do not need to use User Activities. 簡單的應用程式(例如計算機)是很好的範例。A good example is a simple app like Calculator.
  • 企業營運應用程式 —有許多應用程式可用於管理簡單的工作或工作流程。Line-of-business apps — Many apps exist for managing simple tasks or workflows. 針對透過您應用程式存取的每個個別工作流程建立一個活動 (例如,expense reports 會每個都是個別的活動,如此一來,使用者就可以按一下活動,查看是否已核准特定的報表) 。Create one activity for each separate workflow accessed through your app (for example, expense reports would each be a separate Activity, so that the user could then click an Activity to see if a particular report was approved).
  • 媒體播放應用程式 :每個邏輯群組建立一個活動,例如播放清單、程式或獨立內容) , (。Media playback apps — Create one Activity per logical grouping of content (such as a playlist, program, or standalone content). 應用程式開發人員的根本問題是 (電視節目的每個內容、歌曲) 會計為獨立內容或部分的集合。The underlying question for app developers is whether a each piece of content (TV episode, song) counts as standalone content or part of a collection. 一般來說,如果使用者選擇播放集合或順序內容,整體的集合就是活動。As a general rule, if the user opts to play a collection or sequential content, the collection as a whole is the activity. 如果他們選擇播放單一的內容,則該內容是活動的一部分。If they opt to play a single piece of content, then that one piece of content is the activity. 請參閱以下更具體的指導方針。See more specific guidelines below.
    • 音樂:專輯/演出者/ 內容類型-如果使用者選取 專輯、演出者或內容類型與點擊數,該集合就是活動;請勿為每個歌曲撰寫個別的活動。Music: Album/Artist/Genre — If the user selects an Album, Artist, or Genre and hits play, that collection is the activity; do not write a separate Activity for each song. 針對較短的集合(例如單一專輯或以隨機順序播放的集合),您可能不需要更新活動以反映使用者目前的位置。For short collections like a single album or collections being played back in a random order, you may not need to update the Activity to reflect the user's current position. 針對長順序播放(如專輯或播放清單),錄製您在專輯內的位置可能有意義。For long sequential playback such as an album or playlist, recording your position within the album might make sense.
    • 音樂:智慧型播放清單 —以隨機順序播放音樂的應用程式應該記錄該播放清單的單一活動。Music: smart playlists — Applications which play music in a random order should record a single Activity for that playlist. 如果使用者第二次播放播放清單,您會建立相同活動的其他歷程記錄。If the user plays the playlist a second time, you would create additional history records for the same Activity. 不需要錄製使用者在播放清單中的目前位置,因為順序是隨機的。Recording the user's current position in the playlist is not necessary because the ordering is random.
    • 電視系列 :如果您的應用程式設定為在目前的節目完成後播放下一集,您應該為電視系列撰寫單一活動。TV series — If your app is configured to play the next episode after the current one is complete, you should write a single Activity for the TV series. 當您跨多個觀看的會話播放各種不同的節目時,您將會更新活動以反映數列中的目前位置,並建立多個記錄記錄。As you play the various episodes across multiple viewing sessions, you'll update your Activity to reflect the current position in the series, and multiple history records will be created.
    • 電影 —電影是一項內容,而且應該有自己的歷程記錄。Movie — A movie is a single piece of content and should have its own history record. 如果使用者停止觀看電影的部分,則最好記錄其位置。If the user stops watching the movie part-way through, it is desirable to record their position. 當他們想要在未來繼續進行時,活動可能會在其離開的地方繼續播放,或甚至詢問使用者是否想要在一開始就繼續或開始。When they wish to resume it in the future, the Activity could resume the movie where they left off, or even ask the user if they wish to resume or start at the beginning.

使用者活動設計User Activity design

使用者活動包含三個元件:啟用 URI、視覺資料和內容中繼資料。User Activities consist of three components: an activation URI, visual data, and content metadata.

  • 啟用 URI 是可傳遞至應用程式或體驗的 URI,以便繼續具有特定內容的應用程式。The activation URI is a URI that can be passed to an application or experience in order to resume the application with a specific context. 一般而言,這些連結會採用適用于配置的通訊協定處理常式格式 (例如,"my-app://page2? action = edit" ) 。Typically, these links take the form of protocol handler for a scheme (for example, "my-app://page2?action=edit"). 由開發人員決定 URI 參數將如何由其應用程式處理。It is up to the developer to determine how URI parameters will be handled by their app. 如需詳細資訊,請參閱 控制碼 URI 啟用See Handle URI activation for more information.
  • 視覺化資料,由一組必要和選擇性屬性所組成 (例如:標題、描述或調適型卡片元素) ,可讓使用者以視覺化方式識別活動。The visual data, consisting of a set of required and optional properties (for example: title, description, or Adaptive Card elements), allow users to visually identify an Activity. 請參閱下方有關為您的活動建立調適型卡片視覺效果的指導方針。See below for guidelines on creating Adaptive Card visuals for your Activity.
  • 內容中繼資料是 JSON 資料,可用來在特定內容下分組和取出活動。The content metadata is JSON data that can be used to group and retrieve activities under a specific context. 一般來說,這會採用資料的形式 http://schema.orgTypically, this takes the form of http://schema.org data. 請參閱下文以取得填寫此資料的指導方針。See below for guidelines on filling out this data.

調適型卡片設計指導方針Adaptive Card design guidelines

當活動在時間軸中出現時,就會使用調適型 卡片架構來顯示。When Activities appear in Timeline, they are displayed using the Adaptive Card framework. 如果開發人員未提供每個活動的調適型卡片,時程表會根據應用程式名稱/圖示、必要的標題欄位和選擇性的描述欄位,自動建立簡單的卡片。If the developer does not provide an Adaptive Card for each Activity, Timeline will automatically create a simple card based on the app name/icon, the required Title field, and the optional Description field.

建議應用程式開發人員使用簡單調適型卡片 JSON 架構來提供自訂卡片。App developers are encouraged to provide custom cards using the simple Adaptive Card JSON schema. 如需有關如何建立調適型卡片物件的技術指示,請參閱 調適型卡片檔See the Adaptive Cards documentation for technical instructions on how to construct Adaptive Card objects. 請參閱下列指導方針,以設計使用者活動中的調適型卡片。Refer to the guidelines below for designing Adaptive Cards in User Activities.

  • 使用影像Use images
    • 如果可能的話,請針對每個活動使用唯一的映射。Use a unique image for each Activity, if possible. 您的應用程式名稱和圖示將會自動顯示在活動的卡片旁邊;其他映射可協助使用者找出他們要尋找的活動。Your application name and icon will automatically be displayed next to your Activity's card; additional images will help users locate the Activity they are looking for.
    • 影像不應包含使用者預期要讀取的文字。Images should not include text that the user is expected to read. 此文字無法供具有存取範圍需求的使用者使用,且無法搜尋。This text won't be available to users with accessibility needs and cannot be searched.
    • 如果映射不包含文字,而且可以裁剪為大約2:1 比例,您應該使用它做為背景影像。If the image doesn't contain text and can be cropped to about a 2:1 ratio, you should use it as a background image. 這會導致在時間軸中有一個粗體的活動卡。This results in a bold activity card which will stand out in Timeline. 影像會稍微暗一點,以確保文字在卡片上保持可見狀態,而且建議您只在這種情況下使用活動名稱,因為較小的文字可能會變得難以閱讀。The image will be darkened slightly to ensure the text remains visible on the card, and you are encouraged to only use the Activity Name in this case, as smaller text can become hard to read.
    • 如果影像無法裁剪為2:1,您應該將它放在活動卡內。If the image cannot be cropped to 2:1, you should put it within the Activity Card.
      • 如果外觀比例是正方形或直向,請將影像錨定在卡片右側且不含邊界。If the aspect ratio is Square or Portrait, anchor the image on the right side of the card with no margins.
      • 如果外觀比例為橫向,請將影像錨定到卡片的右上角。If the aspect ratio is Landscape, anchor the image to the upper-right corner of the card.
  • 每個活動都必須提供活動名稱,且應一律顯示。Each activity is required to provide an Activity Name, which should always be shown.
    • 這個名稱應該會使用大型粗體文字選項顯示在卡片的左上角。This name should be displayed in the upper-left corner of the card using the large bold text option. 很重要的是,名稱很容易辨識,因為這是使用者在 Cortana 案例中顯示活動時唯一會看到的部分。It is important that the name is easily recognizable, as this is the only part users will see when the activity is shown in Cortana scenarios. 在時間軸中顯示相同的名稱,讓使用者更容易流覽大量活動。Showing the same name in Timeline makes it easier for users to browse a large number of Activities.
  • 對您應用程式中的所有活動使用相同的視覺化樣式,讓使用者可以輕鬆地在時間軸中找出您應用程式的活動。Use the same visual style for all of the Activities from your app, so that users can easily locate your app's activities in the Timeline.
    • 例如,活動全都使用相同的背景色彩。For example, Activities should all use the same background color.
  • 請謹慎使用補充文字資訊。Use supplemental text information sparingly.
    • 避免填滿含有文字的卡片,而且只使用補充資訊,以協助使用者尋找正確的活動或反映狀態資訊 (例如特定工作) 的目前進度。Avoid filling the card with text, and only use supplemental information that aids users in finding the right activity or reflects state information (such as the current progress in a particular task).

內容中繼資料指導方針Content metadata guidelines

使用者活動也可以包含內容中繼資料,讓 Windows 和 Cortana 用來分類活動並產生推斷。User Activities can also contain content metadata, which Windows and Cortana use to categorize Activities and generate inferences. 然後,您可以在特定主題周圍分組活動,例如 (如果使用者正在研究休假) ,則物件 (如果使用者正在研究) 或動作 (的使用者是否在不同的應用程式和網站) 購物特定產品。Activities can then be grouped around a particular topic, such as a location (if the user is researching vacations), object (if the user is researching something) or action (if the user is shopping for a particular product across different apps and websites). 最好同時表示與活動相關的名詞和動詞。It's a good idea to represent both the nouns and the verbs involved in an activity.

在下列範例中,content metadata JSON (遵循 Schema.org的標準)代表案例:「John 玩了 Steve 的鳥」。In the following example, the content metadata JSON, following the standards of Schema.org, represents the scenario: "John played Angry Birds with Steve."

// John played angry birds with Steve.
{
  "@context": "http://schema.org",
  "@type": "PlayAction",
  "agent": {
    "@type": "Person",
    "name": "John"
  },
  "object": {
    "@type": "MobileApplication",
    "name": "Angry Birds."
  },
  "participant": {
    "@type": "Person",
    "name": "Steve"
  }
}

重要 APIKey APIs