Registrar interacciones de contacto

Antes de empezar, agregue sus contactos a Windows.

Puede registrar actividades de contacto para representar interacciones significativas entre un usuario y un contacto dentro de la aplicación. Las actividades de los contactos actúan como señales de interacción ligeras que ayudan a Windows a comprender cómo los usuarios interactúan con los contactos en experiencias relacionadas con personas, como Widgets de personas, Share Sheet y Windows Search Box, de forma planificada por fases.

Note

La referencia ContactAnnotationOperations no enumera actualmente una versión de Windows o SDK para el Activity valor y este artículo no indica qué experiencias usan las actividades de contacto en la actualidad. El historial de versiones de la referencia enumera Share (Windows 10, versión 1703, SDK 15063) como el valor documentado más reciente. Compruebe la referencia de API para ver las actualizaciones antes de depender de Activity en una aplicación que tenga como destino versiones anteriores del SDK.

Cada actividad registra tres fragmentos clave de información:

  • Quién : el contacto implicado en la interacción
  • Qué : el tipo de interacción que se produjo
  • Cuándo : la hora en la que se produjo la interacción

Para registrar una actividad de contacto, una aplicación debe crear una ContactAnnotation asociada al contacto y establecer SupportedOperations en ContactAnnotationOperations.Activity. Windows interpreta las anotaciones con este tipo de operación como señales de interacción asociadas al contacto.

Cada actividad representa un único evento de interacción y se debe registrar por separado. Al enviar varias actividades de contacto, recorra en iteración los registros de interacción y llame a TrySaveAnnotationAsync para cada evento. Un bucle no proporciona una API por lotes ni reduce la sobrecarga de sincronización.

Carga de la actividad del contacto

Para registrar una actividad de contacto, establezca ProviderProperties["ActivityPayload"] de ContactAnnotation en una cadena JSON que describa la interacción.

La carga debe incluir las siguientes propiedades:

Property Description
ActivityType Identifica el tipo de interacción.
ActivityTimestampUnix Hora en la que se produjo la interacción, expresada como marca de tiempo Unix en UTC en segundos.

Use la clave ActivityPayload y los nombres de propiedad payload ActivityType y ActivityTimestampUnix exactamente como se muestra. Estos nombres forman el contrato basado en cadenas de texto para describir la actividad.

Tipos de actividad de contacto admitidos

El ActivityType campo identifica la interacción que se produjo entre el usuario y el contacto. Windows actualmente admite los siguientes tipos de actividad.

TipoDeActividad Description
message Enviar o recibir un mensaje con el contacto.
call Iniciar o responder a una llamada de audio o vídeo.
email Enviar o recibir un correo electrónico.
meeting Unirse o programar una reunión que implique al contacto.
share Compartir contenido con el contacto.
social Interactuar con el contacto a través de experiencias sociales.
profileInteraction Abrir o interactuar con el perfil del contacto.

Las aplicaciones deben seleccionar el tipo de actividad que mejor represente la interacción del usuario que se produjo dentro de la aplicación.

Registrar un ejemplo de actividad de contacto

En el ejemplo siguiente se muestra cómo registrar una interacción de mensajería como actividad 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 devuelve false cuando no puede guardar la anotación, por lo que compruebe el resultado antes de asumir que se registró la actividad. Un resultado true significa que se guardó la anotación. No indica cómo Windows más adelante procesa la actividad.

Modelo de acceso de las actividades de contacto

Las actividades de contacto son de solo escritura desde la perspectiva de la aplicación. La aplicación puede enviar registros de actividad, pero Windows no admite actualmente la recuperación o eliminación explícita de registros de actividad enviados previamente. La limpieza del ciclo de vida administrado por Windows es independiente, como se describe en la sección siguiente.

Si tu aplicación necesita conservar o administrar el historial de interacciones, guárdalo en tu propio almacenamiento o servicio back-end.

Ciclo de vida de las actividades del contacto

Las actividades de contacto están asociadas a contactos usando el RemoteId proporcionado por la aplicación.

Si se quita un contacto o se elimina el asociado RemoteId , las actividades de contacto vinculadas a ese contacto se quitan automáticamente. Del mismo modo, cuando se desinstala una aplicación o se quita su UserDataAccount asociado, Windows quita automáticamente los contactos y las actividades de contacto registradas por esa aplicación.

Procesamiento y retención de actividades de contacto

Las actividades táctiles se procesan por Windows como señales de interacción.

El período de retención, la expiración (TTL), la agregación y la evaluación de las actividades de contacto se administran internamente mediante Windows. Las aplicaciones no controlan cuánto tiempo se almacenan las actividades o cómo se procesan después del envío.

Las actividades de contacto deben representar interacciones originales del usuario y no deben generarse con la intención de influir en la clasificación o visibilidad de los contactos. Windows determina cómo contribuyen estas señales a las experiencias relacionadas con las personas mediante la lógica de plataforma interna.

Contenido relacionado

  • Se actualizó por última vez el