افزونه وردپرس (آزمایشی)

دانلود افزونه رسمی پوشفا

نسخه ۱.۰.۱ افزونه برای WordPress 6.0 یا جدیدتر و PHP 7.4 یا جدیدتر آماده است. فایل ZIP را بدون خارج‌کردن از حالت فشرده از پیشخوان وردپرس نصب کنید.

نصب و اتصال اولیه

نگهداری امن کلیدها در wp-config.php

در محیط Production می‌توانید کلیدها و آدرس‌ها را در wp-config.php تعریف کنید. در این حالت فیلد متناظر در پیشخوان غیرفعال می‌شود و Private Key فقط در PHP باقی می‌ماند.

define('PUSHFA_API_PUBLIC_KEY', 'YOUR_PUBLIC_KEY');
define('PUSHFA_API_PRIVATE_KEY', 'YOUR_PRIVATE_KEY');
define('PUSHFA_SDK_BASE_URL', 'https://sdk.pushfa.com');
define('PUSHFA_API_BASE_URL', 'https://pushfa.com/api');

هر قسمت افزونه چه کاری انجام می‌دهد؟

راهنمای گزینه‌های صفحه تنظیمات

Service Worker و خطای 404

افزونه مسیر pushfa-messaging-sw.js را در ریشه دامنه ایجاد می‌کند و پس از فعال‌سازی یا ذخیره تنظیمات Rewrite وردپرس را نوسازی می‌کند. آدرس زیر باید با JavaScript پاسخ دهد، نه صفحه HTML یا 404.

https://example.com/pushfa-messaging-sw.js

Prompt عضویت؛ خودکار یا دستی

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

[pushfa_button
    label="فعال‌سازی اعلان سفارش‌ها"
    subscribed_label="اعلان‌های سفارش فعال است"
    denied_label="اعلان‌ها در مرورگر مسدود شده است"
]

عضویت و لغو عضویت Topic با یک دکمه

Topic یک گروه از Subscriberهاست؛ مانند «تخفیف‌ها»، «اخبار محصول» یا «موجودشدن کالا». از «پوشفا ← Topicها» Topic را بسازید و شورت‌کد تولیدشده را در برگه، نوشته، ابزارک یا Shortcode Widget صفحه‌ساز قرار دهید.

[pushfa_topic_button
    topic="TOPIC_UUID"
    subscribe_label="عضویت در تخفیف‌ها"
    unsubscribe_label="لغو عضویت از تخفیف‌ها"
]

Topic با دکمه اختصاصی JavaScript

اگر شورت‌کد کافی نیست، دکمه HTML خودتان را بسازید. کد را بعد از رویداد pushfaWordPressReady اجرا کنید تا SDK آماده باشد. UUID موضوع را از «پوشفا ← Topicها» کپی کنید؛ نام نمایشی Topic جای UUID نمی‌نشیند.

const topicUuid = 'TOPIC_UUID_FROM_PUSHFA';

window.addEventListener('pushfaWordPressReady', ({ detail }) => {
    const Pushfa = detail.Pushfa;

    document.querySelector('#join-sales').addEventListener('click', async () => {
        await Pushfa.requestPermission();
        await Pushfa.subscribeTopic(topicUuid);
        alert('عضویت انجام شد');
    });

    document.querySelector('#leave-sales').addEventListener('click', async () => {
        await Pushfa.unsubscribeTopic(topicUuid);
        alert('عضویت لغو شد');
    });

    document.querySelector('#check-sales').addEventListener('click', async () => {
        const topics = await Pushfa.getTopics();
        alert(topics.includes(topicUuid) ? 'عضو است' : 'عضو نیست');
    });
});

هویت کاربر؛ Subscriber ID و External ID

افزونه برای هر حساب WordPress یک External ID پایدار و غیرقابل‌حدس مانند wp-UUID در Backend می‌سازد. شناسه عددی User ID در Pushfa افشا نمی‌شود. هر مرورگر یا دستگاه نیز Subscriber ID جداگانه دارد.

تفاوت Alias و Custom Alias

