Badging API：PWA 通知边界

PWA 徽标可以提示“有待处理工作”，却不会打开通知权限对话框；它也不是投递通道。BotBrowser 可以在授权页面中重放 navigator.setAppBadge() 和 navigator.clearAppBadge()，记录可见的能力分支；它不能添加 Badging API 支持、投递 Web Push，或证明私密计数适合暴露。涉及 service worker 的输入可参阅 Web Push 订阅生命周期与隐私，分享内容则属于 Web Share Target PWA 入口 的不同边界。

TL;DR

• setAppBadge() 在应用快捷方式上请求数字徽标或圆点；clearAppBadge() 移除该状态。
• 徽标只是展示提示，不会请求通知权限、唤醒 service worker、投递 push，也不证明用户已经查看工作。
• 使用有界且对用户有意义的计数。压缩大数字，排除标识符和敏感类别，在对应工作真正确认后清除。
• 检测 navigator.setAppBadge 与 navigator.clearAppBadge；不支持时提供诚实的应用内 fallback。
• 将 badge、Notification、PushManager 和服务器投递记录分开。

Contents

• 定义徽标契约
• 选择数字、圆点与清除时机
• 构建不支持时的 fallback
• 区分徽标、push 与通知
• 最小化计数并验证边界
• Practical conclusion

定义徽标契约

W3C Badging 规范 在 Navigator 上提供 setAppBadge() 与 clearAppBadge()。它们面向启动器或任务切换器中的应用表示，而不是任意 DOM 元素。操作系统可能显示数字、圆点或什么都不显示，取决于安装方式、浏览器和用户设置。promise 成功只表示浏览器接受了请求，不表示启动器已经绘制特定像素。

数字应该概括用户可以处理的待办工作。navigator.setAppBadge(3) 不会创建三条通知，也不能证明三条消息已经到达。不带参数的 navigator.setAppBadge() 请求非数字徽标。当精确数字未知或会泄露过多信息时使用圆点。MDN 的 setAppBadge() 与 clearAppBadge() 说明 API 契约，但不保证各平台绘制相同图形。

让一个状态所有者计算徽标。页面、worker 与后台同步不能从不同快照自行拼出计数。只记录 source、countKind、count、updatedAt、revision 和 outcome，不要记录标题、账号标识或正文。用单调 revision 丢弃旧更新，避免一个标签页清零后被旧缓存重新设为 4。

选择数字、圆点与清除时机

当数字能指导动作时才使用它，例如 7 个未读项目。后台重试或隐藏系统事件不是用户工作。把显示值限制为 99，然后改用圆点或应用内的 99+ 标签。 Chrome Badging API 介绍 展示常见 PWA 用法，但不替产品定义语义。

清除是状态转换，不是定时器。只有代表的工作被确认，或权威写入成功后，才调用 clearAppBadge()。打开收件箱不必然等于阅读。如果五项中确认两项，应从权威状态得到 3，不要在另一设备可能新增工作时直接从本地缓存减去两项。登出、切换账号或失去授权时清除徽标并删除账号范围的本地状态。

async function applyBadge(state) {
  const { revision, count, acknowledged, supported } = state;
  if (!supported || typeof navigator.setAppBadge !== 'function') {
    return { revision, outcome: 'unsupported', fallback: 'in-app-status' };
  }
  if (acknowledged || count === 0) {
    if (typeof navigator.clearAppBadge !== 'function') {
      return { revision, outcome: 'clear-unsupported', fallback: 'in-app-status' };
    }
    await navigator.clearAppBadge();
    return { revision, outcome: 'cleared' };
  }
  if (state.countKind === 'dot') {
    await navigator.setAppBadge();
    return { revision, outcome: 'dot' };
  }
  const bounded = Math.min(Math.max(0, count), 99);
  await navigator.setAppBadge(bounded);
  return { revision, outcome: 'number', count: bounded };
}

构建不支持时的 fallback

在每次使用时检查两个方法：

