Рекомендации для пользователя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. Или ознакомьтесь с разделом действия пользователя в проекте Рим для реализации действий на других платформах разработки.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. Действия пользователя будут демонстрироваться в Кортане и временной шкале, что способствует повышению производительности и эффективности работы пользователей, помогая им вернуться к содержимому, которое они посещали в прошлом.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. Создайте одно действие для каждого отдельного рабочего процесса, доступ к которому осуществляется через приложение (например, отчеты о расходах будут отдельными действиями, чтобы пользователь мог щелкнуть действие, чтобы проверить, был ли утвержден определенный отчет).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 — фильм — это единый фрагмент содержимого, который должен иметь собственную запись журнала.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), который может быть передан приложению или интерфейсу для возобновления работы приложения с указанным контекстом.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.org данных.Typically, 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. Очень важно, чтобы имя было легко распознано, так как это единственная часть, которую пользователи увидят при отображении действия в сценариях Кортаны.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 и Кортана используют для категоризации действий и создания выводов.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.

В следующем примере метаданные JSON метаданных содержимого, указанные в стандарте Schema.org, представляют сценарий: "Джон играл злость птиц with Стив".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"
  }
}

Основные API-интерфейсыKey APIs