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

فعال‌سازی اعلان‌های پوش وب در Metrix

اعلان‌های پوش وب به شما این امکان را می‌دهند که پیام‌های به‌موقع و هدفمند را به کاربرانی که در وب‌سایت شما مشترک شده‌اند، ارسال کنید. این راهنما نحوه فعال‌سازی، پیکربندی و مدیریت اعلان‌های پوش وب را با استفاده از پلاگین وردپرس Metrix توضیح می‌دهد.

اعلان‌های پوش وب چیست؟

اعلان‌های پوش وب پیام‌هایی هستند که از طریق یک سرویس ورکر (Service Worker) به مرورگر کاربران (حتی زمانی که فعالانه در وب‌سایت شما نیستند) تحویل داده می‌شوند. آن‌ها شما را قادر می‌سازند تا:

  • هشدارهای به‌موقع درباره محتوای جدید ارسال کنید
  • پیشنهادات تبلیغاتی ارائه دهید
  • کاربران را از به‌روزرسانی‌های مهم مطلع کنید
  • کاربران را که سایت شما را ترک کرده‌اند، دوباره جذب کنید
  • حفظ کاربران را بهبود ببخشید

پیش‌نیازها

قبل از فعال‌سازی اعلان‌های پوش، به موارد زیر نیاز دارید:

  • پلاگین Metrix نصب شده و با App ID و API Key پیکربندی شده باشد
  • کلید عمومی (Public Key) از داشبورد Metrix شما
  • دسترسی کاربران به وب‌سایت شما از طریق HTTPS (برای اعلان‌های پوش الزامی است)
  • رضایت کاربر برای دریافت اعلان‌ها

مرحله 1: دریافت کلید عمومی (Public Key) از Metrix

برای فعال‌سازی اعلان‌های پوش، باید کلید عمومی خود را از داشبورد Metrix دریافت کنید:

  1. به داشبورد Metrix خود وارد شوید
  2. به تنظیمات پوش وب (Web Push Settings) → ادغام کانال (Channel Integration) → تنظیمات (Settings) → فضای کاری (Workspace) بروید
  3. کلید عمومی (Public Key) خود را کپی کنید
  4. این کلید را ایمن نگه دارید؛ برای پیکربندی به آن نیاز خواهید داشت

اگر گزینه پوش وب را مشاهده نمی‌کنید، برای فعال‌سازی آن برای حساب کاربری خود با پشتیبانی Metrix تماس بگیرید.

مرحله 2: فعال‌سازی اعلان‌های پوش در تنظیمات پلاگین

از طریق داشبورد مدیریت وردپرس

  1. به پنل مدیریت وردپرس خود وارد شوید
  2. در منوی سمت چپ روی Metrix کلیک کنید
  3. در بخش اعلان پوش (Push Notification)، تیک گزینه فعال‌سازی اعلان پوش (Enable push notification) را بزنید
  4. در فیلد کلید عمومی (Public Key)، کلیدی را که از Metrix دریافت کرده‌اید، جای‌گذاری کنید
  5. (اختیاری) تیک نمایش زنگوله (Show bell) را بزنید تا آیکون زنگوله اشتراک‌گذاری برای کاربران نمایش داده شود
  6. (اختیاری) تیک نمایش پیام درخواستی (Show backdrop) را بزنید تا یک پیام درخواستی نمایش داده شود
  7. اگر پیام درخواستی را فعال کرده‌اید:
    • متن پیام درخواستی (Backdrop Text) را وارد کنید (مثلاً “آیا می‌خواهید اعلان‌های پوش را دریافت کنید؟”)
    • تأخیر پیام درخواستی (Backdrop Delay) را بر حسب میلی‌ثانیه وارد کنید (مثلاً 1000 = 1 ثانیه)
  8. روی ذخیره (Save) کلیک کنید

توضیح گزینه‌های پیکربندی

گزینهتوضیحاتپیش‌فرض
فعال‌سازی اعلان پوشقابلیت پوش وب را فعال می‌کندغیرفعال
کلید عمومیکلید احراز هویت از داشبورد Metrixخالی
نمایش زنگولهآیکون زنگوله اشتراک‌گذاری را در گوشه نمایش می‌دهدفعال
نمایش پیام درخواستیقبل از اجازه اعلان، پیام درخواستی را نشان می‌دهدغیرفعال
متن پیام درخواستیپیامی که به کاربران برای درخواست اجازه پوش نشان داده می‌شودخالی
تأخیر پیام درخواستیمیلی‌ثانیه قبل از ظاهر شدن پیام درخواستی در بارگذاری صفحه0

