Registar atividades de contacto

Antes de começares, contribui com os teus contactos para o Windows.

Pode registar atividades de contacto para representar interações significativas entre um utilizador e um contacto dentro da sua aplicação. As atividades de contacto funcionam como sinais de interação leves que ajudam o Windows a compreender como os utilizadores interagem com contactos em experiências relacionadas com pessoas, como Widgets de Pessoas, Folha de Partilha e caixa de pesquisa do Windows em fases planeadas.

Note

A referência ContactAnnotationOperations não lista atualmente uma versão para Windows ou SDK para o Activity valor, e este artigo não indica quais as experiências que utilizam as atividades de contacto atualmente. O histórico de versões nas referências indica Share (Windows 10 versão 1703, SDK 15063) como o valor documentado mais recente. Verifique a referência da API para atualizações antes de depender de Activity numa aplicação que vise versões antigas do SDK.

Cada atividade regista três informações-chave:

  • Quem — o contacto envolvido na interação
  • Tipo de interação — o tipo de interação que ocorreu
  • Quando — o momento em que a interação aconteceu

Para registar uma atividade de contacto, uma aplicação deve criar uma ContactAnnotation associada ao contacto e definir SupportedOperations para ContactAnnotationOperations.Activity. O Windows interpreta anotações com este tipo de operação como sinais de interação associados ao contacto.

Cada atividade representa um único evento de interação e deve ser registada separadamente. Ao submeter múltiplas atividades de contacto, itere pelos registos de interação e chame TrySaveAnnotationAsync para cada evento. Um loop não fornece uma API batch nem reduz a sobrecarga de sincronização.

payload da atividade de contacto

Para registar uma atividade de contacto, defina ProviderProperties["ActivityPayload"] no ContactAnnotation para uma string JSON que descreve a interação.

A carga útil deve incluir as seguintes propriedades:

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

Utilize a chave ActivityPayload e os nomes ActivityType das propriedades da carga útil e ActivityTimestampUnix exatamente como mostrado. Estes nomes formam o contrato baseado em cadeias de caracteres para descrever a atividade.

Tipos de atividade de contacto suportados

O ActivityType campo identifica a interação que ocorreu entre o utilizador e o contacto. O Windows suporta atualmente os seguintes tipos de atividade.

TipoDeAtividade Description
message Enviar ou receber uma mensagem com o contacto.
call Iniciar ou atender uma chamada de áudio ou vídeo.
email Enviar ou receber um email.
meeting Participar ou agendar uma reunião envolvendo o contacto.
share Partilhar conteúdo com o contacto.
social Interagir com o contacto através de experiências sociais.
profileInteraction Abrir ou interagir com o perfil do contacto.

As aplicações devem indicar o tipo de atividade que melhor representa a interação do utilizador que ocorreu dentro da aplicação.

Exemplo de registo de uma atividade de contacto

O exemplo seguinte mostra como registar uma interação de mensagens como atividade de contacto.

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 guardar a anotação, por isso verifica o resultado antes de assumires que a atividade foi registada. Um true resultado significa que a anotação foi guardada. Não indica como o Windows processa a atividade mais tarde.

Modelo de acesso das atividades de contacto

As atividades de contacto são apenas de escrita do ponto de vista da sua aplicação. A sua aplicação pode submeter registos de atividade, mas o Windows atualmente não suporta a recuperação ou a eliminação explícita de registos de atividade previamente submetidos. A limpeza do ciclo de vida gerida pelo Windows é separada, conforme descrito na secção seguinte.

Se a sua aplicação precisar de guardar ou gerir o histórico de interação, guarde-o no seu próprio armazenamento ou serviço backend.

Ciclo de vida das atividades de contacto

As atividades de contacto estão associadas a contactos usando o RemoteId fornecido pela aplicação.

Se um contacto for removido ou o RemoteId associado for eliminado, as atividades de contacto ligadas a esse contacto são automaticamente removidas. De forma semelhante, quando uma aplicação é desinstalada ou a sua entrada associada UserDataAccount é removida, o Windows remove automaticamente os contactos e as atividades de contacto registados por essa aplicação.

Processamento e retenção de atividades de contacto

As ações de contacto são processadas pelo Windows como sinais de interação.

O período de retenção, expiração (TTL), agregação e avaliação das atividades de contacto são geridos internamente pelo Windows. As aplicações não controlam quanto tempo as atividades ficam armazenadas nem como são processadas após a submissão.

As atividades de contacto devem representar interações genuínas dos utilizadores e não devem ser geradas com a intenção de influenciar a classificação ou visibilidade dos contactos. O Windows determina como estes sinais contribuem para experiências relacionadas com as pessoas, usando lógica interna da plataforma.

Conteúdo relacionado

  • Última atualização a