Registrar atividades de contato

Antes de iniciar, adicione seus contatos ao Windows.

Você pode gravar atividades de contato para representar interações significativas entre um usuário e um contato em seu aplicativo. As atividades dos contatos atuam como sinais leves de interação que ajudam o Windows a entender como os usuários interagem com contatos em experiências relacionadas a pessoas, como Widgets de Pessoas, Share Sheet e caixa de pesquisa do Windows, em fases planejadas.

Note

No momento, a referência ContactAnnotationOperations não lista uma versão do Windows ou do SDK para o Activity valor e este artigo não informa quais experiências usam atividades de contato hoje. O histórico de versão na referência lista Share (Windows 10 versão 1703, SDK 15063) como o valor documentado mais recente. Verifique a referência de API para obter atualizações antes de depender de Activity em um aplicativo direcionado a versões mais antigas do SDK.

Cada atividade registra três partes principais de informações:

  • Quem — o contato envolvido na interação
  • O quê : o tipo de interação que ocorreu
  • Quando — a hora em que a interação aconteceu

Para registrar uma atividade de contato, um aplicativo deve criar uma ContactAnnotation associada ao contato e definir SupportedOperations como ContactAnnotationOperations.Activity. Windows interpreta anotações com esse tipo de operação como sinais de interação associados ao contato.

Cada atividade representa um único evento de interação e deve ser gravada separadamente. Ao enviar várias atividades de contato, itere por meio dos registros de interação e chame TrySaveAnnotationAsync para cada evento. Um loop não fornece uma API em lote nem reduz a sobrecarga de sincronização.

Payload da atividade de contato

Para registrar uma atividade de contato, defina ProviderProperties["ActivityPayload"] no ContactAnnotation como uma cadeia de caracteres JSON que descreve a interação.

O conteúdo deve incluir as seguintes propriedades:

Property Description
ActivityType Identifica o tipo de interação.
ActivityTimestampUnix Hora em que a interação ocorreu, expressa como tempo Unix UTC em segundos.

Use a chave ActivityPayload e os nomes das propriedades de conteúdo ActivityType e ActivityTimestampUnix exatamente como mostrado. Esses nomes formam o contrato baseado em string para descrever a atividade.

Tipos de atividade de contato compatíveis

O ActivityType campo identifica a interação que ocorreu entre o usuário e o contato. Windows atualmente dá suporte aos seguintes tipos de atividade.

TipoDeAtividade Description
message Enviando ou recebendo uma mensagem com o contato.
call Iniciando ou respondendo a uma chamada de áudio ou vídeo.
email Enviando ou recebendo um email.
meeting Ingressar ou agendar uma reunião envolvendo o contato.
share Compartilhar conteúdo com o contato.
social Interagir com o contato por meio de interações sociais.
profileInteraction Abrir ou interagir com o perfil do contato.

Os aplicativos devem selecionar o tipo de atividade que melhor representa a interação do usuário que ocorreu no aplicativo.

Gravando um exemplo de atividade de contato

O exemplo a seguir mostra como registrar uma interação de mensagens como uma atividade de contato.

long nowUnix = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

var payload = new
{
    ActivityType = "message",
    ActivityTimestampUnix = nowUnix
};

var annotation = new ContactAnnotation
{
    ContactId = contact.Id,
    RemoteId = contact.RemoteId,
    SupportedOperations = ContactAnnotationOperations.Activity
};

annotation.ProviderProperties["ActivityPayload"] =
    JsonSerializer.Serialize(payload);

bool saved = await this.contactAnnotationList.TrySaveAnnotationAsync(annotation);
if (!saved)
{
    // The annotation wasn't saved, so Windows didn't receive this activity.
    // Log the failure or retry later. Don't treat the interaction as recorded.
    System.Diagnostics.Debug.WriteLine(
        $"Failed to save contact activity for contact {contact.RemoteId}.");
}

TrySaveAnnotationAsync retorna false quando não consegue salvar a anotação, portanto, verifique o resultado antes de assumir que a atividade foi registrada. Um true resultado significa que a anotação foi salva. Isso não indica como o Windows posteriormente processa a atividade.

Modelo de acesso a atividades de contato

As atividades de contato são somente de gravação da perspectiva do seu aplicativo. Seu aplicativo pode enviar registros de atividade, mas Windows atualmente não dá suporte à recuperação ou à exclusão explícita de registros de atividade enviados anteriormente. A limpeza do ciclo de vida gerenciada pelo Windows é separada, conforme descrito na próxima seção.

Se seu aplicativo precisar reter ou gerenciar o histórico de interação, mantenha-o em seu próprio armazenamento ou serviço de back-end.

Ciclo de vida de atividades de contato

As atividades de contato são associadas a contatos usando o RemoteId fornecido pelo aplicativo.

Se um contato for removido ou o registro associado RemoteId for excluído, as atividades de contato vinculadas a esse contato serão removidas automaticamente. Da mesma forma, quando um aplicativo é desinstalado ou seu UserDataAccount associado é removido, o Windows remove automaticamente os contatos e as atividades de contato registradas por esse aplicativo.

Processamento e retenção de atividades de contatos

Os eventos de contato são processados pelo Windows como sinais de interação.

O período de retenção, a expiração (TTL), a agregação e a avaliação das atividades de contato são gerenciados internamente por Windows. Os aplicativos não controlam por quanto tempo as atividades são armazenadas ou como são processadas após o envio.

As atividades de contato devem representar interações genuínas do usuário e não devem ser geradas com a intenção de influenciar a classificação de contatos ou a visibilidade. O Windows determina como esses sinais contribuem para experiências voltadas para pessoas usando a lógica interna da plataforma.

Conteúdo relacionado

  • Última atualização em