نحوه کار اعلان‌های پوش

مسیر کاربر

1. کاربر از وب‌سایت شما بازدید می‌کند
   ↓
2. SDK Metrix راه‌اندازی می‌شود
   ↓
3. رابط کاربری اعلان پوش نمایش داده می‌شود (آیکون زنگوله و/یا پیام درخواستی)
   ↓
4. کاربر روی "مشترک شوید" کلیک می‌کند یا به اعلان‌ها اجازه می‌دهد
   ↓
5. مرورگر از کاربر درخواست اجازه می‌کند
   ↓
6. کاربر اجازه را می‌دهد
   ↓
7. سرویس ورکر (Service Worker) ثبت می‌شود
   ↓
8. کاربر مشترک می‌شود و اعلان‌ها را دریافت می‌کند

سرویس ورکر (Service Worker)

پلاگین به طور خودکار یک سرویس ورکر (metrix-sw.js) در ریشه وب‌سایت شما ثبت می‌کند که:

  • اعلان‌های پوش دریافتی را مدیریت می‌کند
  • اعلان‌ها را به کاربران نمایش می‌دهد
  • کلیک‌ها و تعاملات اعلان را مدیریت می‌کند
  • به صورت آفلاین و زمانی که کاربر در سایت شما نیست کار می‌کند

سرویس ورکر به طور خودکار هنگام فعال‌سازی پوش نصب می‌شود.

روش‌های پیکربندی

روش 1: تنظیمات مدیریت پلاگین (توصیه شده برای اکثر کاربران)

آسان‌ترین راه برای فعال‌سازی اعلان‌های پوش، از طریق پنل مدیریت وردپرس است (همانطور که در مرحله 2 بالا توضیح داده شد).

این روش توصیه می‌شود زیرا:

  • نیازی به کدنویسی نیست
  • تنظیمات به صورت ایمن ذخیره می‌شوند
  • در هر زمان از داشبورد قابل تغییر هستند
  • راه‌اندازی خودکار سرویس ورکر

روش 2: کد PHP (پیشرفته)

اگر نیاز دارید پوش را به صورت برنامه‌نویسی پیکربندی کنید، می‌توانید کد را به قالب یا پلاگین خود اضافه کنید:

<?php
// در فایل functions.php یا فایل پلاگین سفارشی شما
 
// فعال‌سازی برنامه‌نویسی اعلان‌های پوش
add_action('wp_head', function() {
    $push_config = array(
        'enabled' => true,
        'publicKey' => 'YOUR_PUBLIC_KEY_HERE', // کلید عمومی شما در اینجا
        'showBell' => true,
        'showBackdrop' => true,
        'backdropText' => 'برای دریافت به‌روزرسانی‌ها، اعلان‌ها را فعال کنید!',
        'backdropDelay' => 2000
    );
    
    // به‌روزرسانی تنظیمات
    $current_settings = get_option('wp_metrix_settings');
    $current_settings = array_merge($current_settings, array(
        'push_enabled' => $push_config['enabled'],
        'push_public_key' => $push_config['publicKey'],
        'push_show_bell' => $push_config['showBell'],
        'push_show_backdrop' => $push_config['showBackdrop'],
        'push_backdrop_text' => $push_config['backdropText'],
        'push_backdrop_delay' => $push_config['backdropDelay']
    ));
    
    update_option('wp_metrix_settings', $current_settings);
});
?>

روش 3: جاوااسکریپت (کنترل در لحظه)

پس از راه‌اندازی SDK، می‌توانید اعلان‌های پوش را از طریق جاوااسکریپت کنترل کنید:

// درخواست اجازه پوش هنگام کلیک روی دکمه
document.getElementById('subscribePushBtn').addEventListener('click', function() {
    Metrix.subscribePush().then(function(state) {
        console.log('وضعیت اشتراک پوش:', state);
        // وضعیت‌های احتمالی: 'subscribed', 'blocked', 'closed'
        
        if (state === 'subscribed') {
            alert('از شما برای اشتراک در اعلان‌ها متشکریم!');
        } else if (state === 'blocked') {
            alert('شما اعلان‌ها را مسدود کرده‌اید. لطفاً آن‌ها را در تنظیمات مرورگر فعال کنید.');
        }
    });
});

