Registrera kontaktaktiviteter

Innan du börjar kan du bidra med dina kontakter till Windows.

Du kan registrera kontaktaktiviteter för att representera meningsfulla interaktioner mellan en användare och en kontakt i ditt program. Kontaktaktiviteter fungerar som lätta interaktionssignaler som hjälper Windows förstå hur användare interagerar med kontakter i personrelaterade upplevelser, till exempel People Widgets, Share Sheet och Windows Search Box i planerade faser.

Note

Referensen ContactAnnotationOperations listar för närvarande inte en Windows- eller SDK-version för värdet Activity, och den här artikeln anger inte vilka upplevelser som använder kontaktaktiviteter i dag. Versionshistoriken i referenslistorna anger Share (Windows 10 version 1703, SDK 15063) som det senaste dokumenterade värdet. Kontrollera API-referensen för uppdateringar innan du förlitar dig på Activity i en app som riktar sig till äldre SDK-versioner.

Varje aktivitet registrerar tre viktiga informationsdelar:

  • Vem – kontakten som var involverad i interaktionen
  • Vad – typen av interaktion som inträffade
  • När – tidpunkten då interaktionen inträffade

För att registrera en kontaktaktivitet måste ett program skapa en ContactAnnotation som är associerad med kontakten och ange SupportedOperations till ContactAnnotationOperations.Activity. Windows tolkar anteckningar med den här åtgärdstypen som interaktionssignaler som är associerade med kontakten.

Varje aktivitet representerar en enskild interaktionshändelse och bör registreras separat. När du skickar flera kontaktaktiviteter itererar du genom interaktionsposterna och anropar TrySaveAnnotationAsync för varje händelse. En loop tillhandahåller inte ett batch-API eller minskar inte synkroniseringskostnaderna.

Payload för kontaktaktivitet

Om du vill registrera en kontaktaktivitet anger du ProviderProperties["ActivityPayload"] på ContactAnnotation till en JSON-sträng som beskriver interaktionen.

Payloaden måste innehålla följande egenskaper:

Property Description
ActivityType Identifierar typ av interaktion.
ActivityTimestampUnix Tid då interaktionen inträffade, uttryckt som UTC Unix-tid i sekunder.

Använd nyckeln ActivityPayload och egenskapsnamnen för payloaden ActivityType och ActivityTimestampUnix exakt som visas. Dessa namn utgör det strängbaserade kontraktet för att beskriva aktiviteten.

Kontaktaktivitetstyper som stöds

Fältet ActivityType identifierar den interaktion som ägde rum mellan användaren och kontakten. Windows stöder för närvarande följande aktivitetstyper.

Aktivitetstyp Description
message Skicka eller ta emot ett meddelande med kontakten.
call Starta eller svara på ett ljud- eller videosamtal.
email Att skicka eller ta emot e-post.
meeting Ansluta till eller schemalägga ett möte som involverar kontakten.
share Dela innehåll med kontakten.
social Interagera med kontakten via sociala interaktioner.
profileInteraction Öppna eller interagera med kontaktens profil.

Applikationer bör välja den aktivitetstyp som bäst representerar användarinteraktionen som inträffade i applikationen.

Exempel på att registrera en kontaktaktivitet

I följande exempel visas hur du registrerar en meddelandeinteraktion som en kontaktaktivitet.

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 returnerar false när det inte kan spara anteckningen, så kontrollera resultatet innan du antar att aktiviteten har registrerats. Ett true resultat innebär att anteckningen sparades. Det anger inte hur Windows senare bearbetar aktiviteten.

Åtkomstmodell för kontaktaktiviteter

Kontaktaktiviteter är endast skrivbara från appens perspektiv. Din app kan skicka aktivitetsposter, men Windows stöder för närvarande inte hämtning eller explicit borttagning av tidigare skickade aktivitetsposter. Windows-hanterad livscykelrensning är separat, enligt beskrivningen i nästa avsnitt.

Om din app behöver behålla eller hantera interaktionshistorik behåller du den i din egen lagrings- eller backendtjänst.

Livscykel för kontaktaktiviteter

Kontaktaktiviteter associeras med kontakter med det programtillhandahållna RemoteId.

Om en kontakt tas bort eller om den associerade RemoteId tas bort tas kontaktaktiviteterna som är länkade till kontakten bort automatiskt. På samma sätt, när ett program avinstalleras eller dess associerade UserDataAccount tas bort, tar Windows automatiskt bort kontakter och kontaktaktiviteter som registrerats av programmet.

Bearbetning och lagring av kontaktaktiviteter

Kontaktåtgärder bearbetas av Windows som interaktionssignaler.

Kvarhållningsperioden, förfallotiden (TTL), aggregering och utvärdering av kontaktaktiviteter hanteras internt av Windows. Applikationer styr inte hur länge aktiviteter lagras eller hur de bearbetas efter inskickning.

Kontaktaktiviteter bör representera äkta användarinteraktioner och bör inte genereras i syfte att påverka kontaktrankning eller synlighet. Windows avgör hur dessa signaler bidrar till personrelaterade upplevelser med hjälp av intern plattformslogik.

Relaterat innehåll

  • Uppdaterades senast