Push Notifications

Send Web Push notifications to your users. Set up with the SDK and let the AI wire everything up.

Note

Push notification APIs are fully functional at the SDK level — VAPID keys generate, subscriptions store, and send calls return success. However, actual browser push delivery is not yet enabled in production. Messages are logged but not pushed to devices. Production delivery is coming soon.

Every Proyecta app can send browser and PWA push notifications to its users. The Proyecta SDK 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 — generate VAPID keys for your app (one-time)
2. Subscribe — register a user’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

All four live under proyecta.pushNotifications in the SDK.

Enable push for your app

The first call generates a VAPID public key that the browser needs to create a subscription. It’s idempotent — calling it again returns the same key.

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

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

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

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

Subscribe a user’s device

On the client, create a Web Push subscription with the VAPID key, then send it to the server along with a 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

Use an authenticated user ID as the visitorId if the user is signed in, or a generated UUID for anonymous visitors.

Link anonymous subscriptions to users

When an anonymous visitor signs in, link their existing subscription to the authenticated user ID so the next send can target them:

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

Send a notification

You can target specific visitor IDs, topics, both (as a union), or broadcast to everyone. Omit both visitorIds and topics to 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 returns { sent, failed } so you know how delivery went.

Topics

Users can subscribe to named topics (e.g. product-updates, weekly-digest) via the proyecta.pushNotifications.topics sub-resource. This is the recommended way to manage opt-in lists — you don’t need to track visitor IDs yourself for broadcast-style updates.

Unsubscribe

Remove a subscription using the secret returned from subscribe:

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

Let the AI wire it up

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

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