SDK v2

Web Push / PWA SDK — نصب و پیکربندی

راهنمای کامل نصب Pushfa Web SDK، تنظیم autoPrompt، نصب Service Worker و راه‌اندازی Push در وب‌سایت و PWA.

نصب SDK

کد زیر را در <head> یا انتهای <body> سایت قرار دهید. مقدار YOUR_PUBLIC_KEY کلید عمومی سرویس در پنل است.

در حالت پیش‌فرض، تنظیمات زمان، اسکرول و تعداد بازدید ذخیره‌شده در پنل برای نمایش خودکار درخواست عضویت استفاده می‌شود.
<script
  src="https://sdk.pushfa.com/notification-v2.js?api_public_key=YOUR_PUBLIC_KEY"
  type="module">
</script>

نصب سرویس‌ورکر

فایل سرویس‌ورکر را از پنل (روبروی سرویس، دریافت کانفیگ) دانلود و با نام pushfa-messaging-sw.js در ریشه سایت آپلود کنید.

اگر فایل سرویس‌ورکر در زیرپوشه قرار بگیرد، پوش نوتیفیکیشن در پس‌زمینه کار نخواهد کرد.
# فایل باید در این آدرس در دسترس باشد:
https://yourdomain.com/pushfa-messaging-sw.js

غیرفعال کردن نمایش خودکار (Auto Prompt)

اگر می‌خواهید کنترل بیشتری بر زمان نمایش درخواست داشته باشید—مثلاً فقط در صفحات خاص یا پس از انجام اقدامات خاص—Auto Prompt را غیرفعال کنید. قبل از لود SDK این تنظیم را اضافه کنید:

اگر می‌خواهید کنترل بیشتری بر زمان نمایش درخواست عضویت داشته باشید—مثلاً فقط در صفحات خاص یا پس از اقدامات مشخص کاربر—Auto Prompt را غیرفعال کنید و درخواست را دستی نمایش دهید.
<script>
  window.PushfaConfig = { autoPrompt: false };
</script>
<script
  src="https://sdk.pushfa.com/notification-v2.js?api_public_key=YOUR_PUBLIC_KEY"
  type="module">
</script>

استایل درخواست: مرورگر، آماده یا سفارشی

استایل درخواست از پنل سرویس و بخش «تنظیمات عضویت» انتخاب می‌شود. حالت‌های آماده پوشفا مثل OneSignal و Bottom sheet باکس نرم آماده را نمایش می‌دهند. حالت «پیش‌فرض مرورگر» باکس نرم پوشفا را رد می‌کند و مستقیماً prompt اصلی مرورگر را اجرا می‌کند. حالت «پرامپت سفارشی سایت» هیچ UI آماده‌ای نمایش نمی‌دهد و فقط رویداد pushfaCustomPromptRequest را برای نمایش UI خودتان اجرا می‌کند.

window.addEventListener('pushfaCustomPromptRequest', () => {
  document.querySelector('#my-soft-prompt').hidden = false;
});

document.querySelector('#my-soft-prompt-accept').onclick = async () => {
  await window.Pushfa.requestPermission();
};

document.querySelector('#my-soft-prompt-later').onclick = () => {
  window.Pushfa.snoozePrompt(7);
};

سازگاری با مرورگرها

SDK v2 پوشفا روی مرورگرهای مدرن دسکتاپ و اندروید کار می‌کند.

مرورگروضعیتنکته
Chrome ≥ 50 ✅ پشتیبانی کامل دسکتاپ و اندروید
Firefox ≥ 44 ✅ پشتیبانی کامل دسکتاپ
Edge (Chromium) ✅ پشتیبانی کامل دسکتاپ و اندروید
Samsung Internet ✅ پشتیبانی کامل اندروید
Safari ≥ 16 (macOS) ⚠️ محدود نیاز به تأیید کاربر در تنظیمات سافاری
iOS Safari ≥ 16.4 ⚠️ محدود فقط پس از افزودن PWA به Home Screen

پشتیبانی iOS از وب‌پوش

در iPhone و iPad با iOS یا iPadOS نسخه 16.4 به بالا، مجوز وب‌پوش فقط برای سایتی قابل دریافت است که کاربر آن را به Home Screen اضافه کرده و از آیکن نصب‌شده باز کرده باشد. بنابراین ابتدا باید راهنمای Add to Home Screen پوشفا را نشان دهید؛ پس از نصب و ورود دوباره از آیکن سایت، درخواست معمول عضویت در اعلان‌ها نمایش داده می‌شود.

پیش‌نیاز PWA را آماده کنید

