Kontaktaktivitäten aufzeichnen

Bevor Sie beginnen, fügen Sie Ihre Kontakte zu Windows hinzu.

Sie können Kontaktaktivitäten aufzeichnen, um sinnvolle Interaktionen zwischen einem Benutzer und einem Kontakt innerhalb Ihrer Anwendung darzustellen. Kontaktaktivitäten dienen als einfache Interaktionssignale, die Windows helfen zu verstehen, wie Benutzer in geplanten Phasen mit Kontakten in personenbezogenen Funktionen interagieren, z. B. Personen-Widgets, Share Sheet und Windows-Suchfeld.

Note

Die ContactAnnotationOperations-Referenz listet derzeit keine Windows- oder SDK-Version für den Activity-Wert auf, und in diesem Artikel wird nicht festgelegt, welche Szenarien heute Kontaktaktivitäten verwenden. Der Versionsverlauf in der Referenz führt Share (Windows 10 Version 1703, SDK 15063) als den aktuellsten dokumentierten Wert auf. Überprüfen Sie die API-Referenz auf Updates, bevor Sie Activity in einer App verwenden, die auf ältere SDK-Versionen ausgerichtet ist.

Jede Aktivität zeichnet drei Wichtige Informationen auf:

  • Wer – der Kontakt, der an der Interaktion beteiligt ist
  • Was – die Art der Interaktion, die aufgetreten ist
  • Wann – der Zeitpunkt, zu dem die Interaktion stattgefunden hat

Um eine Kontaktaktivität aufzuzeichnen, muss eine Anwendung eine ContactAnnotation erstellen, die dem Kontakt zugeordnet ist, und SupportedOperations auf ContactAnnotationOperations.Activity setzen. Windows interpretiert Anmerkungen mit diesem Vorgangstyp als Interaktionssignale, die dem Kontakt zugeordnet sind.

Jede Aktivität stellt ein einzelnes Interaktionsereignis dar und sollte separat aufgezeichnet werden. Wenn Sie mehrere Kontaktaktivitäten übermitteln, durchlaufen Sie die Interaktionsdatensätze und rufen TrySaveAnnotationAsync für jedes Ereignis auf. Eine Schleife stellt keine Batch-API bereit und reduziert den Synchronisierungsaufwand nicht.

Nutzlast der Kontaktaktivität

Wenn Sie eine Kontaktaktivität aufzeichnen möchten, legen Sie ProviderProperties["ActivityPayload"] in der ContactAnnotation auf eine JSON-Zeichenfolge fest, die die Interaktion beschreibt.

Die Nutzlast muss die folgenden Eigenschaften enthalten:

Property Description
ActivityType Gibt den Typ der Interaktion an.
ActivityTimestampUnix Die Zeit, zu der die Interaktion erfolgte, ausgedrückt als UTC Unix-Zeit in Sekunden.

Verwenden Sie den Schlüssel ActivityPayload und die Nutzlasteigenschaftennamen ActivityType und ActivityTimestampUnix genau wie dargestellt. Diese Namen bilden den stringbasierten Vertrag zur Beschreibung der Aktivität.

Unterstützte Kontaktaktivitätstypen

Das ActivityType Feld gibt die Interaktion an, die zwischen dem Benutzer und dem Kontakt stattgefunden hat. Windows unterstützt derzeit die folgenden Aktivitätstypen.

Aktivitätstyp Description
message Senden oder empfangen Sie eine Nachricht mit dem Kontakt.
call Starten oder Beantworten eines Audio- oder Videoanrufs.
email Senden oder Empfangen einer E-Mail
meeting An einer Besprechung teilnehmen oder eine Besprechung unter Beteiligung des Kontakts planen.
share Inhalte mit dem Kontakt teilen
social Interaktion mit dem Kontakt über soziale Erlebnisse.
profileInteraction Öffnen des oder Interaktion mit dem Profil des Kontakts.

Anwendungen sollten den Aktivitätstyp auswählen, der die innerhalb der Anwendung stattgefundene Benutzerinteraktion am besten widerspiegelt.

Aufzeichnen eines Kontaktaktivitätsbeispiels

Das folgende Beispiel zeigt, wie eine Messaginginteraktion als Kontaktaktivität erfasst wird.

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 gibt zurück false , wenn die Anmerkung nicht gespeichert werden kann. Überprüfen Sie daher das Ergebnis, bevor Sie davon ausgehen, dass die Aktivität aufgezeichnet wurde. Ein true Ergebnis bedeutet, dass die Anmerkung gespeichert wurde. Es wird nicht angegeben, wie Windows die Aktivität später verarbeitet.

Zugriffsmodell für Kontaktaktivitäten

Kontaktaktivitäten sind aus Sicht Ihrer App nur schreibbar. Ihre App kann Aktivitätsdatensätze übermitteln, Windows unterstützt derzeit jedoch nicht das Abrufen oder explizites Löschen zuvor übermittelter Aktivitätsdatensätze. Windows-verwaltete Lebenszyklusbereinigung ist getrennt, wie im nächsten Abschnitt beschrieben.

Wenn Ihre App den Interaktionsverlauf beibehalten oder verwalten muss, speichern Sie ihn in Ihrem eigenen Speicher oder Backend-Dienst.

Lebenszyklus von Kontaktaktivitäten

Kontaktaktivitäten werden mithilfe der von der Anwendung bereitgestellten RemoteId mit Kontakten verknüpft.

Wenn ein Kontakt entfernt oder der zugeordnete RemoteId Kontakt gelöscht wird, werden die mit diesem Kontakt verknüpften Kontaktaktivitäten automatisch entfernt. Ebenso entfernt Windows, wenn eine Anwendung deinstalliert oder das zugehörige UserDataAccount entfernt wird, die Kontakte und Kontaktaktivitäten, die von dieser Anwendung aufgezeichnet werden, automatisch.

Verarbeitung und Aufbewahrung von Kontaktaktivitäten

Kontaktaktivitäten werden von Windows als Interaktionssignale verarbeitet.

Der Aufbewahrungszeitraum, der Ablauf (TTL), die Aggregation und die Auswertung von Kontaktaktivitäten werden intern von Windows verwaltet. Anwendungen steuern nicht, wie lange Aktivitäten gespeichert werden oder wie sie nach der Übermittlung verarbeitet werden.

Kontaktaktivitäten sollten echte Benutzerinteraktionen darstellen und nicht mit der Absicht generiert werden, die Kontaktrangfolge oder Sichtbarkeit zu beeinflussen. Windows bestimmt mithilfe interner Plattformlogik, wie diese Signale zu personenzentrierten Funktionen beitragen.

Verwandte Inhalte

  • Zuletzt aktualisiert um