התראות Push

שלח התראות Web Push למשתמשים שלך. הגדר עם ה-SDK ותן ל-AI לחבר את הכל.

Note

ממשקי API של התראות push פועלים באופן חלקי ברמת ה-SDK — מנויים נשמרים, וקריאות send מסתיימות ללא שגיאה. עם זאת, משלוח push בפועל לדפדפן אינו מופעל עדיין בסביבת הייצור: מפתחות ה-VAPID שמוחזרים על ידי enable() הם בייטים אקראיים ולא מפתחות P-256 EC תקינים, לכן הרשמת הדפדפן (pushManager.subscribe) תיכשל עד שמשלוח הייצור יופעל. הודעות נרשמות ביומן אך אינן נשלחות למכשירים. משלוח ייצור יגיע בקרוב.

כל אפליקציית Proyecta יכולה לשלוח התראות push לדפדפן וכ-PWA למשתמשים שלה. ה-SDK של Proyecta מטפל ביצירת מפתחות VAPID, שמירת מנויים, ניהול נושאים ומשלוח — ללא צורך בחשבון צד שלישי.

איך זה עובד

התראות push ב-Proyecta עוקבות אחר מחזור החיים הסטנדרטי של Web Push בארבעה שלבים:

1. Enable — צור מפתחות VAPID לאפליקציה שלך (פעם אחת)
2. Subscribe — רשום את מכשיר המשתמש לקבלת התראות
3. Identify — קשר מנוי אנונימי למשתמש מחובר
4. Send — שלח התראה למשתמשים ספציפיים, לנושאים, או לכולם

כל ארבעת הפעולות נמצאות תחת proyecta.pushNotifications ב-SDK.

הפעל push לאפליקציה שלך

הקריאה הראשונה יוצרת מפתח VAPID ציבורי שהדפדפן צריך כדי ליצור מנוי. היא idempotent — קריאה חוזרת מחזירה את אותו מפתח.

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

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

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

שאל את ה-AI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

הרשם את מכשיר המשתמש

בצד הלקוח, צור מנוי Web Push עם מפתח ה-VAPID, ואז שלח אותו לשרת יחד עם 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

השתמש במזהה משתמש מאומת כ-visitorId אם המשתמש מחובר, או ב-UUID שנוצר עבור מבקרים אנונימיים.

קשר מנויים אנונימיים למשתמשים

כאשר מבקר אנונימי מתחבר, קשר את המנוי הקיים שלו למזהה המשתמש המאומת כדי שהקריאה הבאה ל-send תוכל למקד אותו:

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

שלח התראה

ניתן למקד מזהי מבקרים ספציפיים, נושאים, שניהם יחד (כאיחוד), או לשדר לכולם. השמט גם visitorIds וגם topics כדי לשדר.

// 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 מחזיר { sent, failed } כדי שתדע כיצד המשלוח הסתיים. ספירת ה-sent בתגובת ה-stub הנוכחית משקפת את מספר המנויים השמורים שאליהם מוקדת ההתראה, ולא משלוחים בפועל לדפדפן — אל תסתמך עליה כאישור משלוח עד שמשלוח הייצור יופעל.

נושאים

משתמשים יכולים להירשם לנושאים בעלי שם (לדוגמה product-updates, weekly-digest) דרך תת-המשאב proyecta.pushNotifications.topics. זוהי הדרך המומלצת לניהול רשימות הצטרפות — אין צורך לעקוב בעצמך אחר מזהי מבקרים לעדכונים בסגנון שידור.

בטל מנוי

הסר מנוי באמצעות ה-secret שהוחזר מ-subscribe:

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

תן ל-AI לחבר את הכל

אין צורך לכתוב את כל זה בעצמך. שאל את ה-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."

הגבלות

• Preview לא שולח push אמיתיים. התראות push פועלות רק בגרסה המפורסמת של האפליקציה שלך, מכיוון שדפדפנים דורשים HTTPS על origin אמיתי.
• iOS דורש PWA. ב-iOS 16.4 ומעלה, Web Push פועל רק מ-Progressive Web App מותקן (שנוסף למסך הבית), ולא מ-Safari ישירות.
• הרשאה היא חד-פעמית. אם משתמש מסרב להרשאת התראות, דפדפנים לא מאפשרים לבקש שוב באופן תכנותי. עליך להדריך אותם להגדרות הדפדפן או המכשיר שלהם.

בקרוב

• שליחה מתוזמנת ומבוססת אירועים — שלח אוטומטית בהתבסס על אירועי אפליקציה או לפי לוח זמנים
• Deep linking — פתח מסך ספציפי באפליקציה כאשר מקישים על ההתראה