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 این تنظیم را اضافه کنید:
<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 را انتخاب میکند و سپس سایت را از آیکن جدید باز میکند. حالا با همان دکمه، درخواست اصلی مجوز اعلان اجرا و توکن پوش بهصورت خودکار ثبت میشود.
<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 توکن را از زیرساخت پوشفا دریافت میکند.