Push-уведомления

Отправляйте Web Push-уведомления своим пользователям. Настройте через SDK и позвольте ИИ сделать всё остальное.

Заметка

Push-уведомления на уровне SDK работают частично — подписки сохраняются, а вызовы send завершаются без ошибок. Однако реальная доставка push-уведомлений в браузер пока не включена в production: VAPID-ключи, возвращаемые enable(), представляют собой случайные байты, а не корректные P-256 EC-ключи, поэтому подписка браузера (pushManager.subscribe) будет завершаться ошибкой до тех пор, пока не будет включена production-доставка. Сообщения логируются, но не отправляются на устройства. Production-доставка появится в ближайшее время.

Каждое приложение Proyecta может отправлять push-уведомления в браузер и PWA своим пользователям. Proyecta SDK берёт на себя генерацию VAPID-ключей, хранение подписок, управление топиками и доставку — сторонние аккаунты не требуются.

Как это работает

Push-уведомления в Proyecta следуют стандартному жизненному циклу Web Push и включают четыре шага:

1. Enable — генерация VAPID-ключей для вашего приложения (выполняется один раз)
2. Subscribe — регистрация устройства пользователя для получения уведомлений
3. Identify — связывание анонимной подписки с авторизованным пользователем
4. Send — доставка уведомления конкретным пользователям, топикам или всем сразу

Все четыре метода находятся в proyecta.pushNotifications внутри SDK.

Включите push для вашего приложения

Первый вызов генерирует VAPID-публичный ключ, который браузер использует для создания подписки. Метод идемпотентен — повторный вызов вернёт тот же ключ.

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

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

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

Спросите ИИ: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Подпишите устройство пользователя

На клиенте создайте Web Push-подписку с VAPID-ключом, затем отправьте её на сервер вместе с 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,
});

Отправьте уведомление

Вы можете адресовать уведомление конкретным visitor 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 }, чтобы вы знали, как прошла доставка. Значение sent в текущем stub-ответе отражает количество сохранённых подписок, которым было адресовано уведомление, а не реальное число доставок в браузер — не используйте его как подтверждение доставки до тех пор, пока не будет включена production-доставка.

Топики

Пользователи могут подписываться на именованные топики (например, product-updates, weekly-digest) через вложенный ресурс proyecta.pushNotifications.topics. Это рекомендуемый способ управления списками opt-in — вам не нужно самостоятельно отслеживать visitor ID для широковещательных рассылок.

Отписка

Удалите подписку с помощью secret, полученного из subscribe:

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

Позвольте ИИ всё настроить

Вам не нужно писать всё это вручную. Спросите ИИ:

• "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 реальные push не отправляются. Push-уведомления работают только в опубликованной версии вашего приложения, поскольку браузеры требуют HTTPS на реальном origin.
• На iOS требуется PWA. На iOS 16.4+ Web Push работает только из установленного Progressive Web App (добавленного на главный экран), но не из Safari напрямую.
• Разрешение запрашивается один раз. Если пользователь отклонил разрешение на уведомления, браузеры не позволяют запросить его повторно программно. Вам придётся направить пользователя в настройки браузера или устройства.

Скоро

• Запланированная и событийная отправка — автоматическая отправка на основе событий приложения или по расписанию
• Deep linking — открытие конкретного экрана в приложении при нажатии на уведомление