Push-сповіщення

Надсилайте Web Push сповіщення своїм користувачам. Налаштуйте через SDK, а AI подбає про решту.

Заувага

Push-сповіщення частково працюють на рівні SDK — підписки зберігаються, а виклики надсилання завершуються без помилок. Однак фактична доставка push-повідомлень у браузері ще не ввімкнена в production: VAPID-ключі, які повертає enable(), є випадковими байтами, а не валідними P-256 EC ключами, тому підписка у браузері (pushManager.subscribe) не спрацює, доки production-доставку не буде увімкнено. Повідомлення логуються, але не доставляються на пристрої. Production-доставка з’явиться найближчим часом.

Кожен застосунок Proyecta може надсилати браузерні push-сповіщення та push-сповіщення PWA своїм користувачам. SDK Proyecta бере на себе генерацію 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();

Запитайте AI: "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,
});

Надсилання сповіщення

Ви можете вказати конкретні ID відвідувачів, теми, і те й інше (як об’єднання) або виконати розсилку всім. Якщо не вказати ні visitorIds, ні topics, буде виконано broadcast.

// 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 у поточній заглушці відображає кількість збережених підписок, охоплених надсиланням, а не фактичну доставку у браузері — не використовуйте його як підтвердження доставки, доки production-доставку не буде увімкнено.

Теми

Користувачі можуть підписуватися на іменовані теми (наприклад, product-updates, weekly-digest) через під-ресурс proyecta.pushNotifications.topics. Це рекомендований спосіб керування списками opt-in — вам не потрібно самостійно відстежувати ID відвідувачів для broadcast-розсилок.

Відписка

Видаліть підписку за допомогою секрету, отриманого від subscribe:

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 не надсилає реальні push-повідомлення. Push-сповіщення працюють лише в опублікованій версії вашого застосунку, оскільки браузери вимагають HTTPS на реальному origin.
• iOS потребує PWA. На iOS 16.4+, Web Push працює лише з встановленого Progressive Web App (доданого на головний екран), а не безпосередньо з Safari.
• Дозвіл запитується один раз. Якщо користувач відхиляє дозвіл на сповіщення, браузери не дозволяють повторно запитати його програмно. Потрібно направити користувача до налаштувань браузера або пристрою.

Найближчим часом

• Заплановані та подієво-тригерні надсилання — автоматичне надсилання на основі подій у застосунку або за розкладом
• Deep linking — відкриття конкретного екрана в застосунку під час натискання на сповіщення