Rejestrowanie aktywności kontaktów

Przed rozpoczęciem dodaj swoje kontakty do systemu Windows.

Możesz rejestrować działania kontaktowe, aby reprezentować znaczące interakcje między użytkownikiem a kontaktem w aplikacji. Aktywności kontaktów stanowią lekkie sygnały interakcji, które pomagają systemowi Windows zrozumieć, jak użytkownicy korzystają z kontaktów w różnych obszarach związanych z kontaktami, takich jak People Widgets, Share Sheet i pole wyszukiwania systemu Windows, w planowanych fazach.

Note

Odwołanie ContactAnnotationOperations nie podaje obecnie wersji systemu Windows ani zestawu SDK dla wartości Activity, a w tym artykule nie stwierdza się, które funkcje korzystają dziś z działań kontaktowych. Historia wersji w dokumentacji referencyjnej wymienia Share (Windows 10 w wersji 1703, SDK 15063) jako najnowszą udokumentowaną wartość. Zapoznaj się z dokumentacją interfejsu API pod kątem aktualizacji, zanim użyjesz Activity w aplikacji przeznaczonej dla starszych wersji zestawu SDK.

Każde działanie rejestruje trzy kluczowe informacje:

  • Kto — kontakt uczestniczący w interakcji
  • Co — typ interakcji, który wystąpił
  • Kiedy — czas, w którym wystąpiła interakcja

Aby zarejestrować aktywność kontaktu, aplikacja musi utworzyć ContactAnnotation skojarzoną z kontaktem i ustawić SupportedOperations na ContactAnnotationOperations.Activity. Windows interpretuje adnotacje z tym typem operacji jako sygnały interakcji skojarzone z punktem kontaktu.

Każde działanie reprezentuje pojedyncze zdarzenie interakcji i powinno być rejestrowane oddzielnie. Podczas przesyłania wielu działań kontaktowych należy iterować rekordy interakcji i wywoływać TrySaveAnnotationAsync dla każdego zdarzenia. Pętla nie zapewnia interfejsu API wsadowego ani nie zmniejsza obciążenia związanego z synchronizacją.

Dane aktywności kontaktu

Aby zarejestrować aktywność kontaktu, ustaw ProviderProperties["ActivityPayload"] w elemencie ContactAnnotation na ciąg JSON opisujący interakcję.

Ładunek danych musi zawierać następujące właściwości:

Property Description
ActivityType Określa typ interakcji.
ActivityTimestampUnix Czas, kiedy wystąpiła interakcja, wyrażony jako czas UTC systemu Unix w sekundach.

Użyj klucza ActivityPayload i nazw właściwości payload ActivityType i ActivityTimestampUnix dokładnie tak, jak pokazano. Te nazwy tworzą opartą na ciągach znaków umowę służącą do opisywania aktywności.

Obsługiwane typy aktywności kontaktów

Pole ActivityType identyfikuje interakcję, która wystąpiła między użytkownikiem a kontaktem. Windows obecnie obsługuje następujące typy działań.

Typ aktywności Description
message Wysyłanie lub odbieranie wiadomości do lub od kontaktu.
call Uruchamianie lub odpowiadanie na połączenie audio lub wideo.
email Wysyłanie lub odbieranie wiadomości e-mail.
meeting Dołączanie do spotkania lub planowanie spotkania dotyczącego kontaktu.
share Udostępnianie zawartości kontaktowi.
social Interakcja z kontaktem za pośrednictwem doświadczeń społecznościowych.
profileInteraction Otwieranie profilu kontaktu lub interakcja z nim.

Należy wybrać typ działania, który najlepiej odzwierciedla interakcję użytkownika, do której doszło w aplikacji.

Przykład rejestrowania aktywności kontaktu

W poniższym przykładzie pokazano, jak zarejestrować interakcję związaną z wiadomościami jako aktywność kontaktową.

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 Zwraca wartość false , gdy nie może zapisać adnotacji, więc sprawdź wynik przed założeniem, że działanie zostało zarejestrowane. Wynik true oznacza, że adnotacja została zapisana. Nie wskazuje, jak Windows później przetwarza aktywność.

Model dostępu do aktywności kontaktu

Aktywności kontaktu są tylko do zapisu z perspektywy aplikacji. Aplikacja może przesyłać rekordy aktywności, ale Windows obecnie nie obsługuje pobierania ani jawnego usuwania wcześniej przesłanych rekordów aktywności. Oczyszczanie cyklu życia zarządzane przez system Windows jest oddzielne, zgodnie z opisem w następnej sekcji.

Jeśli aplikacja musi zachować historię interakcji lub zarządzać nią, zachowaj ją we własnym magazynie lub usłudze zaplecza.

Cykl życia aktywności kontaktu

Aktywności kontaktów są skojarzone z kontaktami przy użyciu udostępnionego przez aplikację RemoteId.

Jeśli kontakt zostanie usunięty lub skojarzony RemoteId zostanie usunięty, działania kontaktowe połączone z tym kontaktem zostaną automatycznie usunięte. Podobnie, gdy aplikacja zostanie odinstalowana lub gdy usunięty zostanie powiązany z nią UserDataAccount , Windows automatycznie usuwa kontakty i działania kontaktowe zarejestrowane przez aplikację.

Przetwarzanie i przechowywanie aktywności kontaktów

Akcje kontaktu są przetwarzane przez Windows jako sygnały interakcji.

Okres przechowywania, wygaśnięcie (TTL), agregacja i ocena aktywności kontaktów są zarządzane wewnętrznie przez Windows. Aplikacje nie kontrolują czasu przechowywania aktywności ani sposobu ich przetwarzania po przesłaniu.

Aktywności kontaktu powinny reprezentować prawdziwe interakcje użytkowników i nie powinny być generowane z zamiarem wywierania wpływu na klasyfikację kontaktów lub widoczność. Windows określa, w jaki sposób te sygnały przyczyniają się do funkcji związanych z użytkownikami przy użyciu wewnętrznej logiki platformy.

Treści powiązane

  • Ostatnia aktualizacja o