در پوشفا، Alias اصلی همان External ID حساب است. Custom Alias یک شناسه برچسب‌دار مستقل مانند crm_id، vendor_id، mobile یا email است. مقدار External ID با wp_user_ref تکرار نمی‌شود؛ wp_user_ref نسخه‌های قبلی در نخستین همگام‌سازی موفق حذف می‌شود.

add_filter('pushfa_wordpress_identity_aliases', function ($aliases, $user) {
    $vendor_id = get_user_meta($user->ID, 'vendor_id', true);

    if ($vendor_id) {
        $aliases['vendor_id'] = (string) $vendor_id;
    }

    return $aliases;
}, 10, 2);

Custom Alias را چطور روی کاربر ثبت کنیم؟

مرحله ثبت با مرحله ارسال فرق دارد. کد زیر مقدار معتبر را از User Meta وردپرس می‌خواند. هنگام ورود کاربر و همگام‌شدن Subscriber، افزونه آن را در پوشفا ثبت می‌کند. سپس می‌توانید با همان Label و Value پیام بفرستید.

// این کد را یک بار در MU Plugin سایت قرار دهید.
add_filter('pushfa_wordpress_identity_aliases', function ($aliases, $user) {
    $crm_id = get_user_meta($user->ID, 'crm_id', true);

    if ($crm_id !== '') {
        $aliases['crm_id'] = (string) $crm_id;
    }

    return $aliases;
}, 10, 2);

// این خط باید داخل Hook رویداد موردنظر اجرا شود، نه در ابتدای فایل.
pushfa_send_to_alias('crm_id', 'CRM-42', $message);

Bracket و شخصی‌سازی متن پیام

Bracket برای نگهداری ویژگی نمایشی مخاطب است، نه شناسایی او. افزونه می‌تواند first_name، last_name و display_name را از WordPress همگام کند. هنگام ارسال گزینه «شخصی‌سازی Bracket» را فعال کنید.

سلام {first_name:کاربر عزیز}
سفارش شما آماده ارسال است.

ارسال اعلان از پیشخوان WordPress

در «پوشفا ← ارسال اعلان» گیرنده، متن و گزینه‌های پیشرفته را انتخاب کنید. Public Key و Private Key هر دو برای ارسال سروری لازم‌اند.

اجزای پیام و گزینه‌های پیشرفته

کدهای PHP را کجا قرار دهیم؟

کد ارسال را داخل فایل افزونه پوشفا یا قالب اصلی ننویسید. روش پایدار، ساخت یک MU Plugin اختصاصی یا استفاده از افزونه Code Snippets است.

<?php
/**
 * Plugin Name: Pushfa Site Events
 */

defined('ABSPATH') || exit;

// Hookها و تابع‌های ارسال سایت را از اینجا به بعد اضافه کنید.

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

این تابع‌ها را فقط در کد PHP سمت سرور و داخل یک Hook اجرا کنید. شکل کلی همه آن‌ها این است: ابتدا شناسه مقصد، سپس آرایه پیام و در پایان آرایه اختیاری تنظیمات. همه تابع‌ها پاسخ API پوشفا یا WP_Error برمی‌گردانند.

ورودی $message دقیقاً چیست؟

متغیر $message یک آرایه PHP است. حداقل title و body را بدهید. کلیدهای دیگر اختیاری‌اند. نام کلیدها را دقیقاً مانند نمونه بنویسید.

$message = [
    'title'       => 'پرداخت موفق',
    'body'        => 'سفارش شما ثبت شد.',
    'link_url'    => home_url('/my-account/orders/'),
    'image_url'   => 'https://example.com/uploads/order-ready.jpg',
    'platform'    => 'all',
    'sendTime'    => 'current',
    'collapse_id' => 'order-status-123',
];

ورودی $options دقیقاً چیست؟

$options آرایه سوم و اختیاری است. اگر آن را ندهید، افزونه امن‌ترین مقصد پیش‌فرض را انتخاب می‌کند. فقط وقتی می‌خواهید روش هدف‌گیری را عوض کنید از آن استفاده کنید.

$options = [
    'target_mode'     => 'external_id',
    'only_last_device'=> true,
];

$result = pushfa_send_to_user(25, $message, $options);

