Compartilhar via

Continuar 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 todos os dispositivos.

Observação

A partir de julho de 2021, os usuários que tiverem o histórico de atividades sincronizado em seus dispositivos Windows por meio de sua CONTA da Microsoft (MSA) 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 o 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 afetadas.

Atividades do usuário e linha do tempo

Nosso tempo todos os dias é distribuído em vários dispositivos. Podemos usar nosso telefone enquanto estiver no ônibus, um computador durante o dia, 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 da Cortana 'Continuar de onde parei'. A linha do tempo é uma visão de tarefas enriquecida que aproveita as Atividades do Usuário para apresentar uma visão cronológica do que você vem trabalhando. Ele também pode incluir o que você estava trabalhando em todos os dispositivos.

Imagem da linha do tempo do Windows

Da mesma forma, vincular seu telefone ao computador 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, uma UserActivity poderá ser o feed que você está lendo. Se você estiver jogando um jogo, a UserActivity poderá ser o nível que você está jogando. Se você estiver ouvindo um aplicativo de música, a UserActivity pode ser a playlist que você está ouvindo. Se você estiver trabalhando em um documento, a UserActivity poderá estar onde você parou de trabalhar nele e assim por diante. Em suma, uma UserActivity representa um destino em seu aplicativo, de modo que permite que o usuário retome o que estava fazendo.

Quando você interage com um UserActivity chamando UserActivity.CreateSession, o sistema cria um registro de histórico indicando o tempo de início e término desse UserActivity. À medida que você se reenga com esse UserActivity ao longo do tempo, vários registros de histórico são registrados para ele.

Adicionar atividades do usuário ao seu aplicativo

Um UserActivity é a unidade de engajamento 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.

  1. 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).
  2. O VisualElements expõe uma classe que permite que o usuário identifique visualmente uma atividade com um título, uma descrição ou elementos de Cartão Adaptável.
  3. Por fim, 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 se apresenta na forma de dados https://schema.org.

Para adicionar um UserActivity ao seu aplicativo:

  1. Gere objetos UserActivity quando o contexto do usuário for alterado dentro do aplicativo (como navegação de página, novo nível de jogo etc.)
  2. Preencha objetos UserActivity com o conjunto mínimo de campos necessários: ActivityId, ActivationUrie UserActivity.VisualElements.DisplayText.
  3. Adicione um manipulador de esquema personalizado ao seu aplicativo para que ele possa ser reativado por uma UserActivity.

Uma UserActivity pode ser integrada a um aplicativo com apenas algumas linhas de código. Por exemplo, imagine esse código em MainPage.xaml.cs, dentro da classe MainPage (observação: pressupõe 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 do método acima obtém oUserActivityChannel de um usuário. Esse é 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 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 o seu aplicativo for baseado em páginas, use um identificador para a página; se for baseado em documentos, use o nome do documento (ou uma hash do nome).
  • Se houver uma atividade existente no feed com o mesmo ID, essa atividade será retornada do canal, com UserActivity.State configurado como Publicado). Se não houver nenhuma atividade com esse nome e a nova atividade for retornada com UserActivity.State definida como Nova.
  • As atividades são limitadas ao seu aplicativo. Você não precisa se preocupar com sua ID de atividade colidindo com 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 utilizando a chamada SaveAsynce, finalmente, CreateSession, que retorna uma 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() na UserActivitySession quando o usuário sair da página. No exemplo acima, também chamamos Dispose() em _currentActivity antes de chamar CreateSession(). Isso ocorre porque criamos _currentActivity um campo membro de nossa página e queremos interromper qualquer atividade existente antes de iniciarmos a nova (observação: é o ?operador condicional nulo que testa nulo antes de executar o acesso do membro).

Como, nesse caso, o ActivationUri esquema é personalizado, também precisamos registrar o protocolo no manifesto do aplicativo. Isso é feito no arquivo XML Package.appmanifest ou usando o designer.

Para efetuar a alteração com o designer, clique duas vezes no arquivo Package.appmanifest em seu projeto para abrir 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 informar ao aplicativo o que fazer quando ele for ativado por um protocolo. Substituiremos o método OnActivated em App.xaml.cs para passar o URI para a página principal, da seguinte maneira:

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, então verifica o que o aplicativo deve fazer para retomar a tarefa para a qual foi ativado. Sendo um aplicativo simples, a única atividade que este aplicativo retoma é colocá-lo na página secundária quando o aplicativo aparece.

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 o framework 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 do aplicativo e no ícone, no campo de título e no campo de descrição opcional. Veja abaixo um exemplo de payload do Adaptive Card e o cartão que ele produz.

Um cartão adaptável ]

Exemplo de cadeia de caracteres JSON de conteúdo de 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 payload de Cartões Adaptáveis como uma cadeia de caracteres JSON à Atividade do Usuário desta 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 entre serviços

Se seu aplicativo executar multiplataforma (por exemplo, no Android e no iOS) ou manter o estado do usuário na nuvem, você poderá publicar UserActivities por meio de do Microsoft Graph. Depois que seu aplicativo ou serviço é autenticado com uma conta da Microsoft, ele apenas usa duas chamadas REST simples para gerar objetos de Atividade e Histórico , usando os mesmos dados descritos acima.

Resumo

Você pode usar a API UserActivity para fazer seu aplicativo aparecer na Timeline e na Cortana.

APIs de chave