const canBadge = 'setAppBadge' in Navigator.prototype && 'clearAppBadge' in Navigator.prototype;

安全上下文、已安装模式、浏览器版本、操作系统集成和托管策略都会影响结果。MDN Badging API 指南记录可用性，但不授权通过改变别的应用图标来伪造启动器徽标。

不支持时，在应用内展示同一个有界状态：可访问的计数、更新后的标题或可见标记。清除语义也必须一致。不要用 Web Push 替代徽标：push 需要订阅、worker、权限和服务器，后台执行并不保证。支持诊断只需 { "capability": "absent", "fallback": "in-app-status" }，不要把私密会话文本放进长期日志。

区分徽标、push 与通知

Notification 请求显示系统通知的权限，而 Badging API 不会打开该对话框。Web Push 是向 service worker 提供投递机会，不是徽标状态。MDN Notification、Push API 与 MDN Push API 指南 描述的是不同表面。

表面	请求内容	不能证明	通常所有者
Badging API	本地数字或圆点	像素、投递、阅读	协调后的应用状态
Notification	权限与系统显示	注意力或阅读	页面或 worker
Web Push	投递机会	到达时间或应用状态	push 与 worker

push 可以更新最小化的本地记录，活动页面再根据权威未读状态协调徽标。不要用 push 事件数量当未读数量。通知显示也不等于确认，因此不能仅因显示通知就清除徽标。

最小化计数并验证边界

锁屏、任务切换器、截图或录屏上的数字都是数据披露。优先使用圆点、区间（1、2-5、6-20）或上限。授权后、调用前计算聚合，不要把用户 id 或会话 id 当作徽标参数。下面的 fixture 只验证分支选择：

const record = {
  fixtureId: 'badge-boundary-01',
  countKind: 'bounded',
  count: 3,
  revision: 18,
  outcome: 'pending',
};

try {
  if (typeof navigator.setAppBadge !== 'function') {
    record.outcome = 'unsupported';
  } else if (record.count === 0 && typeof navigator.clearAppBadge === 'function') {
    await navigator.clearAppBadge();
    record.outcome = 'cleared';
  } else if (record.count > 0) {
    await navigator.setAppBadge(Math.min(record.count, 99));
    record.outcome = 'number-requested';
  } else {
    record.outcome = 'clear-unsupported';
  }
} catch (error) {
  record.outcome = error.name === 'NotAllowedError' ? 'policy-error' : 'api-error';
}

分别在方法存在、方法缺失、确认工作后以及 promise 被拒绝后重放 fixture。保留 browserVersion、context、revision、countKind 和 outcome，不保留账号数据。BotBrowser 可以在授权上下文中捕获这些可见分支，但不能强制启动器绘制数字、授予通知权限、投递 push，或证明真实账号的计数没有隐私风险。它支持重放合成的 Badging API fixture 并记录 unsupported、number-requested 和 cleared 结果，但不能补上浏览器缺失的能力。浏览器、manifest 或 worker 改变后，比较第一个变化的字段。

{
  "fixtureId": "badge-boundary-01",
  "context": "installed-pwa",
  "revision": 18,
  "countKind": "bounded",
  "requestedCount": 3,
  "outcome": "number-requested"
}

公开来源

• W3C Badging 规范
• MDN：Badging API
• MDN：Navigator.setAppBadge()
• MDN：Navigator.clearAppBadge()
• Chrome Developers：Badging API
• MDN：Notification
• W3C Push API
• MDN：Push API
• MDN：PWA installation
• BotBrowser：自动化一致性

Practical conclusion

用 setAppBadge() 表示有界数字或圆点，并在工作被确认或状态完成协调后调用 clearAppBadge()。检测两个方法，保留可访问的应用内 fallback，只记录能力、revision 和 outcome。徽标、通知权限与 Web Push 投递彼此独立。BotBrowser 可以重放合成状态机，但启动器表现和隐私决策不在 fixture 证明范围内。先确定计数所有者和清除事件，再在浏览器或 worker 变化后重跑。