افزونه‌های متصل و رابط‌ها

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

این صفحه «افزونه‌های متصل» را شرح می‌دهد: هر افزونه یا سیستمی که بخواهد از راه پوشیار اعلان بفرستد. چهار راه هست: افزونه‌ای که خودش را ثبت می‌کند، یک محرک که به قلاب (hook) یک افزونه‌ی دیگر گوش می‌دهد، یک کلید برای سیستمی بیرون از سایت، و یک وب‌هوک که نتیجه‌ی ارسال را به سیستم بیرونی خبر می‌دهد. هر کادر این صفحه جدا با یک ماژول خاموش می‌شود (ماژول‌ها).

افزونه‌های متصل#

نشانی: «پوشیار ← افزونه‌های متصل» (admin.php?page=pushyar-connections). جدولی از افزونه‌های ثبت‌شده با ستون‌های «افزونه»، «نسخه» و «رویدادها» (نام هر رویداد و کلیدش). اگر چیزی ثبت نشده باشد «هنوز هیچ افزونه‌ای متصل نشده است.» می‌بینید. متن هر رویداد در قالب‌ها ویرایش می‌شود.

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

اعلان از هر افزونه‌ای، بدون کدنویسی#

(ماژول «اعلان از هر افزونه».) هر افزونه کارهایش را با قلاب اعلام می‌کند. نام یکی از آن قلاب‌ها را اینجا می‌نویسید، اعلان را تنظیم می‌کنید و پوشیار هر بار که آن قلاب اجرا شد اعلان را می‌فرستد؛ خود آن افزونه لازم نیست چیزی درباره‌ی پوشیار بداند. جدول محرک‌های ساخته‌شده ستون‌های «محرک»، «قلاب»، «مخاطب»، «حداکثر در هر ساعت» و «اقدام‌ها» (حذف) را دارد و محرک خاموش نشان «خاموش» می‌گیرد. حداکثر ۲۰ محرک می‌شود ساخت. هر چه محرک می‌فرستد بازاریابی است؛ پس ساعت سکوت، سقف روزانه و فاصله‌ی میان پیام‌ها رویش اعمال می‌شود.

دکمه: «ذخیره‌ی محرک».

هشدار: محرکی که پیش از دانستن اینکه قلاب چه می‌فرستد روشن شود می‌تواند اعلانی بفرستد که منظورتان نبوده.

کلید برای سیستم‌های بیرون از این سایت#

(ماژول «کلید برای سیستم‌های بیرونی».) افزونه‌ای روی همین سایت با pushyar_send() می‌فرستد. سیستمی که روی سایت نیست (انبار، CRM، اسکریپت روی سرور دیگر) با کلید، فقط به یک مسیر و به هیچ جای دیگر می‌فرستد. حداکثر ۲۰ کلید.

با «ساخت کلید» همین یک بار کلید کامل نشان داده می‌شود («همین حالا این کلید را کپی کنید…»)؛ بعد فقط نام کوتاه و چند نویسه‌ی اولش دیده می‌شود. جدول کلیدها ستون‌های «کلید»، «حداکثر در هر ساعت»، «آخرین استفاده» (یا «هرگز») و «اقدام‌ها» («خاموش‌کردن/روشن‌کردن» و «حذف») دارد.

سیستم بیرونی یک درخواست POST به این نشانی می‌فرستد و کلید را در سرآیند X-Pushyar-Key می‌گذارد (قالب نام‌کوتاه.راز):

POST https://example.com/wp-json/pushyar/v1/app/send
X-Pushyar-Key: <short name>.<secret>
Content-Type: application/json

{
  "id": "order-1043-shipped",
  "purpose": "transactional",
  "recipient": { "email": "customer@example.com" },
  "content": { "title": "Your order is on its way", "url": "https://example.com/track/1043" }
}

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

(ماژول «وب‌هوک تحویل».) سیستمی که اعلان می‌فرستد فقط «در صف» می‌شنود. وب‌هوک بقیه‌ی پاسخ است: وقتی اعلان واقعاً تمام شد (تحویل شد یا نه، و به چند مرورگر)، پوشیار آن پایان را به نشانی‌ای که آن سیستم دارد می‌فرستد. آنچه از سایت بیرون می‌رود «پیام» است نه «آدم»: نه نشانی، نه مرورگر، نه حساب. هر تماس امضا دارد و هرگز در حالی که کسی منتظر باز شدن صفحه است انجام نمی‌شود. حداکثر ۱۰ وب‌هوک.

