Continue a atividade do usuário, mesmo entre dispositivos
Este tópico descreve como ajudar os usuários a retomar o que estavam fazendo em seu aplicativo no computador e em vários dispositivos.
Observação
A partir de julho de 2021, os usuários que têm o histórico de atividades sincronizado em seus dispositivos Windows por meio de sua MSA (Conta Microsoft) não terão mais a opção de carregar novas atividades na Linha do Tempo. Eles ainda poderão usar a Linha do Tempo e ver seu histórico de atividades (informações sobre aplicativos, sites e arquivos recentes) em seu computador local. As contas conectadas ao AAD não serão impactadas.
Atividades do usuário e linha do tempo
Nosso tempo todos os dias é distribuído por vários dispositivos. Podemos usar nosso telefone enquanto estamos no ônibus, um PC durante o dia e depois um telefone ou tablet à noite. A partir do Windows 10 Build 1803 ou posterior, a criação de uma Atividade do Usuário faz com que essa atividade apareça na Linha do Tempo do Windows e no recurso Continuar de onde parei da Cortana. A linha do tempo é uma visualização de tarefas avançada que aproveita as Atividades do usuário para mostrar uma exibição cronológica do que você está trabalhando. Também pode incluir o que você estava trabalhando em todos os dispositivos.
Da mesma forma, vincular seu telefone ao seu PC com Windows permite que você continue o que estava fazendo anteriormente em seu dispositivo iOS ou Android.
Pense em uma UserActivity como algo específico em que o usuário estava trabalhando em seu aplicativo. Por exemplo, se você estiver usando um leitor de RSS, um UserActivity pode ser o feed que você está lendo. Se você estiver jogando um jogo, o UserActivity pode ser o nível que você está jogando. Se você estiver ouvindo um aplicativo de música, o UserActivity pode ser a lista de reprodução que você está ouvindo. Se você estiver trabalhando em um documento, a UserActivity pode estar de onde você parou de trabalhar nele e assim por diante. Em resumo, um UserActivity representa um destino dentro do seu aplicativo para permitir que o usuário retome o que estava fazendo.
Quando você interage com uma UserActivity chamando UserActivity.CreateSession, o sistema cria um registro de histórico indicando a hora de início e término dessa UserActivity. À medida que você se envolve novamente com essa UserActivity ao longo do tempo, vários registros de histórico são registrados para ela.
Adicionar atividades do usuário ao seu aplicativo
Uma UserActivity é a unidade de envolvimento do usuário no Windows. Ele tem três partes: um URI usado para ativar o aplicativo ao qual a atividade pertence, visuais e metadados que descrevem a atividade.
- O ActivationUri é usado para retomar o aplicativo com um contexto específico. Normalmente, esse link assume a forma de manipulador de protocolo para um esquema (por exemplo, "my-app://page2?action=edit") ou de um AppUriHandler (por exemplo,
http://contoso.com/page2?action=edit). - VisualElements expõe uma classe que permite ao usuário identificar visualmente uma atividade com um título, descrição ou elementos de Cartão Adaptável.
- Por fim, o conteúdo é onde você pode armazenar metadados para a atividade que podem ser usados para agrupar e recuperar atividades em um contexto específico. Muitas vezes, isso assume a forma de https://schema.org dados.
Para adicionar uma UserActivity ao seu aplicativo:
- Gere objetos UserActivity quando o contexto do usuário for alterado no aplicativo (como navegação de página, novo nível de jogo etc.)
- Preencha os objetos UserActivity com o conjunto mínimo de campos obrigatórios: ActivityId, ActivationUri e UserActivity.VisualElements.DisplayText.
- Adicione um manipulador de esquema personalizado ao seu aplicativo para que ele possa ser reativado por um UserActivity.
Uma UserActivity pode ser integrada a um aplicativo com apenas algumas linhas de código. Por exemplo, imagine este código em MainPage.xaml.cs, dentro da classe MainPage (nota: assume 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();
}
A primeira linha no método acima obtém o GenerateActivityAsync() UserActivityChannel de um usuário. Este é o feed no qual as atividades deste aplicativo serão publicadas. A próxima linha consulta o canal de uma atividade chamada MainPage.
- Seu aplicativo deve nomear as atividades de forma que a mesma ID seja gerada sempre que o usuário estiver em um local específico no aplicativo. Por exemplo, se seu aplicativo for baseado em página, use um identificador para a página; Se for baseado em documento, use o nome do documento (ou um hash do nome).
- Se houver uma atividade existente no feed com o mesmo ID, essa atividade será retornada do canal com
UserActivity.Statedefinido como Publicado). Se não houver nenhuma atividade com esse nome e a nova atividade for retornada comUserActivity.Statedefinido como Novo. - As atividades têm como escopo seu aplicativo. Você não precisa se preocupar com a colisão do ID da atividade com os IDs em outros aplicativos.
Depois de obter ou criar o UserActivity, especifique os outros dois campos obrigatórios: UserActivity.VisualElements.DisplayTexte UserActivity.ActivationUri.
Em seguida, salve os metadados UserActivity chamando SaveAsync e, finalmente , CreateSession, que retorna um UserActivitySession. O UserActivitySession é o objeto que podemos usar para gerenciar quando o usuário está realmente envolvido com o UserActivity. Por exemplo, devemos chamar Dispose() o UserActivitySession quando o usuário sair da página. No exemplo acima, também chamamos Dispose() antes de _currentActivity chamar CreateSession(). Isso ocorre porque criamos _currentActivity um campo de membro de nossa página e queremos interromper qualquer atividade existente antes de iniciarmos a nova (nota: o ? é o operador condicional nulo que testa null antes de realizar o acesso de membro).
Como, nesse caso, o ActivationUri é um esquema personalizado, também precisamos registrar o protocolo no manifesto do aplicativo. Isso é feito no arquivo XML Package.appmanifest ou usando o designer.
Para fazer a alteração com o designer, clique duas vezes no arquivo Package.appmanifest em seu projeto para iniciar o designer, selecione a guia Declarações e adicione uma definição de protocolo. A única propriedade que precisa ser preenchida, por enquanto, é Nome. Ele deve corresponder ao URI especificado acima, my-app.
Agora precisamos escrever algum código para dizer ao aplicativo o que fazer quando ele for ativado por um protocolo. Vamos substituir o OnActivated método em App.xaml.cs para passar o URI para a página principal, assim:
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();
}
O que esse código faz é detectar se o aplicativo foi ativado por meio de um protocolo. Se foi, ele procura ver o que o aplicativo deve fazer para retomar a tarefa para a qual está sendo ativado. Por ser um aplicativo simples, a única atividade que esse aplicativo retoma é colocá-lo na página secundária quando o aplicativo é exibido.
Usar Cartões Adaptáveis para melhorar a experiência da Linha do Tempo
As atividades do usuário aparecem na Cortana e na linha do tempo. Quando as atividades aparecem na Linha do Tempo, nós as exibimos usando a estrutura do Cartão Adaptável. Se você não fornecer um cartão adaptável para cada atividade, a Linha do Tempo criará automaticamente um cartão de atividade simples com base no nome e no ícone do aplicativo, no campo de título e no campo de descrição opcional. Abaixo está um exemplo de conteúdo do Cartão Adaptável e o cartão que ele produz.
]
Exemplo de cadeia de caracteres JSON do conteúdo do cartão adaptável:
{
"$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
}
]
}
]
}
Adicione o conteúdo de Cartões Adaptáveis como uma cadeia de caracteres JSON ao UserActivity da seguinte forma:
activity.VisualElements.Content =
Windows.UI.Shell.AdaptiveCardBuilder.CreateAdaptiveCardFromJson(jsonCardText); // where jsonCardText is a JSON string that represents the card
Integração entre plataformas e serviço a serviço
Se o aplicativo for executado em várias plataformas (por exemplo, no Android e no iOS) ou mantiver o estado do usuário na nuvem, você poderá publicar UserActivities por meio do Microsoft Graph. Depois que seu aplicativo ou serviço for autenticado com uma conta da Microsoft, serão necessárias apenas duas chamadas REST simples para gerar objetos Activity e History, usando os mesmos dados descritos acima.
Resumo
Você pode usar a API UserActivity para fazer seu aplicativo aparecer na Linha do Tempo e na Cortana.
- Saiba mais sobre a API UserActivity
- Confira o código de exemplo.
- Veja Cartões Adaptáveis mais sofisticados.
- Publique uma UserActivity do iOS, Android ou do serviço Web por meio do Microsoft Graph.
- Saiba mais sobre o Project Rome no GitHub.