應用程式可以透過為 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 建議定期更新排名清單,以提供最佳的用戶體驗。 每當您需要更新排名清單時,都必須遵循數個步驟。
-
一旦應用程式有已更新的頂端聯繫人清單,就可以刪除批注清單,並建立具有其頂端聯繫人更新批注的新批注清單。
await this.contactAnnotationList.DeleteAsync(); 請建立新的
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 聯絡人。
為確保您的聯絡人顯示:
- 使用
UserDataAccount建立DisplayName = "com.microsoft.peoplecontract" - 儲存包含必填欄位(
FirstName、RemoteId、DisplayPicture)的聯絡人 - 建立具有等級的
ContactAnnotationList(較低的數值優先) - 在每個註解上設定
SupportedOperations = Share - 更新會根據更新頻率和頻率定期排序
- 從你的排名列表中移除使用者在 30 天以上未互動的聯絡人
請參閱「 從你的應用程式分享內容 」和 「在你的應用程式中接收內容 」,以了解完整的分享工作表整合指南。