الإشعارات الفورية

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

ملاحظة

يتوفر إرسال push حقيقي عبر المتصفح عندما تكون بيئة Proyecta Cloud لديك تعمل بمحوّل تسليم web-push مفعّلاً (PUSH_DELIVERY_ADAPTER=web-push). عند تفعيله، يُصدَر زوج مفاتيح P-256 VAPID صالح وتُسلَّم الإشعارات للمتصفحات المشتركة. أما عند إيقافه، فكل شيء يُكمل الدورة — تُخزَّن الاشتراكات وتُنجَز عمليات الإرسال — غير أن مفتاح VAPID يكون بديلاً موقتاً، فلا تُنتَج تسليمات حقيقية وتُسجَّل الرسائل بدلاً من إرسالها. إذا لم تصل إشعاراتك، فهذا المحوّل هو أول ما يجب فحصه.

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

كيف يعمل

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

1. التفعيل — تُنشأ مفاتيح VAPID لتطبيقك أول مرة يُحتاج إليها
2. الاشتراك — تسجيل جهاز الزائر لاستقبال الإشعارات
3. التعريف — ربط اشتراك مجهول بمستخدم مسجّل الدخول
4. الإرسال — تسليم إشعار لمستخدمين بعينهم أو مواضيع أو للجميع

تتم الخطوات الثلاث الأولى نيابةً عنك داخل الخطّاف usePush()، أما الرابعة فتقوم بها من لوحة الإدارة.

اشتراك جهاز المستخدم

يأتي تطبيقك ومعه الخطّاف usePush() الذي يتولى مسار المتصفح كاملاً — جلب مفتاح VAPID، وتسجيل الـ service worker، وإنشاء اشتراك Web Push، وتخزين السر، وربط الاشتراك المجهول بالمستخدم بمجرد تسجيل دخوله. لا تفعل أياً من ذلك بيدك:

import { usePush } from '@/hooks/usePush.ts';

function NotifyMeButton() {
    const { supported, subscribed, subscribe, unsubscribe, isPending } = usePush();

    // `supported: false` means this browser cannot do push at all — hide the CTA.
    if (!supported) return null;

    return (
        <button onClick={subscribed ? unsubscribe : subscribe} disabled={isPending}>
            {subscribed ? 'Turn off notifications' : 'Notify me'}
        </button>
    );
}

وهناك أيضاً مكوّن جاهز إن كنت تريد نافذة الاشتراك فحسب:

import { PushOptInButton } from '@/components/blocks/PushOptInButton.tsx';

<PushOptInButton description="Get told the moment a new drop lands." />;

اسأل الذكاء الاصطناعي: "Add a 'Notify me' button to the header that opts the visitor into push."

الزوار المجهولون مدعومون — إذ يشترك بهم الخطّاف بمعرّف مُولَّد، ثم يعيد ربط ذلك الاشتراك بحسابهم تلقائياً عند تسجيل دخولهم، فيصلهم أي إشعار ترسله لاحقاً في الحالتين.

إرسال إشعار

الإرسال إجراء يخص صاحب التطبيق، لا شيء تفعله صفحات تطبيقك العامة — فيجب ألا يستطيع متصفح زائر أن يرسل إشعاراً إلى جمهورك كله. وفي العمل اليومي ترسل من قسم Push في لوحة إدارة تطبيقك: تكتب العنوان والنص، وتختار موضوعاً أو تبث للجميع، وترسل اختباراً إلى جهازك أولاً.

يمكنك استهداف الجميع، أو الزوار المشتركين في موضوع بعينه فقط. ويحمل الإشعار عنواناً ونصاً، واختيارياً أيقونة وصورة.

وبعد الإرسال تحصل على عدد الأجهزة التي وصلها الإشعار وعدد ما فشل منها. مع تحفّظ واحد: لا تعكس هذه الأرقام تسليمات المتصفح الحقيقية إلا عند تفعيل محوّل تسليم web-push. أما عند إيقافه، فيعكس العدد كم اشتراكاً مخزّناً استُهدف، لا التسليمات الفعلية — فلا تقرأه على أنه تأكيد تسليم في تلك الحالة.

المواضيع

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

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

استدعِ unsubscribe من الخطّاف usePush() نفسه — فهو يحتفظ أصلاً بسر الاشتراك، ولا شيء عليك تخزينه أو تمريره:

const { subscribed, unsubscribe } = usePush();

{
    subscribed && <button onClick={unsubscribe}>Turn off notifications</button>;
}

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

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

• "Add a 'Notify me' button to the header that opts the visitor into push notifications."
• "Put a push opt-in prompt on the product page, but only show it to visitors who haven't already subscribed."
• "Add a topic called 'breaking-news' that visitors can opt into from the footer."

تنبيهات مهمة

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

قريباً

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