Contactactiviteiten vastleggen

Voordat u begint, voegt u uw contactpersonen toe aan Windows.

U kunt contactactiviteiten vastleggen om zinvolle interacties tussen een gebruiker en een contactpersoon in uw toepassing aan te geven. Contactactiviteiten fungeren als lichtgewicht interactiesignalen die Windows inzicht geven in hoe gebruikers in geplande fasen met contactpersonen omgaan via persoonsgerelateerde functies, zoals Personenwidgets, Share Sheet en Windows Zoekvak.

Note

De verwijzing ContactAnnotationOperations vermeldt momenteel geen Windows- of SDK-versie voor de Activity waarde en in dit artikel wordt niet vermeld welke ervaringen vandaag de dag contactactiviteiten gebruiken. De versiegeschiedenis in de referentie vermeldt Share (Windows 10 versie 1703, SDK 15063) als de meest recente gedocumenteerde waarde. Controleer de API-verwijzing op updates voordat u in een app die is gericht op oudere SDK-versies afhankelijk bent van Activity.

Elke activiteit registreert drie belangrijke gegevens:

  • Wie — de contactpersoon die betrokken is bij de interactie
  • Wat — het type interactie dat heeft plaatsgevonden
  • Wanneer — het tijdstip waarop de interactie heeft plaatsgevonden

Als u een contactactiviteit wilt vastleggen, moet een toepassing een ContactAnnotation maken die is gekoppeld aan de contactpersoon en SupportedOperations instellen op ContactAnnotationOperations.Activity. Windows interpreteert annotaties met dit bewerkingstype als interactiesignalen die aan de contactpersoon zijn gekoppeld.

Elke activiteit vertegenwoordigt één interactiegebeurtenis en moet afzonderlijk worden vastgelegd. Wanneer u meerdere contactactiviteiten verzendt, doorloopt u de interactierecords en roept u TrySaveAnnotationAsync aan voor elke gebeurtenis. Een lus biedt geen batch-API en vermindert de synchronisatie-overhead niet.

Payload van contactactiviteit

Als u een activiteit van een contactpersoon wilt opnemen, stelt u ProviderProperties["ActivityPayload"] op de ContactAnnotation in op een JSON-tekenreeks die de interactie beschrijft.

De payload moet de volgende eigenschappen bevatten:

Property Description
ActivityType Hiermee wordt het type interactie geïdentificeerd.
ActivityTimestampUnix Tijd waarop de interactie heeft plaatsgevonden, uitgedrukt als UTC Unix-tijd in seconden.

Gebruik de sleutel ActivityPayload en de eigenschapsnamen ActivityType van de payload en ActivityTimestampUnix precies zoals weergegeven. Deze namen vormen het op tekenreeks gebaseerde contract voor het beschrijven van de activiteit.

Ondersteunde typen contactactiviteiten

Het ActivityType veld identificeert de interactie die is opgetreden tussen de gebruiker en de contactpersoon. Windows ondersteunt momenteel de volgende activiteitstypen.

Activiteitstype Description
message Een bericht naar of van de contactpersoon verzenden of ontvangen.
call Een audio- of videogesprek starten of beantwoorden.
email Een e-mailbericht verzenden of ontvangen.
meeting Deelnemen aan of plannen van een vergadering waarbij de contactpersoon betrokken is.
share Inhoud delen met de contactpersoon.
social Interactie met het contact via sociale interacties.
profileInteraction Het profiel van de contactpersoon openen of ermee communiceren.

Aanvragen moeten het activiteitstype selecteren dat het beste de gebruikersinteractie vertegenwoordigt die in de toepassing is opgetreden.

Voorbeeld van het registreren van een contactactiviteit

In het volgende voorbeeld ziet u hoe u een berichtinteractie registreert als een contactactiviteit.

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 geeft false terug wanneer de aantekening niet kan worden opgeslagen, dus controleer het resultaat voordat u ervan uitgaat dat de activiteit is vastgelegd. Een true resultaat betekent dat de aantekening is opgeslagen. Het geeft niet aan hoe Windows later de activiteit verwerkt.

Toegangsmodel contactactiviteiten

Activiteiten van contactpersonen zijn alleen schrijven vanuit het perspectief van uw app. Uw app kan activiteitsrecords verzenden, maar Windows biedt momenteel geen ondersteuning voor het ophalen of expliciet verwijderen van eerder ingediende activiteitsrecords. Het opschonen van de door Windows beheerde levenscyclus staat los van, zoals beschreven in de volgende sectie.

Als uw app de interactiegeschiedenis moet behouden of beheren, moet u deze bewaren in uw eigen opslag- of back-endservice.

Levenscyclus van contactactiviteiten

Contactactiviteiten zijn gekoppeld aan contactpersonen met behulp van de door de toepassing geleverde RemoteId.

Als een contactpersoon wordt verwijderd of als de gekoppelde RemoteId wordt verwijderd, worden de contactactiviteiten die aan die contactpersoon zijn gekoppeld, automatisch verwijderd. Op dezelfde manier verwijdert Windows automatisch de contactpersonen en contactactiviteiten die door die toepassing zijn vastgelegd wanneer een toepassing wordt verwijderd of de bijbehorende UserDataAccount wordt verwijderd.

Verwerking en bewaring van contactactiviteiten

Contactactiviteiten worden verwerkt door Windows als interactiesignalen.

De bewaarperiode, vervaldatum (TTL), aggregatie en evaluatie van contactactiviteiten worden intern beheerd door Windows. Toepassingen bepalen niet hoe lang activiteiten worden opgeslagen of hoe ze worden verwerkt na verzending.

Contactactiviteiten moeten legitieme gebruikersinteracties vertegenwoordigen en mogen niet worden gegenereerd met de bedoeling om de contactrangschikking of zichtbaarheid te beïnvloeden. Windows bepaalt hoe deze signalen bijdragen aan mensengerelateerde ervaringen met behulp van interne platformlogica.

Verwante onderwerpen

  • Laatst bijgewerkt om