از کجا بفهمیم ارسال موفق بوده است؟

خروجی تابع را داخل $result بگیرید. WP_Error یعنی درخواست قبل از پذیرش یا هنگام تماس با API شکست خورده است. پاسخ غیرخطا یعنی درخواست توسط API پذیرفته شده؛ این لزوماً تضمین نمایش روی دستگاه نیست.

$result = pushfa_send_to_user(25, $message);

if (is_wp_error($result)) {
    // فقط در محیط عیب‌یابی Log کنید؛ کلید خصوصی را چاپ نکنید.
    error_log('Pushfa error: ' . $result->get_error_message());
    return;
}

// در این نقطه API درخواست را پذیرفته است.

ارسال پیام به یک کاربر WordPress

User ID فقط در Backend وردپرس استفاده می‌شود. افزونه External ID تصادفی همان حساب را پیدا و درخواست احراز‌شده را به پوشفا ارسال می‌کند.

$result = pushfa_send_to_user($user_id, [
    'title'    => 'پیام جدید',
    'body'     => 'یک پیام جدید برای شما ثبت شده است.',
    'link_url' => home_url('/my-account/'),
]);

if (is_wp_error($result)) {
    error_log('Pushfa: ' . $result->get_error_message());
}

تابع pushfa_send_to_order_purchaser؛ ارسال به خریدار

ورودی اول شماره داخلی سفارش است، نه شماره نمایشی سفارش. در حالت auto افزونه ابتدا Subscriber ذخیره‌شده سفارش را امتحان می‌کند؛ برای کاربر عضو از External ID و برای مهمان از Alias سفارش/اطلاعات صورتحساب استفاده می‌کند.

$order_id = 1842;
$message = [
    'title'    => 'سفارش آماده ارسال است',
    'body'     => 'بسته شما تحویل پست شد.',
    'link_url' => home_url('/my-account/orders/'),
];

$result = pushfa_send_to_order_purchaser($order_id, $message);

تابع‌های فروشنده؛ User ID یا Product ID؟

اگر User ID فروشنده را دارید از pushfa_send_to_seller استفاده کنید. اگر فقط Product ID را دارید، pushfa_send_to_product_seller مالک محصول را پیدا می‌کند. هر دو در پایان با هویت امن حساب وردپرس ارسال می‌کنند.

// حالت ۱: شناسه کاربری فروشنده را دارید.
$result = pushfa_send_to_seller(73, [
    'title' => 'سفارش جدید',
    'body'  => 'یک سفارش جدید برای شما ثبت شد.',
]);

// حالت ۲: فقط شناسه محصول را دارید.
$result = pushfa_send_to_product_seller(915, [
    'title' => 'محصول شما فروخته شد',
    'body'  => 'برای مشاهده سفارش وارد پنل شوید.',
]);

تابع pushfa_send_to_subscribers؛ ارسال به دستگاه مشخص

Subscriber ID شناسه یک عضویت مرورگر است. می‌توانید یک رشته، چند مقدار جداشده با ویرگول/خط جدید، یا آرایه بدهید. مقادیر خالی و تکراری حذف می‌شوند.

// یک دستگاه
pushfa_send_to_subscribers('f1444a41-b3af-4e30-8655-9a70de1e0915', $message);

// چند دستگاه
pushfa_send_to_subscribers([
    'SUBSCRIBER_UUID_1',
    'SUBSCRIBER_UUID_2',
], $message);

تابع pushfa_send_to_alias؛ ارسال به Custom Alias

این تابع چهار ورودی دارد: ۱) نام Label، ۲) یک Value یا آرایه Valueها، ۳) پیام و ۴) تنظیمات اختیاری. Label و Value باید قبلاً روی Subscriber ثبت شده باشند.

$message = [
    'title' => 'پیام حسابداری',
    'body'  => 'یک فاکتور جدید برای شما صادر شد.',
];

// یک مقدار
pushfa_send_to_alias('crm_id', 'CRM-42', $message);

// چند مقدار با Label یکسان؛ حداکثر ۱۰۰ مقدار در هر درخواست
pushfa_send_to_alias('vendor_id', ['V-10', 'V-11'], $message, [
    'only_last_device' => true,
]);

