推送通知

向用户发送 Web Push 通知，让 AI 自动完成接入。

每个 Proyecta 应用都可以向用户发送浏览器和 PWA 推送通知。Proyecta 负责处理 VAPID 密钥生成、订阅存储、话题管理和消息投递，无需任何第三方账号。

工作原理

Proyecta 中的推送通知遵循标准 Web Push 生命周期，分为四个步骤：

启用（Enable） — 首次需要时，系统会为应用生成 VAPID 密钥
订阅（Subscribe） — 注册访客设备以接收通知
关联（Identify） — 将匿名订阅与已登录用户绑定
发送（Send） — 向特定用户、话题或所有人投递通知

前三步由 usePush() hook 自动为您完成；第四步则在管理面板中操作。

订阅用户设备

您的应用内置了一个 usePush() hook，它会处理整个浏览器端流程——获取 VAPID 密钥、注册 service worker、创建 Web Push 订阅、存储 secret，以及在用户登录后把匿名订阅关联到该用户。这些都无需您手动完成：

import { usePush } from '@/hooks/usePush.ts';

function NotifyMeButton() {
    const { supported, subscribed, subscribe, unsubscribe, isPending } = usePush();

    // `supported: false` means this browser cannot do push at all — hide the CTA.
    if (!supported) return null;

    return (
        <button onClick={subscribed ? unsubscribe : subscribe} disabled={isPending}>
            {subscribed ? 'Turn off notifications' : 'Notify me'}
        </button>
    );
}

如果您只想要一个现成的订阅提示，也可以直接使用内置区块：

import { PushOptInButton } from '@/components/blocks/PushOptInButton.tsx';

<PushOptInButton description="Get told the moment a new drop lands." />;

向 AI 提问："Add a 'Notify me' button to the header that opts the visitor into push."

匿名访客同样受支持——hook 会用一个生成的 id 为其订阅，并在他们登录后自动将该订阅重新关联到其账号，因此您之后发送的通知无论哪种情况都能送达。

发送通知

发送是所有者行为，而不是应用公开页面该做的事——绝不能让访客的浏览器向您的全体受众推送消息。日常发送请在应用管理面板的 Push 部分完成：填写标题和正文，选择一个话题或广播给所有人，并先向自己的设备发一条测试。

您可以定向所有人，也可以只定向订阅了某个特定话题的访客。一条通知包含标题、正文，以及可选的图标和图片。

发送后您会得到一个统计：投递到了多少台设备、失败了多少条。有一点需要注意：只有在启用了 web-push 投递适配器时，这些数值才反映真实的浏览器投递结果。未启用时，该数值反映的是被定向的已存储订阅数量，而非实际投递数——此时请勿将其作为投递确认的依据。

话题（Topics）

访客可以订阅命名话题（例如 product-updates、weekly-digest），而不是只有“全订/全不订”两种选择。对于广播式更新，这是管理订阅意愿的推荐方式——您无需自行追踪 visitor ID。话题会在管理面板 Push 部分中以受众选择器的形式出现。

取消订阅

从同一个 usePush() hook 调用 unsubscribe 即可——它已经持有订阅的 secret，您无需存储或传递任何东西：

const { subscribed, unsubscribe } = usePush();

{
    subscribed && <button onClick={unsubscribe}>Turn off notifications</button>;
}

让 AI 完成接入

您无需手动编写上述任何代码。直接向 AI 提问：

"Add a 'Notify me' button to the header that opts the visitor into push notifications."
"Put a push opt-in prompt on the product page, but only show it to visitors who haven't already subscribed."
"Add a topic called 'breaking-news' that visitors can opt into from the footer."

注意事项

Preview 环境不会发送真实推送。 推送通知仅在已发布版本的应用中有效，因为浏览器要求使用真实域名的 HTTPS。
iOS 需要 PWA。 在 iOS 16.4 及以上版本中，Web Push 仅在已安装的渐进式 Web 应用（已添加到主屏幕）中有效，无法直接从 Safari 使用。
权限申请只有一次机会。 如果用户拒绝了通知权限，浏览器不允许以编程方式重新弹出请求。您只能引导用户前往浏览器或设备设置中手动开启。

即将推出

定时发送与事件触发发送 — 根据应用事件或计划时间自动发送通知
深度链接（Deep linking） — 点击通知时直接跳转到应用内的特定页面