إشعارات Push

أرسل إشعارات Web Push لمستخدميك. قم بالإعداد باستخدام SDK ودع الذكاء الاصطناعي يتولى ربط كل شيء.

ملاحظة

واجهات برمجة إشعارات Push تعمل جزئيًا على مستوى SDK — تُخزَّن الاشتراكات، وتنتهي استدعاءات الإرسال دون أخطاء. غير أن تسليم إشعارات Push الفعلي إلى المتصفح لم يُفعَّل بعد في بيئة الإنتاج: مفاتيح VAPID التي تُعيدها enable() هي بايتات عشوائية وليست مفاتيح P-256 EC صالحة، لذا سيفشل اشتراك المتصفح (pushManager.subscribe) حتى يُفعَّل التسليم في الإنتاج. تُسجَّل الرسائل لكنها لا تُرسَل إلى الأجهزة. التسليم في بيئة الإنتاج قادم قريبًا.

يمكن لكل تطبيق Proyecta إرسال إشعارات Push للمتصفح وتطبيقات PWA إلى مستخدميه. يتولى Proyecta SDK إنشاء مفاتيح VAPID، وتخزين الاشتراكات، وإدارة المواضيع، والتسليم — دون الحاجة إلى حساب خارجي.

كيف يعمل

تتبع إشعارات Push في Proyecta دورة حياة Web Push القياسية في أربع خطوات:

1. التفعيل (Enable) — إنشاء مفاتيح VAPID لتطبيقك (مرة واحدة فقط)
2. الاشتراك (Subscribe) — تسجيل جهاز المستخدم لاستقبال الإشعارات
3. الربط (Identify) — ربط اشتراك مجهول بمستخدم مسجَّل الدخول
4. الإرسال (Send) — تسليم إشعار لمستخدمين محددين أو مواضيع أو للجميع

جميع الخطوات الأربع موجودة تحت proyecta.pushNotifications في SDK.

تفعيل Push لتطبيقك

يُنشئ الاستدعاء الأول مفتاح VAPID العام الذي يحتاجه المتصفح لإنشاء اشتراك. العملية متكررة بأمان — استدعاؤها مجددًا يُعيد نفس المفتاح.

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

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

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

اسأل الذكاء الاصطناعي: "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 في الاستجابة الحالية عدد الاشتراكات المخزَّنة المستهدَفة، وليس عمليات التسليم الفعلية للمتصفح — لا تعتمد عليه كتأكيد للتسليم حتى يُفعَّل التسليم في بيئة الإنتاج.

المواضيع (Topics)

يمكن للمستخدمين الاشتراك في مواضيع مسماة (مثل product-updates، weekly-digest) عبر الموارد الفرعية proyecta.pushNotifications.topics. هذه هي الطريقة الموصى بها لإدارة قوائم الاشتراك الاختياري — لست بحاجة إلى تتبع معرّفات الزوار بنفسك للتحديثات ذات طابع البث.

إلغاء الاشتراك

احذف اشتراكًا باستخدام السر المُعاد من subscribe:

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

دع الذكاء الاصطناعي يتولى الربط

لا تحتاج إلى كتابة أي من هذا يدويًا. اسأل الذكاء الاصطناعي:

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

تحفظات

• بيئة المعاينة لا تُرسل إشعارات Push حقيقية. تعمل إشعارات Push فقط على النسخة المنشورة من تطبيقك لأن المتصفحات تشترط HTTPS على أصل حقيقي.
• iOS تتطلب تطبيق PWA. على iOS 16.4 وما بعده، يعمل Web Push فقط من تطبيق Progressive Web App مُثبَّت (مُضاف إلى الشاشة الرئيسية)، وليس من Safari مباشرةً.
• الإذن فرصة واحدة. إذا رفض المستخدم إذن الإشعارات، لا تسمح المتصفحات بإعادة الطلب برمجيًا. يتعين عليك توجيههم إلى إعدادات المتصفح أو الجهاز.

قريبًا

• الإرسال المجدوَل والمُشغَّل بالأحداث — إرسال تلقائي بناءً على أحداث التطبيق أو جدول زمني
• الربط العميق (Deep Linking) — فتح شاشة محددة في التطبيق عند النقر على الإشعار