تابع pushfa_send_to_token؛ ارسال مستقیم به FCM Token

این روش برای یک Token فنی است. Token ممکن است Refresh یا منقضی شود؛ بنابراین برای منطق کاربر، فروشنده یا سفارش از External ID/Subscriber ID استفاده کنید.

$result = pushfa_send_to_token($fcm_token, [
    'title' => 'پیام آزمایشی',
    'body'  => 'این پیام مستقیماً به Token ارسال شد.',
]);

Hookهای مهم WooCommerce برای ارسال

Hook نقطه‌ای از اجرای WooCommerce است که کد شما در زمان مشخص اجرا می‌شود. یک پیام واحد را هم‌زمان به چند Hook مشابه متصل نکنید.

نمونه کامل ارسال بعد از پرداخت موفق

این نمونه از متای سفارش برای جلوگیری از ارسال تکراری استفاده می‌کند و فقط بعد از پذیرفته‌شدن درخواست توسط پوشفا، علامت ارسال‌شده را ذخیره می‌کند.

add_action('woocommerce_payment_complete', function ($order_id) {
    if (!function_exists('pushfa_send_to_order_purchaser')) {
        return;
    }

    $order = wc_get_order($order_id);
    if (!$order || $order->get_meta('_pushfa_payment_notification_sent')) {
        return;
    }

    $result = pushfa_send_to_order_purchaser($order_id, [
        'title'       => 'پرداخت موفق',
        'body'        => sprintf(
            'پرداخت سفارش شماره %s با موفقیت انجام شد.',
            $order->get_order_number()
        ),
        'link_url'    => $order->get_view_order_url(),
        'collapse_id' => 'payment-' . $order_id,
    ]);

    if (!is_wp_error($result)) {
        $order->update_meta_data(
            '_pushfa_payment_notification_sent',
            current_time('mysql')
        );
        $order->save();
    } elseif (defined('WP_DEBUG') && WP_DEBUG) {
        error_log('Pushfa: ' . $result->get_error_message());
    }
}, 20);

ارسال اعلان سفارش جدید به فروشنده

در فروشگاه ساده، مالک محصول معمولاً post_author است. نمونه زیر فروشندگان سفارش را یکتا می‌کند تا فروشنده‌ای که چند محصول در سفارش دارد چند پیام یکسان نگیرد.

add_action('woocommerce_payment_complete', function ($order_id) {
    $order = wc_get_order($order_id);
    if (!$order) {
        return;
    }

    $seller_ids = [];
    foreach ($order->get_items() as $item) {
        $product_id = $item->get_product_id();
        $seller_id = (int) get_post_field('post_author', $product_id);

        if ($seller_id > 0) {
            $seller_ids[$seller_id] = true;
        }
    }

    foreach (array_keys($seller_ids) as $seller_id) {
        pushfa_send_to_seller($seller_id, [
            'title'    => 'سفارش جدید',
            'body'     => 'یک سفارش جدید برای محصولات شما ثبت شد.',
            'link_url' => admin_url('post.php?post=' . $order_id . '&action=edit'),
        ]);
    }
}, 30);

ارسال با Subscriber ID یا Custom Alias

// ارسال به دستگاه‌های مشخص
pushfa_send_to_subscribers([
    'SUBSCRIBER_UUID_1',
    'SUBSCRIBER_UUID_2',
], $message);

// ارسال با شناسه CRM
pushfa_send_to_alias('crm_id', ['CRM-42'], $message);

// هدف‌گیری صریح سفارش مهمان با شناسه داخلی سفارش
pushfa_send_to_order_purchaser($order_id, $message, [
    'target_mode' => 'custom_alias',
    'label'       => 'wp_order_ref',
]);

ارسال خودکار هنگام انتشار محتوا

در تنظیمات افزونه می‌توانید اولین انتشار نوشته، برگه یا محصول را به Topic موردنظر یا all ارسال کنید. افزونه با متای داخلی از ارسال دوباره در ویرایش‌های بعدی جلوگیری می‌کند.

مرجع کامل Filterهای افزونه

