Notifications Push

Envoyez des notifications Web Push à vos utilisateurs. Configurez le SDK et laissez l’IA tout mettre en place.

Note

Les API de notifications push sont partiellement fonctionnelles au niveau du SDK — les abonnements sont enregistrés, et les appels d’envoi se résolvent sans erreur. Cependant, la distribution réelle des push vers le navigateur n’est pas encore activée en production : les clés VAPID renvoyées par enable() sont des octets aléatoires, et non des clés EC P-256 valides, ce qui entraînera l’échec de l’abonnement navigateur (pushManager.subscribe) jusqu’à l’activation de la distribution en production. Les messages sont enregistrés dans les logs mais ne sont pas envoyés aux appareils. La distribution en production arrive bientôt.

Chaque application Proyecta peut envoyer des notifications push navigateur et PWA à ses utilisateurs. Le SDK Proyecta gère la génération des clés VAPID, le stockage des abonnements, la gestion des topics et la distribution — aucun compte tiers requis.

Fonctionnement

Les notifications push dans Proyecta suivent le cycle de vie standard du Web Push en quatre étapes :

1. Enable — générer les clés VAPID pour votre application (opération unique)
2. Subscribe — enregistrer l’appareil d’un utilisateur pour recevoir des notifications
3. Identify — associer un abonnement anonyme à un utilisateur connecté
4. Send — envoyer une notification à des utilisateurs spécifiques, à des topics, ou à tout le monde

Ces quatre étapes sont accessibles via proyecta.pushNotifications dans le SDK.

Activer les push pour votre application

Le premier appel génère une clé publique VAPID dont le navigateur a besoin pour créer un abonnement. Il est idempotent — l’appeler à nouveau renvoie la même clé.

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

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

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

Demandez à l’IA : "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Abonner l’appareil d’un utilisateur

Côté client, créez un abonnement Web Push avec la clé VAPID, puis envoyez-le au serveur accompagné d’un 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

Utilisez l’identifiant de l’utilisateur authentifié comme visitorId si l’utilisateur est connecté, ou un UUID généré pour les visiteurs anonymes.

Associer des abonnements anonymes à des utilisateurs

Lorsqu’un visiteur anonyme se connecte, associez son abonnement existant à l’identifiant de l’utilisateur authentifié afin que le prochain send puisse le cibler :

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

Envoyer une notification

Vous pouvez cibler des identifiants de visiteurs spécifiques, des topics, les deux (en union), ou diffuser à tout le monde. Omettez visitorIds et topics pour une diffusion générale.

// 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 renvoie { sent, failed } pour vous indiquer comment s’est déroulée la distribution. Le compteur sent dans la réponse de stub actuelle reflète le nombre d’abonnements enregistrés ciblés, et non les livraisons réelles vers le navigateur — ne vous y fiez pas comme confirmation de distribution jusqu’à l’activation de la distribution en production.

Topics

Les utilisateurs peuvent s’abonner à des topics nommés (par ex. product-updates, weekly-digest) via la sous-ressource proyecta.pushNotifications.topics. C’est la méthode recommandée pour gérer les listes d’opt-in — vous n’avez pas besoin de suivre vous-même les identifiants de visiteurs pour les mises à jour de type diffusion.

Se désabonner

Supprimez un abonnement en utilisant le secret renvoyé par subscribe :

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

Laisser l’IA tout configurer

Vous n’avez pas à écrire tout cela manuellement. Demandez à l’IA :

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

Points d’attention

• Le preview n’envoie pas de vrais push. Les notifications push ne fonctionnent que sur la version publiée de votre application, car les navigateurs exigent HTTPS sur une origine réelle.
• iOS nécessite une PWA. Sur iOS 16.4+, le Web Push ne fonctionne qu’à partir d’une Progressive Web App installée (ajoutée à l’écran d’accueil), pas directement depuis Safari.
• La permission ne se demande qu’une fois. Si un utilisateur refuse l’autorisation de recevoir des notifications, les navigateurs ne permettent pas de redemander programmatiquement. Vous devez le guider vers les paramètres de son navigateur ou de son appareil.

Prochainement

• Envois planifiés et déclenchés par événements — envoyez automatiquement en fonction d’événements applicatifs ou d’un calendrier
• Deep linking — ouvrez un écran spécifique de l’application lorsque la notification est appuyée