گزینه‌های رابط کاربری

گزینه 1: اشتراک‌گذاری با آیکون زنگوله

نمایش یک آیکون زنگوله در گوشه وب‌سایت شما:

<?php
// در مدیریت وردپرس: Metrix ← تیک گزینه "نمایش زنگوله" را بزنید
// یا در کد:
Metrix_SDK::enable_push_bell(true);
?>

ویژگی‌ها:

  • عنصر رابط کاربری غیر مزاحم
  • آیکون در گوشه ظاهر می‌شود
  • کاربران برای اشتراک کلیک می‌کنند
  • قابل بستن در صورت عدم علاقه

گزینه 2: پیام درخواستی (Backdrop Message)

نمایش پیامی برای درخواست اجازه اعلان:

<?php
// در مدیریت وردپرس:
// 1. تیک "نمایش پیام درخواستی" را بزنید
// 2. "متن پیام درخواستی" را وارد کنید
// 3. "تأخیر پیام درخواستی" را تنظیم کنید (بر حسب میلی‌ثانیه)
 
// مثال پیکربندی
$backdrop_config = array(
    'show_backdrop' => true,
    'backdrop_text' => 'به‌روز بمانید! برای دریافت اخبار مهم، اعلان‌ها را فعال کنید.',
    'backdrop_delay' => 3000  // پس از 3 ثانیه نمایش داده شود
);
?>

ویژگی‌ها:

  • پیام برجسته به کاربران
  • متن قابل تنظیم
  • تأخیر قبل از نمایش (اجازه دهید کاربران ابتدا صفحه را ببینند)
  • کاربران می‌توانند قبول یا رد کنند

گزینه 3: دکمه سفارشی

افزودن یک دکمه اشتراک سفارشی:

<!-- در قالب وردپرس یا پلاگین سفارشی شما -->
<button id="custom-push-subscribe" class="btn btn-primary">
    مشترک شدن در اعلان‌ها
</button>
 
<script>
document.getElementById('custom-push-subscribe').addEventListener('click', function() {
    Metrix.subscribePush().then(function(state) {
        if (state === 'subscribed') {
            // به‌روزرسانی متن دکمه
            document.getElementById('custom-push-subscribe').textContent = 'مشترک شدید!';
            document.getElementById('custom-push-subscribe').disabled = true;
        }
    });
});
</script>

مثال‌های راه‌اندازی اعلان پوش

راه‌اندازی اولیه (فقط مدیر)

برای اکثر سایت‌های وردپرس، این تنها چیزی است که نیاز دارید:

  1. پوش را در تنظیمات Metrix فعال کنید
  2. کلید عمومی را اضافه کنید
  3. تیک “نمایش زنگوله” را بزنید
  4. ذخیره کنید

کاربران آیکون زنگوله را مشاهده کرده و می‌توانند مشترک شوند.

راه‌اندازی با پیام درخواستی

برای نمایش یک پیام درخواست اجازه:

  1. پوش را در تنظیمات Metrix فعال کنید
  2. کلید عمومی را اضافه کنید
  3. هر دو گزینه “نمایش زنگوله” و “نمایش پیام درخواستی” را تیک بزنید
  4. متن پیام درخواستی (Backdrop Text) را تنظیم کنید: “برای دریافت به‌روزرسانی‌ها درباره پست‌های جدید مشترک شوید!”
  5. تأخیر پیام درخواستی (Backdrop Delay) را: 2000 (2 ثانیه) تنظیم کنید
  6. ذخیره کنید

کاربران پیام شما را 2 ثانیه پس از بارگذاری صفحه مشاهده خواهند کرد.

راه‌اندازی پیشرفته با کد سفارشی

برای سایت‌هایی که نیاز به رفتارهای خاص دارند:

<?php
// به functions.php قالب خود اضافه کنید
 
add_action('wp_footer', function() {
    $current_user = wp_get_current_user();
    
    // فقط برای کاربران وارد شده پوش را نمایش دهید
    if ($current_user->ID) {
        $settings = Metrix_Settings::get_settings();
        
        if ($settings['push_enabled']) {
            ?>
            <script>
            document.addEventListener('DOMContentLoaded', function() {
                // بررسی کنید آیا کاربر قبلاً مشترک شده است
                Metrix.getPushState().then(function(state) {
                    if (state !== 'subscribed') {
                        // نمایش پیام سفارشی
                        showCustomPushPrompt();
                    }
                });
            });
            
            function showCustomPushPrompt() {
                // منطق رابط کاربری سفارشی شما در اینجا
                console.log('کاربر در پوش مشترک نشده است');
            }
            </script>
            <?php
        }
    }
});
?>