با «افزودن وب‌هوک» راز امضا یک بار نشان داده می‌شود. در جدول برای هر وب‌هوک «خاموش‌کردن/روشن‌کردن»، «راز تازه» (چرخاندن راز) و «حذف» هست و ستون «آخرین تماس» نتیجه‌ی آخرین تماس را می‌گوید. رویداد message.finished با سرآیندهای X-Pushyar-Event و X-Pushyar-Signature (به شکل t=…,v1=…) می‌رسد. گیرنده امضا را با HMAC-SHA256 از زمان.بدنه‌ی خام و راز می‌سنجد و باید اختلاف زمان را کمتر از ۳۰۰ ثانیه بپذیرد:

{
  "event": "message.finished",
  "sent_at": "2026-01-01T12:00:00+00:00",
  "site": "https://example.com/",
  "data": { "source": "warehouse", "id": "order-1043-shipped", "message": 1043,
            "status": "sent", "reason": "",
            "counts": { "sent": 2, "failed": 0, "expired": 0, "capped": 0, "stale": 0 } }
}

برای برنامه‌نویسان#

افزونه‌ی شما روی کنش pushyar/register_sources خودش را با pushyar_register_source() ثبت می‌کند و با pushyar_send() می‌فرستد. پیام در صف می‌رود و در پس‌زمینه ارسال می‌شود؛ متن آن از صفحه‌ی «قالب‌ها» می‌آید و مدیر سایت می‌تواند عوضش کند. پیش از فرستادن pushyar_is_ready() را بپرسید.

add_action( 'pushyar/register_sources', function () {
    pushyar_register_source( 'my-plugin', array(
        'label'  => 'My Plugin',
        'events' => array(
            'order.shipped' => array(
                'label'     => 'Order shipped',
                'variables' => array( 'order_number' => 'Order number' ),
                'defaults'  => array( 'title' => 'Your order is on its way', 'body' => 'Order {order_number} has shipped.' ),
            ),
        ),
    ) );
} );

if ( function_exists( 'pushyar_is_ready' ) && pushyar_is_ready() ) {
    pushyar_send( array(
        'source'    => 'my-plugin',
        'id'        => 'order-shipped-1234',
        'type'      => 'order.shipped',
        'purpose'   => 'transactional',
        'recipient' => array( 'user_id' => 7 ),
        'payload'   => array( 'order_number' => '1234' ),
    ) );
}

دو پرسش دیگر: pushyar_can_reach( array( 'user_id' => 7 ) ) می‌گوید آیا پیام به یک مرورگر زنده می‌رسد، و pushyar_subscriber_count() می‌گوید سایت به چند مرورگر می‌تواند بفرستد. مرورگر مهمان با اشتراک خودش نشانی داده می‌شود: recipient => array( 'subscriber' => 12 ) (شناسه را از کنش pushyar/subscribed می‌گیرید). توابع pushyar_tag_subscriber()، pushyar_untag_subscriber()، pushyar_set_subscriber_attributes() و pushyar_subscriber_tags() برچسب و ویژگی اشتراک را می‌خوانند و می‌نویسند. هر خطا یک WP_Error است، نه خطای PHP.

صندوق درون‌سایت#

(ماژول «صندوق درون‌سایت».) برای اعضای واردشده، کانال «درون‌سایت» اعلان‌ها را در یک صندوق نگه می‌دارد. با کد کوتاه [pushyar_inbox] در هر صفحه نمایش داده می‌شود: عنوان «اعلان‌ها»، دکمه‌ی «همه خوانده شد» و در نبود اعلان «هنوز اعلانی ندارید.»؛ به بازدیدکننده‌ی واردنشده «برای دیدن اعلان‌هایتان وارد شوید.» نشان داده می‌شود. با خاموش‌کردن ماژول، نشانی صندوق و کد کوتاه چیزی چاپ نمی‌کنند.