SuperAPI AI 工具集

user-notifications

通用与其它

查看项目

更新于 11-11 12:24

技能介绍

用途

使用户能够从自己的 canister 向其应用用户发送通知,通知可在用户设备上显示,甚至当应用关闭时也能送达。Internet Identity 持有用户的设备并负责投递(以 web push 形式),因此应用无需自建推送服务、无需管理 VAPID 密钥或设备令牌。

主要能力

  • 通过 Internet Identity 申请用户通知同意,并在前端记录状态;
  • 从 canister 发送通知,指定标题、正文、URL、key、紧急程度、过期时间和 funnel;
  • 支持同一 key 的通知更新(替代新增)以及按 key 撤销通知;
  • 提供 metrics() 按小时报告通知管道状态;
  • 支持 Rust 和 Motoko 两种语言,Rust 库位于 crates.io,Motoko 库位于 Mops(需 moc 2.0.0 及以上)。

使用方式

使用前需先加载 user-sign-in 技能,因为发送者列表从应用的主源提供,该技能会选定该源。

三个必需部分:

  1. 前端通过 II 请求用户同意(需要 @icp-sdk/auth 11.1.0 或更高版本):
    • 调用 authClient.requestNotificationConsent() 打开 II 并返回 { granted };
    • 调用 authClient.getNotificationConsentStatus() 查询同意状态(未认证查询,适合渲染开关);
    • 调用 authClient.revokeNotificationConsent() 撤销同意(幂等,作用于当前应用)。 注意:granted: false 表示用户拒绝,不是错误;建议在点击事件中调用,不能使用 prompt: 'none';可与登录并行调用以节省一次 II 访问。
  2. 在应用的 /.well-known/ii-notification-senders 路径发布 JSON 文档,列出允许发送通知的 canister 列表。每个源最多 10 个 canister,超出会整体拒绝。II 会缓存该文档,添加或删除 canister 不会立即生效。缺少此文档会导致所有发送被拒绝且无错误提示。
  3. 在 canister 中使用 identity-notifications 库发送通知。Rust 需要 endpoints!() 和三个稳定的 MemoryId 传给 init;Motoko 通过 mixin 自带端点并管理状态,无需 memory id。配置通过环境变量提供:notification_sender(II canister)、notification_origin(应用源)、notification_capacity_mb(可选)。

通知字段包括:url(用户操作后的跳转地址,必须属于发送源或其替代源)、key(通知关联的主题,相同 key 的后续发送会更新现有通知)、urgency(VeryLow、Low、Normal、High,用于调度优先级)、expiresAt(有效期,默认较短,重要通知应显式设置更长的时间)、funnel(用于统计的标签)。urgency 和 expiresAt 需一起选择。

发送操作不会失败或阻塞调用,结果可通过 metrics() 查看。应用只负责寻址用户,投递细节由 II 和用户管理。显示内容中应用名称由 /.well-known/ii-app-metadata 提供,不要将应用名放入 title。iOS 需要将 II 添加到主屏幕才能使用 web push,同意流程会引导用户。

升级:Motoko 无需额外操作;Rust 必须在 post_upgrade 中再次调用 init,且每次使用相同的 MemoryIds,否则已排队的通知会丢失。

适用场景

需要在 Internet Computer 应用内向用户设备发送通知的场景,例如安全警报、新登录提醒、直接消息、配送通知、营销活动、摘要提醒等。

限制

  • 需要先加载 user-sign-in 技能;
  • 前端依赖 @icp-sdk/auth 11.1.0 以上;
  • 发送者文档最多列出 10 个 canister;
  • II 缓存发送者文档,变更不立即生效;
  • 通知的投递位置和方式由 II 和用户管理,应用无法控制;
  • 发送操作返回空,无法直接判断成功与否,需查看 metrics;
  • iOS 用户需将 II 添加到主屏幕才能接收 web push;
  • Rust canister 升级后必须再次调用 init,且 MemoryIds 不得变更。