Filter مقداری را از افزونه می‌گیرد، شما آن را تغییر می‌دهید و حتماً با return برمی‌گردانید. عدد 10 اولویت و عدد آخر تعداد ورودی‌های Callback است.

add_filter('pushfa_wordpress_product_seller_user_id', function ($seller_id, $product, $options) {
    // شناسه فروشنده را با API افزونه Marketplace خودتان پیدا کنید.
    $marketplace_seller_id = (int) get_post_meta($product->ID, '_vendor_user_id', true);

    return $marketplace_seller_id ?: $seller_id;
}, 10, 3);

مثال Filterهای هویت، Bracket و پیام خودکار

// ۱) Custom Alias معتبر از User Meta
add_filter('pushfa_wordpress_identity_aliases', function ($aliases, $user) {
    $aliases['vendor_id'] = get_user_meta($user->ID, 'vendor_id', true);
    return array_filter($aliases);
}, 10, 2);

// ۲) Bracket شهر برای متن‌هایی مانند «ارسال به {city:شهر شما}»
add_filter('pushfa_wordpress_identity_brackets', function ($brackets, $user) {
    $brackets['city'] = get_user_meta($user->ID, 'billing_city', true);
    return array_filter($brackets);
}, 10, 2);

// ۳) تغییر پیام ارسال خودکار محصول
add_filter('pushfa_wordpress_auto_notification_message', function ($message, $post, $old_status) {
    if ($post->post_type === 'product') {
        $message['title'] = 'محصول جدید: ' . get_the_title($post);
        $message['link_url'] = get_permalink($post);
    }
    return $message;
}, 10, 3);

Actionهای آماده افزونه و مثال استفاده

Action فقط خبر می‌دهد که اتفاقی رخ داده است؛ لازم نیست چیزی return کنید. افزونه دو Action عمومی دارد.

// مثال ۱: بعد از ذخیره Subscriber، کار جانبی سایت خودتان را انجام دهید.
add_action('pushfa_wordpress_subscriber_stored', function ($subscriber_id, $user_id, $order_id) {
    if ($user_id) {
        update_user_meta($user_id, '_pushfa_last_connected_at', current_time('mysql'));
    }
}, 10, 3);

// مثال ۲: نتیجه ارسال خودکار انتشار را بررسی کنید.
add_action('pushfa_wordpress_auto_notification_sent', function ($post, $result) {
    if (is_wp_error($result) && defined('WP_DEBUG') && WP_DEBUG) {
        error_log('Pushfa auto send failed for post ' . $post->ID . ': ' . $result->get_error_message());
    }
}, 10, 2);

API آماده JavaScript افزونه

برای کد مرورگر ابتدا منتظر pushfaWordPressReady بمانید. شیء window.PushfaWordPress سه تابع کمکی افزونه دارد و detail.Pushfa توابع اصلی SDK مانند Topic و Prompt را در اختیار می‌گذارد.

window.addEventListener('pushfaWordPressReady', async ({ detail }) => {
    // رویداد سفارشی RetenX
    await window.PushfaWordPress.track('article_read', {
        post_id: 125,
        category: 'آموزش'
    });

    // وضعیت دکمه‌های افزونه را دوباره بخوان.
    await window.PushfaWordPress.refresh();

    // تابع‌های SDK اصلی نیز اینجا آماده‌اند.
    const topics = await detail.Pushfa.getTopics();
    console.log(topics);
});

WooCommerce و RetenX

با فعال‌کردن RetenX، افزونه رویدادهای استاندارد فروشگاه را برای ساخت Journeyهای نگهداشت ارسال می‌کند. این بخش اختیاری است و به دسترسی Pro و Private Key نیاز دارد.

اعلان در تب فعال و iPhone/iPad

در تنظیمات می‌توانید رفتار Foreground را از سرویس ارث‌بری کنید، اعلان سیستمی را در تب فعال مخفی کنید یا نمایش را اجبار کنید. گزینه اعلان درون‌صفحه‌ای پیام Foreground را به‌شکل Toast نمایش می‌دهد.

امنیت و حریم خصوصی

عیب‌یابی سریع