اعلان‌های Push

اعلان‌های Web Push به کاربرانت بفرست، و بگذار هوش مصنوعی همه چیز را سیم‌کشی کند.

یادداشت

تحویل واقعی push در مرورگر زمانی در دسترس است که محیط Proyecta Cloud تو آداپتور تحویل web-push را فعال داشته باشد (PUSH_DELIVERY_ADAPTER=web-push). با فعال بودن آن، یک جفت کلید VAPID معتبر از نوع P-256 صادر می‌شود و اعلان‌ها به مرورگرهای مشترک تحویل داده می‌شوند. وقتی خاموش است، همه چیز همچنان رفت‌وبرگشت می‌کند — اشتراک‌ها ذخیره می‌شوند و ارسال‌ها با موفقیت تمام می‌شوند — اما کلید VAPID یک مقدار موقت است، بنابراین تحویل واقعی صورت نمی‌گیرد و پیام‌ها به جای push شدن، در لاگ ثبت می‌شوند. اگر push هایت به مقصد نمی‌رسند، اول همین آداپتور را بررسی کن.

هر اپ Proyecta می‌تواند اعلان‌های push مرورگر و PWA برای کاربرانش ارسال کند. Proyecta تولید کلید VAPID، ذخیره‌سازی اشتراک، مدیریت topic و تحویل را مدیریت می‌کند — بدون نیاز به هیچ حساب شخص ثالثی.

نحوه عملکرد

اعلان‌های push در Proyecta از چرخه حیات استاندارد Web Push با چهار مرحله پیروی می‌کنند:

1. Enable — کلیدهای VAPID اولین باری که لازم شوند برای اپت تولید می‌شوند
2. Subscribe — ثبت دستگاه بازدیدکننده برای دریافت اعلان‌ها
3. Identify — اتصال یک اشتراک ناشناس به کاربر وارد شده
4. Send — تحویل اعلان به کاربران خاص، topic ها، یا همه

سه مورد اول داخل هوک usePush() برایت انجام می‌شوند؛ مورد چهارم را از پنل ادمینت انجام می‌دهی.

اشتراک دستگاه کاربر

اپ تو با یک هوک usePush() عرضه می‌شود که کل جریان مرورگر را مدیریت می‌کند — گرفتن کلید VAPID، ثبت service worker، ساختن اشتراک Web Push، ذخیره secret، و اتصال یک اشتراک ناشناس به کاربر به‌محض ورود او. هیچ‌کدام از این‌ها را دستی انجام نمی‌دهی:

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>
    );
}

اگر فقط همان پیام opt-in را می‌خواهی، یک بلوک آماده هم وجود دارد:

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 کند. در کار روزمره از بخش Push پنل ادمین اپت ارسال می‌کنی: عنوان و متن را می‌نویسی، یک topic انتخاب می‌کنی یا برای همه broadcast می‌کنی، و اول یک تست به دستگاه خودت می‌فرستی.

می‌توانی همه را هدف بگیری، یا فقط بازدیدکنندگانی که مشترک یک topic خاص هستند. یک اعلان شامل یک عنوان، یک متن، و به‌صورت اختیاری یک آیکون و تصویر است.

پس از ارسال، تعداد دستگاه‌هایی که اعلان به آن‌ها رفته و تعداد ناموفق‌ها را می‌بینی. یک نکته: این اعداد فقط زمانی نشان‌دهنده تحویل واقعی در مرورگر هستند که آداپتور تحویل web-push فعال باشد. با خاموش بودن آن، عدد نشان می‌دهد چند اشتراک ذخیره‌شده هدف قرار گرفته‌اند، نه تحویل واقعی — پس در آن حالت آن را به‌عنوان تأیید تحویل نخوان.

Topic ها

بازدیدکنندگان می‌توانند به‌جای یک فهرست همه‌یا-هیچ، به topic های نام‌گذاری‌شده (مثلاً product-updates، weekly-digest) مشترک شوند. این روش توصیه‌شده برای مدیریت opt-in هاست — برای به‌روزرسانی‌های از نوع broadcast نیازی نیست visitor ID ها را خودت دنبال کنی. Topic ها به‌عنوان انتخاب‌گر مخاطب در بخش Push پنل ادمین ظاهر می‌شوند.

لغو اشتراک

از همان هوک usePush() تابع unsubscribe را صدا بزن — secret اشتراک را از قبل در اختیار دارد، پس چیزی برای ذخیره یا پاس دادن نداری:

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

نکات مهم

• در Preview push واقعی ارسال نمی‌شود. اعلان‌های push فقط روی نسخه منتشرشده اپت کار می‌کنند، چون مرورگرها به HTTPS روی یک origin واقعی نیاز دارند.
• iOS به PWA نیاز دارد. در iOS نسخه 16.4 و بالاتر، Web Push فقط از یک Progressive Web App نصب‌شده (اضافه‌شده به صفحه اصلی) کار می‌کند، نه مستقیماً از Safari.
• مجوز یک‌بار مصرف است. اگر کاربر مجوز اعلان را رد کند، مرورگرها اجازه نمی‌دهند دوباره به صورت برنامه‌نویسی درخواست بدهی. باید او را به تنظیمات مرورگر یا دستگاهش راهنمایی کنی.

به زودی

• ارسال زمان‌بندی‌شده و مبتنی بر رویداد — ارسال خودکار بر اساس رویدادهای اپ یا یک زمان‌بندی
• Deep linking — باز کردن یک صفحه خاص در اپ هنگامی که روی اعلان ضربه زده می‌شود