Windows Share 的聯絡人排名

應用程式可以透過為 Windows 分享新增聯絡人註解,為其熱門聯絡人設定排名。 本文將介紹建立註解清單、使用 Share 作業儲存排名、更新排名清單,以及排名最佳實務。

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

儲存聯絡人的排名

您可以為 UserDataAccount 建立 批注清單,以儲存聯繫人的排名。 應用程式可以將批註新增至聯繫人,以儲存其最上層聯繫人的排名。 這些批注會儲存為聯繫人存放區中批注清單的一部分。

ContactAnnotationStore annotationStore = await
    ContactManager.RequestAnnotationStoreAsync(ContactAnnotationStoreAccessType.AppAnnotationsReadWrite);
this.contactAnnotationList = await annotationStore.CreateAnnotationListAsync(uda.Id);

您可以使用連絡人上的批注來儲存最上層聯絡人的排名。 排名會儲存在聯繫人批注的 ProviderProperties 中。 除了排名之外,應用程式必須將 SupportedOperations 設定在聯絡人標註上為 Share。

foreach (var appContact in topAppContacts)
{
  Contact contact = await list.GetContactFromRemoteIdAsync(topAppContact.RemoteID);
  var annotation = new ContactAnnotation
  {
    ContactId = contact.Id,
    SupportedOperations = ContactAnnotationOperations.Share
  };
  annotation.ProviderProperties.Add("Rank", rank);
  await this.contactAnnotationList.TrySaveAnnotationAsync(annotation);
}

排名值參考資料

層面 Guidance
屬性索引鍵 "Rank" 在註解的 ProviderProperties 字典中
值類型 非負整數。
方向 較低的數值在你的應用程式清單中會優先顯示。 等級為 0 並不代表「忽略」;它遵循相同的低值優先排序。
唯一性 為名單中的每個聯絡人分配獨特的名次。 重複排名的行為並未明確說明。
Scope 你的應用程式排名僅表示你自己清單中的優先順序。 Windows 會讀取所有Share註解,並根據使用情況使用內部邏輯來跨應用程式排序聯絡人。 閱讀所有註解與 Windows 顯示的建議數量是分開的。
誰來定義價值 你的應用程式。 選擇如何計算,例如根據互動的近期性和頻率。

更新連絡人排名

在更新儲存在 Windows 中的連絡人排名時,應用程式會自行決定。 Windows 建議定期更新排名清單,以提供最佳的用戶體驗。 每當您需要更新排名清單時,都必須遵循數個步驟。

  1. 刪除 ContactAnnotationList。

    一旦應用程式有已更新的頂端聯繫人清單,就可以刪除批注清單,並建立具有其頂端聯繫人更新批注的新批注清單。

    await this.contactAnnotationList.DeleteAsync();
    
  2. 請建立新的 ContactAnnotationList。 請遵循 [儲存聯繫人的排名] 區段中的步驟,為您的最上層聯繫人建立新的批注清單和儲存排名。

排名最佳實務

為了最大化你應用程式聯絡人在分享名單建議欄中的相關性,請遵循以下排名原則:

依新近性與頻率排序

排名可由以下組合計算:

  • 最近互動時間:使用者上次與各聯絡人互動的時間
  • 頻率:使用者與每個聯絡人互動的頻率

因為較低的排名值優先,請依分數從高到低排序聯絡人,並依序分配1、2、3等排名。 例如,使用者昨天傳訊息給的聯絡人可能會被評為 1,而使用者兩週前傳訊息給的聯絡人可能會被評為第 5 位。

// lastInteraction and interactionCount come from your app's own interaction
// telemetry. The Windows Contact class does not expose interaction history.
private int CalculateScore(DateTime lastInteraction, int interactionCount)
{
    TimeSpan daysSinceLastInteraction = DateTime.Now - lastInteraction;
    int frequencyScore = interactionCount * 10; // Max ~100
    int recencyScore = Math.Max(0, 100 - (daysSinceLastInteraction.Days * 3));

    return (recencyScore + frequencyScore) / 2;
}

// A higher score means a more relevant contact, so it gets a lower rank value.
// Assign unique ranks 1, 2, 3, ... in descending score order.
var rankedContacts = this.AllTrackedContacts
    .OrderByDescending(c => CalculateScore(c.LastInteractionDate, c.InteractionCount))
    .Select((c, index) => (Contact: c, Rank: index + 1));

移除過期的聯絡人

用戶30+天內未互動的聯絡人應該從你的排名列表中移除。 這讓建議保持新鮮且相關性:

// Exclude stale contacts when you rebuild the ranked list. Don't save a rank of 0
// for them: lower values take precedence, so 0 is the highest priority.
var staleCutoff = DateTime.Now.AddDays(-30);
var activeContacts = this.AllTrackedContacts
    .Where(c => c.LastInteractionDate >= staleCutoff);

定期更新排名

依照你的應用程式安排排名更新的節奏——訊息應用程式是每日更新,電子郵件是每週更新,行事曆應用程式則是每月更新。 必要時使用背景任務:

// Example: Update ranks when the app comes to foreground or on a timer
private async void UpdateRanksOnAppActivated()
{
    var topContacts = GetTopContactsByRecentActivity(50);
    await UpdateAnnotationRanksAsync(topContacts);
}

建議欄的核對清單

當你依照上述指引排名並維護聯絡人時,使用者會在 Windows 分享表的建議欄看到你應用程式的熱門聯絡人。 此路徑目前支援 People 聯絡人。

為確保您的聯絡人顯示:

  1. 使用UserDataAccount建立DisplayName = "com.microsoft.peoplecontract"
  2. 儲存包含必填欄位(FirstName、RemoteId、DisplayPicture)的聯絡人
  3. 建立具有等級的 ContactAnnotationList(較低的數值優先)
  4. 在每個註解上設定SupportedOperations = Share
  5. 更新會根據更新頻率和頻率定期排序
  6. 從你的排名列表中移除使用者在 30 天以上未互動的聯絡人

請參閱「 從你的應用程式分享內容 」和 「在你的應用程式中接收內容 」,以了解完整的分享工作表整合指南。