Powiadomienia Push

Wysyłaj powiadomienia Web Push do swoich użytkowników. Skonfiguruj za pomocą SDK i pozwól AI zająć się resztą.

Notatka

Interfejsy API powiadomień push są częściowo funkcjonalne na poziomie SDK — subskrypcje są zapisywane, a wywołania send kończą się bez błędu. Jednak rzeczywiste dostarczanie powiadomień push przez przeglądarkę nie jest jeszcze włączone w środowisku produkcyjnym: klucze VAPID zwracane przez enable() to losowe bajty, a nie prawidłowe klucze P-256 EC, więc subskrypcja przeglądarki (pushManager.subscribe) będzie kończyć się błędem do czasu włączenia produkcyjnego dostarczania. Wiadomości są logowane, ale nie są wysyłane do urządzeń. Produkcyjne dostarczanie powiadomień zostanie udostępnione wkrótce.

Każda aplikacja Proyecta może wysyłać powiadomienia push w przeglądarce i w aplikacjach PWA do swoich użytkowników. SDK Proyecta obsługuje generowanie kluczy VAPID, przechowywanie subskrypcji, zarządzanie tematami i dostarczanie powiadomień — bez potrzeby zakładania konta w zewnętrznych serwisach.

Jak to działa

Powiadomienia push w Proyecta działają zgodnie ze standardowym cyklem życia Web Push i obejmują cztery kroki:

1. Enable — wygenerowanie kluczy VAPID dla Twojej aplikacji (jednorazowo)
2. Subscribe — rejestracja urządzenia użytkownika do odbierania powiadomień
3. Identify — powiązanie anonimowej subskrypcji z zalogowanym użytkownikiem
4. Send — dostarczenie powiadomienia do konkretnych użytkowników, tematów lub do wszystkich

Wszystkie cztery operacje są dostępne pod proyecta.pushNotifications w SDK.

Włącz push dla swojej aplikacji

Pierwsze wywołanie generuje klucz publiczny VAPID, którego przeglądarka potrzebuje do utworzenia subskrypcji. Operacja jest idempotentna — kolejne wywołanie zwraca ten sam klucz.

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

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

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

Zapytaj AI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Subskrybowanie urządzenia użytkownika

Po stronie klienta utwórz subskrypcję Web Push przy użyciu klucza VAPID, a następnie wyślij ją na serwer razem z 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

Jako visitorId użyj ID zalogowanego użytkownika, jeśli jest zalogowany, lub wygenerowanego UUID dla anonimowych odwiedzających.

Łączenie anonimowych subskrypcji z użytkownikami

Gdy anonimowy użytkownik się zaloguje, powiąż jego istniejącą subskrypcję z ID zalogowanego użytkownika, aby kolejne wywołanie send mogło go docelować:

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

Wysyłanie powiadomienia

Możesz kierować powiadomienia do konkretnych identyfikatorów odwiedzających, tematów, obu jednocześnie (jako sumę), lub rozgłaszać do wszystkich. Pomiń zarówno visitorIds, jak i topics, aby wykonać 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 zwraca { sent, failed }, dzięki czemu wiesz, jak przebiegło dostarczanie. Liczba sent w bieżącej odpowiedzi stub odzwierciedla liczbę zaadresowanych zapisanych subskrypcji, a nie rzeczywistych dostarczeń do przeglądarki — nie należy na niej polegać jako potwierdzeniu dostarczenia do czasu włączenia produkcyjnego dostarczania.

Tematy

Użytkownicy mogą subskrybować nazwane tematy (np. product-updates, weekly-digest) za pośrednictwem podzasobu proyecta.pushNotifications.topics. To zalecany sposób zarządzania listami opt-in — nie musisz samodzielnie śledzić identyfikatorów odwiedzających na potrzeby aktualizacji w stylu broadcast.

Anulowanie subskrypcji

Usuń subskrypcję, używając sekretu zwróconego przez subscribe:

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

Pozwól AI zająć się konfiguracją

Nie musisz pisać tego wszystkiego ręcznie. Zapytaj 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."

Ograniczenia

• Preview nie wysyła prawdziwych powiadomień push. Powiadomienia push działają tylko w opublikowanej wersji Twojej aplikacji, ponieważ przeglądarki wymagają HTTPS na prawdziwym origin.
• iOS wymaga PWA. Na iOS 16.4+ Web Push działa wyłącznie z zainstalowanej Progressive Web App (dodanej do ekranu głównego), a nie bezpośrednio z Safari.
• Uprawnienie jest jednorazowe. Jeśli użytkownik odmówi uprawnienia do powiadomień, przeglądarki nie pozwalają ponownie wyświetlić monitu programowo. Musisz nakierować użytkownika na ustawienia przeglądarki lub urządzenia.

Wkrótce

• Wysyłanie zaplanowane i wyzwalane zdarzeniami — automatyczne wysyłanie na podstawie zdarzeń w aplikacji lub harmonogramu
• Deep linking — otwieranie konkretnego ekranu w aplikacji po kliknięciu powiadomienia