Enregistrer les activités liées aux contacts

Avant de commencer, ajoutez vos contacts à Windows.

Vous pouvez enregistrer des activités de contact pour représenter des interactions significatives entre un utilisateur et un contact au sein de votre application. Les activités liées aux contacts agissent comme des signaux d’interaction légers qui aident Windows à comprendre comment les utilisateurs interagissent avec des contacts dans des expériences liées aux personnes telles que People Widgets, Share Sheet et la zone Windows Search, en phases planifiées.

Chaque activité enregistre trois éléments clés d’informations :

• Qui — le contact impliqué dans l’interaction
• Type — le type d’interaction qui s’est produite
• Quand — heure à laquelle l’interaction s’est produite

Pour enregistrer une activité de contact, une application doit créer un ContactAnnotation associé au contact et définir SupportedOperations sur ContactAnnotationOperations.Activity. Windows interprète les annotations avec ce type d’opération en tant que signaux d’interaction associés au contact.

Chaque activité représente un événement d’interaction unique et doit être enregistrée séparément. Lors de l’envoi de plusieurs activités de contact, effectuez une itération dans les enregistrements d’interaction et appelez TrySaveAnnotationAsync pour chaque événement. Une boucle ne fournit pas d’API batch et ne réduit pas la surcharge de synchronisation.

Charge utile de l’activité Contact

Pour enregistrer une activité de contact, définissez ProviderProperties["ActivityPayload"] de ContactAnnotation sur une chaîne JSON qui décrit l’interaction.

La charge utile doit inclure les propriétés suivantes :

Utilisez la clé ActivityPayload et les noms de propriété de payload ActivityType et ActivityTimestampUnix exactement comme indiqué. Ces noms forment le contrat basé sur les chaînes de caractères pour décrire l’activité.

Types d’activités de contact pris en charge

Le ActivityType champ identifie l’interaction qui s’est produite entre l’utilisateur et le contact. Windows prend actuellement en charge les types d’activités suivants.

Les applications doivent choisir le type d’activité qui représente le mieux l’interaction de l’utilisateur ayant eu lieu dans l’application.

Enregistrement d’un exemple d’activité de contact

L’exemple suivant montre comment enregistrer une interaction de messagerie en tant qu’activité de contact.

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 retourne false lorsqu’elle ne peut pas enregistrer l’annotation. Vérifiez donc le résultat avant de supposer que l’activité a été enregistrée. Un true résultat signifie que l’annotation a été enregistrée. Il n'indique pas comment Windows traite ensuite l'activité.

Modèle d’accès aux activités du contact

Les activités de contact sont accessibles uniquement en écriture du point de vue de votre application. Votre application peut envoyer des enregistrements d'activité, mais Windows ne prend actuellement pas en charge la récupération ou la suppression explicite des enregistrements d'activité précédemment envoyés. Le nettoyage du cycle de vie géré par Windows est distinct, comme décrit dans la section suivante.

Si votre application doit conserver ou gérer l’historique des interactions, conservez-le dans votre propre service de stockage ou de back-end.

Cycle de vie des activités du contact

Les activités de contact sont associées aux contacts à l’aide du RemoteId fourni par l’application.

Si un contact est supprimé ou si l’élément associé RemoteId est supprimé, les activités de contact liées à ce contact sont automatiquement supprimées. De même, lorsqu’une application est désinstallée ou que son UserDataAccount associé est supprimé, Windows supprime automatiquement les contacts et les activités de contact enregistrées par cette application.

Traitement et rétention des activités de contact

Les activités de contact sont traitées par Windows comme signaux d’interaction.

La période de rétention, l’expiration (TTL), l’agrégation et l’évaluation des activités de contact sont gérées en interne par Windows. Les applications ne contrôlent pas la durée pendant laquelle les activités sont stockées ou comment elles sont traitées après l’envoi.

Les activités de contact doivent représenter des interactions utilisateur authentiques et ne doivent pas être générées avec l’intention d’influencer le classement ou la visibilité du contact. Windows détermine comment ces signaux contribuent aux expériences liées aux personnes à l’aide de la logique de plateforme interne.

Contenu connexe

• ContactAnnotation
• ContactAnnotationOperations
• ContactAnnotation.ProviderProperties
• ContactAnnotationList.TrySaveAnnotationAsync