記錄聯絡活動

開始之前,請先將你的聯絡人新增到 Windows。

你可以記錄聯絡活動,以代表應用程式中使用者與聯絡人之間有意義的互動。 聯絡活動作為輕量級互動訊號,幫助 Windows 了解使用者如何在與人相關的體驗(如 People Widgets、Share Sheet 和 Windows Search Box)中,於規劃中的各階段與聯絡人互動。

Note

ContactAnnotationOperations 參考文獻目前沒有列出該Activity值的 Windows 或 SDK 版本,這篇文章也未說明目前哪些經驗使用聯絡活動。 參考資料中的版本歷程將 Share(Windows 10 版本 1703,SDK 15063)列為最近記錄的值。 在針對舊版 SDK 的應用程式中依賴 Activity 之前,請先查看 API 參考的更新。

每個活動記錄三個關鍵資訊:

  • 誰 ——互動中涉及的聯絡人
  • 內容 —— 發生的互動類型
  • 當 ——互動發生的時間點

要記錄聯絡活動,應用程式必須建立與該聯絡人相關的 ContactAnnotation ,並設定 SupportedOperations 為 ContactAnnotationOperations.Activity。 Windows 將帶有此操作類型的註解解讀為與接觸點相關的互動訊號。

每個活動代表單一互動事件,應分別記錄。 提交多個聯絡活動時,逐一檢視互動紀錄並針對每個事件呼叫 TrySaveAnnotationAsync。 迴圈不會提供批次 API,也不會降低同步的開銷。

聯絡人活動酬載

要記錄聯絡活動,請在 ProviderProperties["ActivityPayload"] 上設定 ,使其成為描述互動的 JSON 字串。

承載資料必須包含以下屬性:

Property Description
ActivityType 辨識互動類型。
ActivityTimestampUnix 互動發生的時間,以 UTC Unix 時間(秒)表示。

使用金鑰 ActivityPayload 和有效載荷屬性名稱 ActivityType 與 ActivityTimestampUnix,完全按照顯示的方式。 這些名稱構成了描述活動的字串契約。

支援的聯絡活動類型

該 ActivityType 欄位識別使用者與聯絡人之間發生的互動。 Windows 目前支援以下活動類型。

活動類型 Description
message 與聯絡人傳送或接收訊息。
call 開始或接聽音訊或視訊通話。
email 發送或接收電子郵件。
meeting 加入或安排涉及該聯絡人的會議。
share 與聯絡人分享內容。
social 透過社群體驗與接觸者互動。
profileInteraction 開啟或互動聯絡人的個人檔案。

應用程式應選擇最能代表在應用程式內發生的使用者互動的活動類型。

記錄聯絡人活動範例

以下範例說明如何將訊息互動記錄為聯絡活動。

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 當無法儲存註解時會回傳 false ,所以在假設活動被記錄前,請先檢查結果。 結果 true 表示註解已被保存。 它沒有說明 Windows 之後如何處理這些活動。

連絡人活動存取模型

從應用程式的角度來看,聯絡人活動是只能寫入的。 你的應用程式可以提交活動紀錄,但 Windows 目前不支援擷取或明確刪除先前提交的活動記錄。 Windows 管理的生命週期管理清理則是分開的,詳見下一節。

如果你的應用程式需要保留或管理互動歷史,請將其保存在自己的儲存空間或後端服務中。

聯絡人活動生命週期

聯絡活動會使用應用程式提供的 RemoteId 與聯絡人相關聯。

如果聯絡人被移除或關聯的 RemoteId 被刪除,與該聯絡人連結的活動會自動移除。 同樣地,當應用程式被移除或其關聯的 UserDataAccount 被移除時,Windows 會自動移除該應用程式記錄的聯絡人及聯絡人活動。

聯絡人活動處理與保留

聯絡人活動由 Windows 作為互動訊號處理。

保留期間、到期(TTL)、彙總及聯繫人活動評估皆由 Windows 內部管理。 應用程式無法控制活動儲存的時間長短,也無法控制提交後的處理方式。

聯絡活動應代表真實的用戶互動,且不應為了影響聯絡人排名或能見度而產生。 Windows 利用內部平台邏輯判斷這些訊號如何影響與人相關的體驗。