Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.

راهنمای پیاده‌سازی Web Push

نمای کلی

این راهنما مستندات جامعی برای پیاده‌سازی نوتیفیکیشن‌های Web Push با استفاده از Metrix Web SDK ارائه می‌دهد. Web Push به شما امکان می‌دهد برای کاربرانی که مجوز دریافت نوتیفیکیشن را صادر کرده‌اند، اعلان‌های مرورگری ارسال کنید.

مفاهیم کلیدی

ارتباط با کاربر

  • کاربران ناشناس: اگر authorizeUser پیش از درخواست مجوز فراخوانی نشود، Metrix برای هر دستگاهی که مجوز نوتیفیکیشن پوش را بدهد، یک کاربر ناشناس ایجاد می‌کند.
  • کاربران شناسایی‌شده: برای اتصال اشتراک پوش به یک کاربر شناسایی‌شده، authorizeUser را پیش از درخواست مجوز فراخوانی کنید.

چرخه عمر اشتراک

  1. مقداردهی اولیه Metrix SDK همراه با تنظیمات push و کلید عمومی VAPID
  2. پیکربندی Service Worker، چه Service Worker اختصاصی متریکس باشد و چه Service Worker موجود شما
  3. درخواست مجوز با استفاده از یکی از چهار روش موجود
  4. دریافت نوتیفیکیشن‌ها از طریق داشبورد 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 اختصاصی متریکس (پیشنهادی)

  1. فایل metrix-sw.js را دانلود کنید.
  2. آن را در ریشه وب‌سایت خود (همان پوشه‌ای که index.html در آن قرار دارد) قرار دهید.
  3. فایل باید در این آدرس قابل دسترسی باشد: 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 برای توسعه مجاز است.

بهترین روش‌ها

  1. زمان‌بندی: مجوز را بعد از تعامل کاربر درخواست کنید، نه هنگام بارگذاری اولیه صفحه.
  2. زمینه‌سازی: پیش از درخواست مجوز، مزایای فعال‌سازی نوتیفیکیشن‌ها را برای کاربر توضیح دهید.
  3. شناسایی کاربر: همیشه پیش از درخواست مجوز، authorizeUser() را فراخوانی کنید تا اشتراک پوش به کاربر شناسایی‌شده مرتبط شود.
  4. مدیریت خطا: همیشه Promiseهای ردشده (rejected) را مدیریت کنید تا خطاهای احتمالی را به درستی پوشش دهید.
  5. راهکار جایگزین: نوتیفیکیشن‌های پوش را اجباری نکنید؛ آن‌ها را اختیاری نگه دارید و امکان فعال‌سازی مجدد را فراهم کنید.
  6. تست: با استفاده از HTTPS یا localhost و کلیدهای VAPID معتبر تست کنید.
  7. حریم خصوصی: به انتخاب کاربر احترام بگذارید؛ پس از رد شدن مجوز، به طور مکرر درخواست نمایش مجدد آن را نکنید.
  8. مانیتورینگ: وضعیت‌های مجوز را برای اهداف تحلیل و آنالیتیکس ثبت کنید.

دیباگ

برای بررسی مشکلات، لاگ‌گیری را فعال کنید:

// وضعیت 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 پشتیبانی می‌کند.