Registrare le attività di contatto

Prima di iniziare, aggiungi i tuoi contatti in Windows.

È possibile registrare le attività di contatto per rappresentare interazioni significative tra un utente e un contatto all'interno dell'applicazione. Le attività di contatto fungono da segnali di interazione leggeri che consentono a Windows di comprendere in che modo gli utenti interagiscono con i contatti tra esperienze correlate alle persone, ad esempio People Widgets, foglio di condivisione e casella di ricerca di Windows nelle fasi pianificate.

Ogni attività registra tre informazioni chiave:

• Chi — il contatto coinvolto nell'interazione
• Cosa — il tipo di interazione che si è verificata
• Quando — il momento in cui si è verificata l'interazione

Per registrare un'attività di contatto, un'applicazione deve creare un Oggetto ContactAnnotation associato al contatto e impostare SupportedOperations su ContactAnnotationOperations.Activity. Windows interpreta le annotazioni con questo tipo di operazione come segnali di interazione associati al contatto.

Ogni attività rappresenta un singolo evento di interazione e deve essere registrata separatamente. Quando si inviano più attività di contatto, scorrere i record di interazione e chiamare TrySaveAnnotationAsync per ogni evento. Un ciclo non fornisce un'API batch né riduce il sovraccarico di sincronizzazione.

Payload dell'attività di contatto

Per registrare un'attività di contatto, impostare ProviderProperties["ActivityPayload"] in ContactAnnotation su una stringa JSON che descrive l'interazione.

Il payload deve includere le proprietà seguenti:

Usare la chiave ActivityPayload e i nomi ActivityType delle proprietà del payload e ActivityTimestampUnix esattamente come illustrato. Questi nomi costituiscono il contratto basato su stringa per descrivere l'attività.

Tipi di attività di contatto supportati

Il ActivityType campo identifica l'interazione che si è verificata tra l'utente e il contatto. Windows attualmente supporta i seguenti tipi di attività.

Le richieste devono selezionare il tipo di attività che meglio rappresenta l'interazione dell'utente che si è verificata all'interno dell'applicazione.

Esempio di registrazione di un'attività di contatto

Nell'esempio seguente viene illustrato come registrare un'interazione di messaggistica come attività di contatto.

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 restituisce false quando non riesce a salvare l'annotazione, quindi controllare il risultato prima di presupporre che l'attività sia stata registrata. Un true risultato indica che l'annotazione è stata salvata. Non indica come Windows in seguito elabora l'attività.

Modello di accesso alle attività dei contatti

Le attività di contatto sono di sola scrittura dal punto di vista dell'app. L'app può inviare record attività, ma Windows attualmente non supporta il recupero o l'eliminazione esplicita dei record attività inviati in precedenza. La pulizia del ciclo di vita gestito da Windows è separata, come descritto nella sezione successiva.

Se l'app deve mantenere o gestire la cronologia delle interazioni, conservala nel tuo sistema di archiviazione o servizio backend.

Ciclo di vita delle attività del contatto

Le attività di contatto sono associate ai contatti tramite RemoteId fornito dall'applicazione.

Se un contatto viene rimosso o l'associato RemoteId viene eliminato, le attività di contatto collegate a tale contatto vengono rimosse automaticamente. Analogamente, quando un'applicazione viene disinstallata o la relativa associazione UserDataAccount viene rimossa, Windows rimuove automaticamente i contatti e le attività di contatto registrate dall'applicazione.

Elaborazione e conservazione delle attività di contatto

Le attività del contatto vengono elaborate da Windows come segnali di interazione.

Il periodo di conservazione, la scadenza (TTL), l'aggregazione e la valutazione delle attività di contatto vengono gestiti internamente da Windows. Le applicazioni non controllano per quanto tempo vengono archiviate le attività o come vengono elaborate dopo l'invio.

Le attività di contatto devono rappresentare interazioni utente autentiche e non devono essere generate con l'intento di influenzare la classificazione o la visibilità dei contatti. Windows determina il modo in cui questi segnali contribuiscono alle esperienze correlate alle persone usando la logica interna della piattaforma.

Contenuti correlati

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