نیاز به HTTPS

مهم: اعلان‌های پوش وب نیاز به HTTPS دارند. اگر وب‌سایت شما از HTTP استفاده می‌کند:

  1. به HTTPS ارتقا دهید (بسیار توصیه می‌شود)
  2. یک گواهی SSL دریافت کنید (رایگان از طریق Let’s Encrypt)
  3. سرور وب خود را برای تغییر مسیر HTTP به HTTPS پیکربندی کنید
  4. در: SSL Labs  تست کنید

برای بررسی اینکه آیا سایت شما از HTTPS استفاده می‌کند:

<?php
if (is_ssl()) {
    echo "سایت شما از HTTPS استفاده می‌کند ✓";
} else {
    echo "سایت شما از HTTP استفاده می‌کند ✗ (اعلان‌های پوش کار نخواهند کرد)";
}
?>

ایجاد و ارسال کمپین‌های پوش

پس از اینکه کاربران مشترک شدند، می‌توانید اعلان‌های پوش را ارسال کنید:

از طریق داشبورد Metrix

  1. به داشبورد Metrix خود وارد شوید

  2. به پوش وب (Web Push) → ایجاد کمپین (Create Campaign) → کمپین‌ها (Campaigns) → اتومیشن (Automation) بروید

  3. کمپین خود را تعریف کنید:

    • عنوان (Title): نام کمپین (برای ارجاع شما)
    • عنوان اعلان (Notification Title): پیامی که در اعلان نمایش داده می‌شود
    • بدنه اعلان (Notification Body): پیام با جزئیات بیشتر
    • تصویر (Image): تصویر اختیاری اعلان
    • آدرس اینترنتی (URL): جایی که کاربران پس از کلیک روی اعلان به آنجا می‌روند

  4. هدف‌گیری کاربران (Target Users):

    • همه مشترکین
    • سگمنت‌های خاص کاربر
    • کاربران با ویژگی‌های خاص
    • کاربرانی که رویدادهای خاصی را انجام داده‌اند

  5. زمان‌بندی (Schedule):

    • ارسال فوری
    • زمان‌بندی برای بعد
    • ارسال اعلان‌های تکرارشونده

  6. بررسی و ارسال (Review & Send): تأیید و انتشار

عیب‌یابی

اعلان‌های پوش نمایش داده نمی‌شوند

دلایل احتمالی:

  • HTTPS فعال نیست (الزامی است)
  • کلید عمومی نادرست است
  • سرویس ورکر ثبت نشده است
  • کاربر اعلان‌ها را در مرورگر مسدود کرده است

راه‌حل‌ها:

  1. بررسی HTTPS:

    <?php
if (!is_ssl()) {
    echo "خطا: HTTPS برای اعلان‌های پوش الزامی است";
}
?>

  2. تأیید کلید عمومی:

    • به داشبورد Metrix وارد شوید
    • به فضای کاری (Workspace) → تنظیمات (Settings) → تنظیمات پوش وب (Web Push Settings) بروید
    • با مقدار موجود در مدیریت وردپرس مقایسه کنید

  3. بررسی سرویس ورکر:

    • DevTools مرورگر (F12) را باز کنید
    • به Application → Service Workers بروید
    • به دنبال metrix-sw.js بگردید
    • باید “فعال و در حال اجرا” (activated and running) را نشان دهد

  4. مجوزهای مرورگر:

    • کاربر ممکن است اعلان‌ها را مسدود کرده باشد
    • از کاربر بخواهید تنظیمات اعلان مرورگر را بررسی کند
    • داده‌های سایت را پاک کرده و دوباره امتحان کنید

خطای “Push permission denied” (اجازه پوش رد شد)

دلایل احتمالی:

  • کاربر اجازه را رد کرده است
  • تنظیمات حریم خصوصی مرورگر اعلان‌ها را مسدود می‌کند
  • کاربر قبلاً اجازه را رد کرده است

