Push-Benachrichtigungen

Sende Web-Push-Benachrichtigungen an deine Nutzer. Richte es mit dem SDK ein und lass die KI den Rest erledigen.

Hinweis

Push-Benachrichtigungs-APIs sind auf SDK-Ebene teilweise funktionsfähig – Abonnements werden gespeichert, und Send-Aufrufe werden ohne Fehler aufgelöst. Die tatsächliche Browser-Push-Zustellung ist in der Produktion jedoch noch nicht aktiviert: Die von enable() zurückgegebenen VAPID-Schlüssel sind zufällige Bytes und keine gültigen P-256-EC-Schlüssel, sodass das Browser-Abonnement (pushManager.subscribe) fehlschlägt, bis die Produktionszustellung aktiviert ist. Nachrichten werden protokolliert, aber nicht an Geräte gesendet. Die Produktionszustellung ist in Kürze verfügbar.

Jede Proyecta-App kann Browser- und PWA-Push-Benachrichtigungen an ihre Nutzer senden. Das Proyecta SDK übernimmt die VAPID-Schlüsselgenerierung, Abonnementspeicherung, Themenverwaltung und Zustellung – kein Drittanbieter-Konto erforderlich.

So funktioniert es

Push-Benachrichtigungen in Proyecta folgen dem Standard-Web-Push-Lebenszyklus in vier Schritten:

1. Enable — VAPID-Schlüssel für deine App generieren (einmalig)
2. Subscribe — Das Gerät eines Nutzers für den Empfang von Benachrichtigungen registrieren
3. Identify — Ein anonymes Abonnement mit einem angemeldeten Nutzer verknüpfen
4. Send — Eine Benachrichtigung an bestimmte Nutzer, Themen oder alle zustellen

Alle vier sind unter proyecta.pushNotifications im SDK verfügbar.

Push für deine App aktivieren

Der erste Aufruf generiert einen öffentlichen VAPID-Schlüssel, den der Browser zum Erstellen eines Abonnements benötigt. Er ist idempotent – ein erneuter Aufruf gibt denselben Schlüssel zurück.

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

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

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

Frag die KI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Das Gerät eines Nutzers abonnieren

Erstelle auf dem Client ein Web-Push-Abonnement mit dem VAPID-Schlüssel und sende es zusammen mit einer visitorId an den Server:

// 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

Verwende eine authentifizierte Nutzer-ID als visitorId, wenn der Nutzer angemeldet ist, oder eine generierte UUID für anonyme Besucher.

Anonyme Abonnements mit Nutzern verknüpfen

Wenn sich ein anonymer Besucher anmeldet, verknüpfe sein bestehendes Abonnement mit der authentifizierten Nutzer-ID, damit der nächste send-Aufruf ihn gezielt ansprechen kann:

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

Eine Benachrichtigung senden

Du kannst bestimmte Besucher-IDs, Themen, beides (als Vereinigung) oder eine Broadcast-Nachricht an alle senden. Lasse sowohl visitorIds als auch topics weg, um eine Broadcast-Nachricht zu senden.

// 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 gibt { sent, failed } zurück, damit du weißt, wie die Zustellung verlaufen ist. Der sent-Zähler in der aktuellen Stub-Antwort gibt die Anzahl der angesprochenen gespeicherten Abonnements wieder, nicht die tatsächlichen Browser-Zustellungen – verlasse dich nicht darauf als Zustellungsbestätigung, bis die Produktionszustellung aktiviert ist.

Themen

Nutzer können benannte Themen abonnieren (z. B. product-updates, weekly-digest) über die Unterressource proyecta.pushNotifications.topics. Dies ist die empfohlene Methode zur Verwaltung von Opt-in-Listen – du musst Besucher-IDs nicht selbst für broadcast-artige Updates verfolgen.

Abonnement kündigen

Entferne ein Abonnement mithilfe des von subscribe zurückgegebenen Secrets:

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

Lass die KI alles verdrahten

Du musst nichts davon manuell schreiben. Frag die KI:

• "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."

Einschränkungen

• Vorschauen senden keine echten Push-Nachrichten. Push-Benachrichtigungen funktionieren nur in der veröffentlichten Version deiner App, da Browser HTTPS auf einem echten Origin voraussetzen.
• iOS erfordert eine PWA. Auf iOS 16.4+ funktioniert Web Push nur aus einer installierten Progressive Web App (zum Startbildschirm hinzugefügt), nicht direkt aus Safari.
• Die Berechtigung ist einmalig. Wenn ein Nutzer die Benachrichtigungsberechtigung verweigert, erlauben Browser keine erneute programmatische Abfrage. Du musst die Nutzer zu ihren Browser- oder Geräteeinstellungen führen.

Demnächst verfügbar

• Geplante und ereignisgesteuerte Sends — automatisch basierend auf App-Ereignissen oder einem Zeitplan senden
• Deep Linking — einen bestimmten Bildschirm in der App öffnen, wenn die Benachrichtigung angetippt wird