推送通知

向用户发送 Web Push 通知。通过 SDK 完成配置，让 AI 负责所有接线工作。

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

工作原理

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

启用（Enable） — 为您的应用生成 VAPID 密钥（仅需一次）
订阅（Subscribe） — 注册用户设备以接收通知
关联（Identify） — 将匿名订阅与已登录用户绑定
发送（Send） — 向特定用户、主题或全部用户投递通知

以上四个步骤均位于 SDK 的 proyecta.pushNotifications 下。

为应用启用推送

第一次调用会生成浏览器创建订阅所需的 VAPID 公钥。此操作是幂等的 — 重复调用将返回相同的密钥。

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

const { vapidPublicKey } = await proyecta.pushNotifications.enable();

您可以向 AI 说："Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var"。

订阅用户设备

在客户端，使用 VAPID 密钥创建一个 Web Push 订阅，然后将其连同 visitorId 一起发送到服务端：

// client side
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: PROYECTA_VAPID_PUBLIC_KEY,
});

// server side (or via your API route)
const { secret } = await proyecta.pushNotifications.subscribe({
    visitorId: currentUser?.id ?? generateAnonymousId(),
    subscription: {
        endpoint: subscription.endpoint,
        keys: {
            auth: subscription.keys.auth,
            p256dh: subscription.keys.p256dh,
        },
    },
});
// Store `secret` on the client — it's required to unsubscribe or identify later

如果用户已登录，请使用已认证的用户 ID 作为 visitorId；对于匿名访客，则使用生成的 UUID。

将匿名订阅关联到用户

当匿名访客登录时，将其现有订阅关联到已认证的用户 ID，以便下次 send 时能够精准触达：

await proyecta.pushNotifications.identify({
    secret: storedSubscriptionSecret,
    userId: authenticatedUser.id,
});

发送通知

您可以定向到特定访客 ID、主题、两者的并集，或向所有人广播。若同时省略 visitorIds 和 topics，则执行广播。

// Send to specific users
await proyecta.pushNotifications.send({
    title: 'Your order has shipped',
    body: 'Track it from your dashboard',
    visitorIds: ['user_123', 'user_456'],
    data: { orderId: 'ord_789' }, // custom payload
});

// Send to everyone subscribed to a topic
await proyecta.pushNotifications.send({
    title: 'New feature just dropped',
    topics: ['product-updates'],
    icon: 'https://cdn.example.com/icon.png',
    image: 'https://cdn.example.com/banner.png',
});

// Broadcast to all subscribers
await proyecta.pushNotifications.send({
    title: 'Scheduled maintenance at 2am UTC',
});

send 返回 { sent, failed }，便于您了解投递情况。当前 stub 响应中的 sent 计数反映的是目标存储订阅数量，而非实际的浏览器投递数量 — 在生产投递正式启用之前，请勿将其作为投递确认的依据。

主题

用户可以通过 proyecta.pushNotifications.topics 子资源订阅命名主题（例如 product-updates、weekly-digest）。对于广播式更新，这是管理用户自愿订阅列表的推荐方式 — 您无需自行追踪访客 ID。

取消订阅

使用 subscribe 返回的 secret 移除订阅：

await proyecta.pushNotifications.unsubscribe({ secret });

让 AI 完成接线

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

"Enable push notifications for my app. Register a service worker, call pushNotifications.subscribe on the client after the user grants permission, and store the secret in localStorage."
"Send a push to all users subscribed to the 'breaking-news' topic whenever a new article is published."
"After a user signs in, call pushNotifications.identify to link their anonymous subscription to their user ID."

注意事项

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

即将推出

定时与事件触发发送 — 根据应用事件或计划任务自动发送通知
深度链接（Deep linking） — 点击通知时直接打开应用中的特定页面