سایت باید HTTPS و فایل manifest.json معتبر داشته باشد. در Manifest نام، آیکن، start_url و display: standalone را مشخص کنید. داشتن PWA به‌تنهایی کافی نیست؛ کاربر iOS باید آن را روی Home Screen نصب کند.

تنظیمات عضویت سرویس را باز کنید

در پنل پوشفا به «سرویس‌ها» بروید، روی «تنظیمات و جزئیات» سرویس وب‌پوش بزنید و زبانه «تنظیمات عضویت» را باز کنید.

عنوان راهنمای iOS را بنویسید

در فیلد «عنوان پرامت راهنمای افزودن به Home Screen iOS» متن کوتاه و روشن وارد کنید. متن پیشنهادی: «برای دریافت اعلان در آیفون، سایت را به Home Screen اضافه کنید». پیش‌نمایش پایین فیلد، ظاهر نهایی راهنما را همان لحظه نشان می‌دهد.

تنظیمات را ذخیره کنید

روی «ذخیره تنظیمات» بزنید تا عنوان انتخابی در SDK وب‌پوش همان سرویس قرار بگیرد. لوگو یا آیکن تنظیم‌شده سرویس نیز در بالای راهنمای iOS نمایش داده می‌شود.

راهنما را با اقدام کاربر نمایش دهید

بهتر است دکمه‌ای مانند «فعال‌سازی اعلان در آیفون» در سایت قرار دهید. با کلیک کاربر، متد showIosInstallPrompt را اجرا کنید. این راهنما فقط در iOS 16.4+، خارج از حالت نصب‌شده و با رعایت فاصله نمایش باز می‌شود.

عضویت را بعد از نصب کامل کنید

کاربر در Safari روی Share می‌زند، Add to Home Screen را انتخاب می‌کند و سپس سایت را از آیکن جدید باز می‌کند. حالا با همان دکمه، درخواست اصلی مجوز اعلان اجرا و توکن پوش به‌صورت خودکار ثبت می‌شود.

کدام Prompt مناسب است؟ برای کاربری که سایت را در Safari معمولی باز کرده، ابتدا «راهنمای افزودن به Home Screen iOS» را نمایش دهید؛ این راهنما جای مجوز مرورگر نیست. بعد از نصب و باز شدن سایت از آیکن Home Screen، از Prompt معمول عضویت یا متد requestPermission استفاده کنید. گزینه «استایل درخواست» در پنل، ظاهر Prompt معمول عضویت را تعیین می‌کند و با راهنمای نصب iOS متفاوت است.
پارامتر days فاصله نمایش دوباره راهنما را مشخص می‌کند. مقدار 7 یعنی اگر کاربر راهنما را ببندد، تا هفت روز دوباره نشان داده نشود. اگر متد را بدون پارامتر اجرا کنید، پس از بستن دیگر نمایش داده نمی‌شود. مقدار پیشنهادی برای بیشتر سایت‌ها 7 روز است.
در حالت Private Browsing یا Incognito امکان عضویت پایدار وجود ندارد. همچنین کاربر باید پس از Add to Home Screen، سایت را از آیکن تازه ساخته‌شده باز کند؛ درخواست مجوز در تب معمولی Safari جای این مرحله را نمی‌گیرد.
تنظیم عنوان پرامت Add to Home Screen آیفون و پیش‌نمایش آن در پنل پوشفا
پنل پوشفا ← سرویس‌ها ← تنظیمات و جزئیات ← تنظیمات عضویت؛ فیلد عنوان راهنمای iOS و پیش‌نمایش سه‌مرحله‌ای Add to Home Screen.
<button type="button" id="enable-pushfa-notifications">
  فعال‌سازی اعلان‌ها
</button>

<script>
  document.getElementById('enable-pushfa-notifications').addEventListener('click', async () => {
    // در Safari آیفونِ نصب‌نشده، ابتدا راهنمای Add to Home Screen باز می‌شود.
    const installGuideShown = window.Pushfa.showIosInstallPrompt(7);

    if (installGuideShown) {
      return;
    }

    // در PWA نصب‌شده یا مرورگرهای دیگر، درخواست اصلی مجوز اجرا می‌شود.
    await window.Pushfa.requestPermission();
  });
</script>

سرویس عادی در مقابل پوش پایدار

در پنل سرویس نوع سرویس را انتخاب کنید. سرویس عادی از Firebase Cloud Messaging (FCM) و Service Worker استفاده می‌کند. پوش پایدار (SosNet) برای محیط‌هایی که دسترسی به سرورهای Google ندارند طراحی شده و بدون لود Firebase SDK توکن را از زیرساخت پوشفا دریافت می‌کند.