Push Notifications

Send Web Push notifications to your users, and let the AI wire everything up.

Note

Real browser push delivery is available when your Proyecta Cloud environment has the web-push delivery adapter enabled (PUSH_DELIVERY_ADAPTER=web-push). With it on, a valid P-256 VAPID key pair is issued and notifications are delivered to subscribed browsers. When it’s off, everything still round-trips — subscriptions store and sends resolve — but the VAPID key is a placeholder, so no real deliveries are produced and messages are logged rather than pushed. If your pushes aren’t arriving, this adapter is the first thing to check.

Every Proyecta app can send browser and PWA push notifications to its users. Proyecta handles VAPID key generation, subscription storage, topic management, and delivery — no third-party account required.

How it works

Push notifications in Proyecta follow the standard Web Push lifecycle with four steps:

1. Enable — VAPID keys are generated for your app the first time they’re needed
2. Subscribe — register a visitor’s device to receive notifications
3. Identify — link an anonymous subscription to a signed-in user
4. Send — deliver a notification to specific users, topics, or everyone

The first three happen for you inside the usePush() hook; the fourth you do from your admin panel.

Subscribe a user’s device

Your app ships with a usePush() hook that handles the entire browser flow — fetching the VAPID key, registering the service worker, creating the Web Push subscription, storing the secret, and linking an anonymous subscription to the user once they sign in. You do not do any of that by hand:

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>
    );
}

There is also a ready-made block if you just want the opt-in prompt:

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

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

Ask the AI: "Add a 'Notify me' button to the header that opts the visitor into push."

Anonymous visitors are supported — the hook subscribes them with a generated id and re-links that subscription to their account automatically when they sign in, so a notification you send later reaches them either way.

Send a notification

Sending is an owner action, not something your app’s public pages do — a visitor’s browser must never be able to push to your whole audience. Day to day you send from the Push section of your app’s admin panel: write the title and body, pick a topic or broadcast to everyone, and send a test to your own device first.

You can target everyone, or just the visitors subscribed to a particular topic. A notification carries a title, a body, and optionally an icon and image.

After sending you get a count of how many devices it went to and how many failed. One caveat: those numbers only reflect real browser deliveries when the web-push delivery adapter is on. With it off, the count reflects how many stored subscriptions were targeted, not actual deliveries — so don’t read it as delivery confirmation in that case.

Topics

Visitors can subscribe to named topics (e.g. product-updates, weekly-digest) instead of a single all-or-nothing list. This is the recommended way to manage opt-ins — you don’t need to track visitor IDs yourself for broadcast-style updates. Topics show up as the audience picker in the admin panel’s Push section.

Unsubscribe

Call unsubscribe from the same usePush() hook — it already holds the subscription secret, so there is nothing for you to store or pass:

const { subscribed, unsubscribe } = usePush();

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

Let the AI wire it up

You don’t have to write any of this by hand. Ask the 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."

Caveats

• Preview doesn’t fire real pushes. Push notifications only work on the published version of your app because browsers require HTTPS on a real origin.
• iOS requires a PWA. On iOS 16.4+, Web Push only works from an installed Progressive Web App (added to the home screen), not from Safari directly.
• Permission is a one-shot. If a user denies notification permission, browsers don’t let you re-prompt programmatically. You have to guide them to their browser or device settings.

Coming soon

• Scheduled and event-triggered sends — send automatically based on app events or a schedule
• Deep linking — open a specific screen in the app when the notification is tapped