在开始之前,将联系人添加到 Windows。
可以记录联系人活动,以表示用户与应用程序中的联系人之间的有意义的交互。 联系人活动作为轻量级交互信号,帮助 Windows 了解用户如何在人员小组件、共享工作表和 Windows 搜索框等与人员相关的体验中与联系人互动,这些体验将按计划分阶段推出。
Note
ContactAnnotationOperations 参考当前未列出 Activity 值对应的 Windows 或 SDK 版本,本文也未说明目前哪些体验会使用联系人活动。 参考中的版本历史将Share(Windows 10 版本 1703,SDK 15063)列为最新记录的值。 在面向较旧 SDK 版本的应用中依赖 Activity 之前,先检查 API 参考以获取更新。
每个活动记录三个关键信息片段:
- 谁 — 参与交互的联系人
- 什么 — 发生的交互类型
- 何时 - 发生交互的时间
若要记录联系人活动,应用程序必须创建与联系人关联的 ContactAnnotation,并将 SupportedOperations 设置为 ContactAnnotationOperations.Activity。 Windows 将此操作类型的批注解释为与联系人关联的交互信号。
每个活动表示单个交互事件,应单独记录。 提交多个联系人活动时,请遍历交互记录,并为每个事件调用 TrySaveAnnotationAsync。 循环既不提供批处理 API,也不会减少同步开销。
联系人活动有效负载
若要记录联系人活动,请将 ContactAnnotation 上的 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 使用内部平台逻辑来确定这些信号如何影响以人为中心的体验。