راه‌حل‌ها:

  1. کاربر اجازه را رد کرده است:

    • دستورالعمل‌هایی برای فعال‌سازی مجدد در تنظیمات مرورگر ارائه دهید
    • بعداً دوباره امتحان کنید (مزاحم نشوید)

  2. تنظیمات حریم خصوصی مرورگر:

    • کاربران را به: تنظیمات ← حریم خصوصی ← اعلان‌ها راهنمایی کنید
    • دامنه خود را به سایت‌های مجاز اضافه کنید

  3. فعال‌سازی مجدد پس از رد شدن:

    • مرورگر رد شدن را به خاطر می‌آورد
    • کاربر باید به صورت دستی در تنظیمات فعال کند یا داده‌های سایت را پاک کند

آیکون زنگوله ظاهر نمی‌شود

دلایل احتمالی:

  • گزینه “نمایش زنگوله” تیک نخورده است
  • اعلان‌های پوش غیرفعال هستند
  • تداخل CSS که عنصر را پنهان می‌کند
  • خطاهای جاوااسکریپت در کنسول

راه‌حل‌ها:

  1. بررسی تنظیمات:

    • به Metrix در مدیریت وردپرس بروید
    • تأیید کنید که فعال‌سازی اعلان پوش تیک خورده باشد
    • تأیید کنید که نمایش زنگوله تیک خورده باشد
    • روی ذخیره کلیک کنید

  2. بررسی کنسول مرورگر:

    • DevTools (F12) را باز کنید
    • به دنبال خطاهای جاوااسکریپت بگردید
    • برگه Network را برای درخواست‌های ناموفق بررسی کنید

  3. تداخل CSS:

    • بررسی کنید آیا CSS دیگری .metrix-push-bell را پنهان می‌کند
    • یک قاعده CSS خاص برای نمایش آن اضافه کنید:
    .metrix-push-bell { display: block !important; }

ثبت سرویس ورکر ناموفق بود

دلایل احتمالی:

  • فایل سرویس ورکر پیدا نشد
  • پیکربندی نادرست سرور
  • مشکلات کش مرورگر

راه‌حل‌ها:

  1. تأیید وجود فایل:

    https://yourdomain.com/metrix-sw.js

    این آدرس را در مرورگر بازدید کنید - باید کد جاوااسکریپت را نشان دهد

  2. پاک کردن کش:

    • رفرش سخت: Ctrl+Shift+R (ویندوز) یا Cmd+Shift+R (مک)
    • یا کش و کوکی‌های مرورگر را پاک کنید

  3. پیکربندی سرور:

    • بررسی کنید آیا فایل‌های .js به درستی ارائه می‌شوند
    • تأیید کنید سرور اجازه دسترسی اسکریپت در ریشه را می‌دهد

کلیک روی اعلان کار نمی‌کند

دلایل احتمالی:

  • آدرس اینترنتی (URL) نامعتبر است
  • کنترل‌کننده کلیک پیکربندی نشده است
  • محدودیت‌های امنیتی مرورگر

راه‌حل‌ها:

  1. بررسی آدرس اینترنتی کمپین:

    • اطمینان حاصل کنید که آدرس اینترنتی کامل و معتبر است
    • آدرس اینترنتی را به صورت دستی در مرورگر تست کنید

  2. تأیید پیکربندی:

    • بررسی کنید که اقدام کلیک اعلان در کمپین تنظیم شده باشد
    • برخی مرورگرها به آدرس اینترنتی کامل نیاز دارند (نه مسیرهای نسبی)

مباحث پیشرفته

مدیریت سفارشی اعلان

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

// در metrix-sw.js یا سرویس ورکر سفارشی
self.addEventListener('push', function(event) {
    const data = event.data.json();
    
    // ظاهر اعلان را سفارشی کنید
    const options = {
        body: data.body,
        icon: data.icon,
        badge: data.badge,
        image: data.image,
        tag: 'metrix-notification',
        requireInteraction: true // نیاز به تعامل دارد
    };
    
    event.waitUntil(
        self.registration.showNotification(data.title, options)
    );
});

فعال‌سازی مشروط پوش

پوش را فقط برای انواع خاصی از کاربران فعال کنید:

<?php
add_action('wp_footer', function() {
    $current_user = wp_get_current_user();
    $settings = Metrix_Settings::get_settings();
    
    // فقط برای کاربران ویژه فعال شود
    if ($current_user->ID && user_has_role($current_user, 'premium')) {
        // فعال‌سازی اعلان‌های پوش
    } else {
        // غیرفعال کردن پوش برای دیگران
    }
});
?>
Tracking EventsGoogle Tag Manager