راهنمای پیادهسازی Web Push
نمای کلی
این راهنما مستندات جامعی برای پیادهسازی نوتیفیکیشنهای Web Push با استفاده از Metrix Web SDK ارائه میدهد. Web Push به شما امکان میدهد برای کاربرانی که مجوز دریافت نوتیفیکیشن را صادر کردهاند، اعلانهای مرورگری ارسال کنید.
مفاهیم کلیدی
ارتباط با کاربر
- کاربران ناشناس: اگر
authorizeUserپیش از درخواست مجوز فراخوانی نشود، Metrix برای هر دستگاهی که مجوز نوتیفیکیشن پوش را بدهد، یک کاربر ناشناس ایجاد میکند. - کاربران شناساییشده: برای اتصال اشتراک پوش به یک کاربر شناساییشده،
authorizeUserرا پیش از درخواست مجوز فراخوانی کنید.
چرخه عمر اشتراک
- مقداردهی اولیه Metrix SDK همراه با تنظیمات push و کلید عمومی VAPID
- پیکربندی Service Worker، چه Service Worker اختصاصی متریکس باشد و چه Service Worker موجود شما
- درخواست مجوز با استفاده از یکی از چهار روش موجود
- دریافت نوتیفیکیشنها از طریق داشبورد Metrix
پیشنیازها
- HTTPS: برای محیط production الزامی است.
localhostبرای توسعه مجاز است. - مرورگر مدرن: Chrome 50+, Firefox 44+, Edge 15+, Safari 16+
- پشتیبانی از Service Worker: مرورگر باید از Service Worker و Push API پشتیبانی کند
- کلید عمومی VAPID: توسط Metrix در اختیار شما قرار میگیرد
میتوانید از نمونه پیادهسازیهای زیر برای پیادهسازی WebPush در وبسایت خود استفاده نمایید:
مراحل پیادهسازی
مرحله ۱: راهاندازی Service Worker
گزینه الف: استفاده از Service Worker اختصاصی متریکس (پیشنهادی)
- فایل
metrix-sw.jsرا دانلود کنید. - آن را در ریشه وبسایت خود (همان پوشهای که
index.htmlدر آن قرار دارد) قرار دهید. - فایل باید در این آدرس قابل دسترسی باشد:
https://YOUR_DOMAIN/metrix-sw.js
وقتی hasSW: false (حالت پیشفرض) باشد، SDK این Service Worker را بهصورت خودکار ثبت میکند.
گزینه ب: استفاده از Service Worker موجود
اگر از قبل Service Worker دارید:
// Add to your service worker file
importScripts('https://cdn.metrix.ir/sdk/web/metrixweb-sw.js');سپس SDK را با hasSW: true مقداردهی اولیه کنید:
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
hasSW: true,
},
});مرحله ۲: مقداردهی اولیه SDK
import { init } from '@metrixorg/websdk';
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
hasSW: false, // Set to true if using existing service worker
showBell: true, // Optional: Display bell icon
showBackdrop: false, // Optional: Show permission dialog on init
popUpText: 'Enable notifications', // Custom bell popup text
position: 'bottom-right', // Bell position
},
});مرحله ۳: درخواست مجوز از کاربر
روش ۱: subscribePush() — درخواست برنامهنویسیشده
import { subscribePush } from '@metrixorg/websdk';
// این تابع را در پاسخ به یک تعامل کاربر (مانند کلیک روی دکمه) فراخوانی کنید
async function enableNotifications() {
try {
const state = await subscribePush();
if (state === 'subscribed') {
console.log('✓ Push notifications enabled');
} else if (state === 'blocked') {
console.log('✗ User blocked notifications');
} else if (state === 'closed') {
console.log('○ Permission dialog closed');
}
} catch (error) {
console.error('Failed to enable push:', error);
}
}
// این کد را به یک دکمه یا هر تعامل کاربری دیگری متصل کنید
document.getElementById('enable-btn').addEventListener('click', enableNotifications);روش ۲: نمایش خودکار دیالوگ تایید (Backdrop) هنگام init
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
showBackdrop: true,
backdropDelay: 2000, // 2 second delay
backdropText: 'Enable notifications to stay updated',
},
});روش ۳: کنترل دستی دیالوگ تایید (Backdrop)
import { openPushConfirmBackdrop } from '@metrixorg/websdk';
async function showPermissionDialog() {
const state = await openPushConfirmBackdrop({
backdropText: 'Get important updates',
backdropDelay: 500,
});
console.log('User decision:', state);
}
// این دیالوگ را پس از تعامل کاربر نمایش دهید
document.getElementById('settings-btn').addEventListener('click', showPermissionDialog);روش ۴: آیکون زنگ
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
showBell: true,
popUpText: 'Click to enable notifications',
position: 'bottom-right', // or top-left, top-right, bottom-left
},
});با کلیک کاربر روی آیکون زنگ، فرایند درخواست مجوز آغاز میشود.
وضعیتهای پاسخ
همه روشهای درخواست مجوز یک ConfirmPushState برمیگردانند:
type ConfirmPushState = 'subscribed' | 'blocked' | 'closed';| وضعیت | معنی |
|---|---|
subscribed | کاربر مجوز را صادر کرده و اشتراک با موفقیت ایجاد شده است. |
blocked | مجوز توسط مرورگر رد شده یا کاربر نوتیفیکیشنها را مسدود کرده است. |
closed | دیالوگ بدون هیچ اقدامی از سوی کاربر بسته شده است. |
مرجع API
توابع export شده
subscribePush()
درخواست مجوز نوتیفیکیشن در پاسخ به تعامل کاربر.
subscribePush(): Promise<ConfirmPushState>خروجی: یک Promise که با تصمیم کاربر resolve میشود.
نحوه استفاده:
const state = await subscribePush();openPushConfirmBackdrop(config)
نمایش دستی دیالوگ تایید مجوز.
openPushConfirmBackdrop(config: {
backdropText: string;
backdropDelay?: number;
}): Promise<ConfirmPushState>پارامترها:
backdropText(الزامی): متن پیام دیالوگ تایید مجوز.backdropDelay(اختیاری): مدت زمان تأخیر (بر حسب میلیثانیه) پیش از نمایش.
نحوه استفاده:
const state = await openPushConfirmBackdrop({
backdropText: 'Enable notifications',
backdropDelay: 1000,
});onPushStateResolved()
انتظار برای تکمیل فرایند مجوز از هر روشی.
onPushStateResolved(): Promise<ConfirmPushState>خروجی: یک Promise که با وضعیت نهایی مجوز resolve میشود.
نحوه استفاده:
const finalState = await onPushStateResolved();notificationPermissionState()
بررسی وضعیت فعلی مجوز مرورگر.
notificationPermissionState(): NotificationPermission | undefinedخروجی: 'default' | 'granted' | 'denied' | undefined
نحوه استفاده:
const permission = notificationPermissionState();
if (permission === 'granted') {
console.log('Already enabled');
}getPushSubscription()
دریافت جزئیات اشتراک فعلی Push.
getPushSubscription(): Promise<PushSubscriptionJSON | undefined>خروجی: شیء اشتراک Push یا undefined
نحوه استفاده:
const subscription = await getPushSubscription();
if (subscription) {
console.log('Endpoint:', subscription.endpoint);
}گزینههای پیکربندی
interface PushConfig {
enabled: boolean; // Enable push (required)
publicKey: string; // VAPID public key (required)
hasSW?: boolean; // Existing service worker? (default: false)
showBell?: boolean; // Show bell icon? (default: false)
showBackdrop?: boolean; // Show backdrop on init? (default: false)
backdropText?: string; // Backdrop message text
backdropDelay?: number; // Backdrop delay in ms
popUpText?: string; // Bell popup text
position?: string; // Bell position (top-left, top-right, bottom-left, bottom-right)
}مثال کامل
import {
init,
authorizeUser,
subscribePush,
notificationPermissionState,
getPushSubscription,
} from '@metrixorg/websdk';
// مقداردهی اولیه SDK
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
hasSW: false,
},
});
// شناسایی کاربر (اختیاری اما توصیه میشود)
authorizeUser('user@example.com');
// افزودن دکمه درخواست مجوز
document.getElementById('notify-btn').addEventListener('click', async () => {
const permission = notificationPermissionState();
// اگر از قبل مجوز داده شده یا رد شده است، از ادامه صرف نظر کنید
if (permission === 'granted') {
alert('نوتیفیکیشنها از قبل فعال هستند.');
return;
}
if (permission === 'denied') {
alert('لطفاً نوتیفیکیشنها را از تنظیمات مرورگر خود فعال کنید.');
return;
}
// درخواست مجوز
try {
const state = await subscribePush();
if (state === 'subscribed') {
const sub = await getPushSubscription();
console.log('Subscribed:', sub?.endpoint);
alert('✓ Notifications enabled');
} else if (state === 'blocked') {
alert('Notifications blocked by browser');
} else {
alert('Permission request cancelled');
}
} catch (error) {
console.error('Push error:', error);
alert('Failed to enable notifications');
}
});الگوهای پیشرفته
درخواست مجوز با تأخیر
درخواست مجوز بعد از تعامل کاربر:
import { init, openPushConfirmBackdrop } from '@metrixorg/websdk';
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
showBackdrop: false, // Don't show immediately
},
});
// نمایش دیالوگ پس از ۵ ثانیه از اولین تعامل کاربر
let hasInteracted = false;
document.addEventListener('click', () => {
if (!hasInteracted) {
hasInteracted = true;
setTimeout(() => {
openPushConfirmBackdrop({
backdropText: 'Stay updated with notifications',
backdropDelay: 500,
});
}, 5000);
}
});درخواست شرطی مجوز
درخواست مجوز بر اساس اقدام کاربر:
document.getElementById('checkout-btn').addEventListener('click', async () => {
// تکمیل فرآیند خرید...
const permission = notificationPermissionState();
if (permission !== 'denied' && permission !== 'granted') {
const state = await subscribePush();
if (state === 'subscribed') {
console.log('User subscribed to order updates'); // کاربر مشترک بهروزرسانیهای سفارش شد
}
}
});ترکیب آیکون زنگ + درخواست دستی مجوز
امکان ارائه چند روش مختلف برای درخواست مجوز:
init('APP_ID', 'API_KEY', {
push: {
enabled: true,
publicKey: 'YOUR_VAPID_PUBLIC_KEY',
showBell: true, // نمایش آیکون زنگ
popUpText: 'Enable notifications',
position: 'bottom-right',
},
});
// همچنین یک دکمه سفارشی برای درخواست مجوز اضافه کنید
document.getElementById('custom-notify-btn').addEventListener('click', subscribePush);عیبیابی
مشکلات Service Worker
مشکل: Service Worker پیدا نمیشود.
- راهحل: مطمئن شوید
metrix-sw.jsدر ریشه دامنه قرار دارد و از طریقhttps://YOUR_DOMAIN/metrix-sw.jsقابل دسترسی است.
مشکل: مشاهده پیام "Service worker is not for Metrix" در کنسول.
- راهحل: مقدار
hasSW: trueرا تنظیم کنید و مطمئن شویدimportScripts('https://cdn.metrix.ir/sdk/web/metrixweb-sw.js');در فایل Service Worker شما وجود دارد.
مشکلات مجوز
مشکل: درخواست مجوز همیشه رد میشود.
- راهحل: بررسی کنید
publicKeyهمان کلید عمومی VAPID درست باشد، نه کلید خصوصی.
مشکل: پنجره درخواست مجوز نمایش داده نمیشود.
- راهحل:
subscribePush()را در پاسخ به تعامل کاربر (کلیک، لمس و غیره) فراخوانی کنید. مرورگرها از درخواست مجوز بدون تعامل کاربر جلوگیری میکنند.
مشکل: Push مقداردهی اولیه (Initialize) نمیشود.
- راهحل: بررسی کنید
enabled: trueوpublicKeyبه درستی در تنظیمات وارد شده باشند.
پشتیبانی مرورگر
مشکل: پیام "Push notification is not supported"
- راهحل: از مرورگر مدرن استفاده کنید (Chrome 50+، Firefox 44+، Edge 15+، Safari 16+).
مشکل: خطای مربوط به نیاز به HTTPS
- راهحل: در محیط production از HTTPS استفاده کنید؛
localhostبرای توسعه مجاز است.
بهترین روشها
- زمانبندی: مجوز را بعد از تعامل کاربر درخواست کنید، نه هنگام بارگذاری اولیه صفحه.
- زمینهسازی: پیش از درخواست مجوز، مزایای فعالسازی نوتیفیکیشنها را برای کاربر توضیح دهید.
- شناسایی کاربر: همیشه پیش از درخواست مجوز،
authorizeUser()را فراخوانی کنید تا اشتراک پوش به کاربر شناساییشده مرتبط شود. - مدیریت خطا: همیشه Promiseهای ردشده (rejected) را مدیریت کنید تا خطاهای احتمالی را به درستی پوشش دهید.
- راهکار جایگزین: نوتیفیکیشنهای پوش را اجباری نکنید؛ آنها را اختیاری نگه دارید و امکان فعالسازی مجدد را فراهم کنید.
- تست: با استفاده از HTTPS یا localhost و کلیدهای VAPID معتبر تست کنید.
- حریم خصوصی: به انتخاب کاربر احترام بگذارید؛ پس از رد شدن مجوز، به طور مکرر درخواست نمایش مجدد آن را نکنید.
- مانیتورینگ: وضعیتهای مجوز را برای اهداف تحلیل و آنالیتیکس ثبت کنید.
دیباگ
برای بررسی مشکلات، لاگگیری را فعال کنید:
// وضعیت Push را بررسی کنید
const permission = notificationPermissionState();
console.log('Push initialized:', permission !== undefined);
console.log('Permission:', permission);
// اشتراک را بررسی کنید
getPushSubscription().then(sub => {
console.log('Subscription:', sub?.endpoint ? 'Active' : 'None');
});
// جریان را مانیتور کنید
onPushStateResolved().then(state => {
console.log('Final state:', state);
});پشتیبانی
برای رفع مشکلات یا پاسخ به پرسشها، موارد زیر را بررسی کنید:
- خطاهای کنسول مرورگر را بررسی کنید.
- مطمئن شوید از HTTPS یا localhost استفاده میکنید.
- از صحت کلید عمومی VAPID اطمینان حاصل کنید.
- از در دسترس بودن فایل Service Worker اطمینان حاصل کنید.
- تأیید کنید که مرورگر کاربر از Push API پشتیبانی میکند.