مدیریت Topic وب پوش؛ عضویت و ارسال موضوعی

کاربران را در تاپیک‌های پوشفا عضو یا لغو عضویت کنید؛ روش مدیریت موضوع‌ها و استفاده از آن‌ها برای ارسال پوش هدفمند را با مثال ببینید.

تاپیک چیست؟

تاپیک‌ها در پوشفا مانند دسته‌بندی‌های مشترک هستند. برای هر سرویس می‌توانید یک یا چند تاپیک بسازید و کاربران را در موقعیت‌های مختلف عضو یا خارج کنید. مثلاً مشترکین علاقه‌مند به یک دسته محصول را عضو تاپیک آن دسته کنید و بعداً اعلان‌ها را فقط به همان تاپیک بفرستید.

شناسه ثابت مخاطب (Subscriber ID)؟ (توصیه‌شده)

همه وب‌سرویس‌های مدیریت تاپیک (عضویت، لغو عضویت و دریافت تاپیک‌های دستگاه) در فیلد subscriber_id شناسه ثابت مخاطب (Subscriber ID) را می‌پذیرند. روش توصیه‌شده این است که ابتدا شناسه ثابت مخاطب (Subscriber ID) دستگاه را دریافت کنید و همان مقدار را به این وب‌سرویس‌ها بفرستید.

Subscriber ID شناسه‌ای است که حتی پس از تجدید توکن FCM تغییر نمی‌کند، بنابراین پایدارتر از توکن FCM است. برای نحوه دریافت آن به بخش «دریافت توکن و شناسه ثابت مخاطب (Subscriber ID)» مراجعه کنید.

ساخت تاپیک در پنل

در بخش سرویس‌ها روی آیکن تاپیک کلیک کنید. تاپیک جدید بسازید، نامی منحصربه‌فرد انتخاب کنید و UUID آن را یادداشت کنید.

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

عضو کردن کاربر از جاوااسکریپت

UUID تاپیک را از پنل بردارید. در زمان مناسب (مثلاً بعد از کلیک روی یک دسته‌بندی) این متد را صدا بزنید:

await window.Pushfa.subscribeTopic('TOPIC-UUID');

لغو عضویت از جاوااسکریپت

برای خارج کردن دستگاه فعلی از یک تاپیک:

await window.Pushfa.unSubscribeTopic('TOPIC-UUID');

بررسی تاپیک‌های دستگاه

لیست UUID تاپیک‌های ذخیره‌شده روی دستگاه فعلی را بخوانید و دکمه عضویت/لغو عضویت را بر اساس آن نمایش دهید:

const topics = await window.Pushfa.getDeviceTopics();
const topicId = 'TOPIC-UUID';

if (topics.includes(topicId)) {
  // کاربر عضو است — دکمه لغو عضویت نشان بده
} else {
  // کاربر عضو نیست — دکمه عضویت نشان بده
}

کنترل دسترسی تاپیک از جاوااسکریپت

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

تاپیک‌هایی که کاربر قبلاً عضو آن‌هاست، در صورت غیرفعال بودن «لغو عضویت از جاوااسکریپت»، با درخواست‌های مرورگری حذف نمی‌شوند.

وب‌سرویس: ساخت تاپیک و دریافت UUID

POST
https://pushfa.com/api/topics/create

از سمت سرور خودتان می‌توانید یک تاپیک جدید بسازید و UUID آن را در پاسخ دریافت کنید. به کلید عمومی و خصوصی نیاز دارد. فقط فیلد name اجباری است؛ بقیه فیلدها اختیاری و پیش‌فرض false هستند.

پاسخ شامل اطلاعات تاپیک ساخته‌شده است که فیلد id آن همان UUID تاپیک است؛ از این UUID برای عضو کردن کاربران و ارسال اعلان استفاده کنید.
پارامترمقداراجباری
api_public_key کلید عمومی سرویس بله
api_private_key کلید خصوصی سرویس بله
name نام تاپیک بله
send_membership_notification ارسال اعلان هنگام عضویت/خروج (boolean) خیر
allow_js_register اجازه عضویت از جاوااسکریپت (boolean) خیر
allow_js_unregister اجازه لغو عضویت از جاوااسکریپت (boolean) خیر
allow_js_get اجازه دریافت لیست از جاوااسکریپت (boolean) خیر
curl -X POST https://pushfa.com/api/topics/create \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "name": "My topic",
    "send_membership_notification": false,
    "allow_js_register": true,
    "allow_js_unregister": true,
    "allow_js_get": true
  }'

وب‌سرویس: عضو کردن توکن در تاپیک

POST
https://pushfa.com/api/topics/subscribe

از سمت سرور خودتان می‌توانید یک دستگاه را در تاپیک عضو کنید:

فیلد subscriber_id شناسه ثابت مخاطب (Subscriber ID) را می‌پذیرد. توصیه می‌شود ابتدا شناسه ثابت مخاطب (Subscriber ID) دستگاه را دریافت و همان را ارسال کنید؛ چون برخلاف توکن FCM با چرخش توکن تغییر نمی‌کند و پایدارتر است.
پارامترمقداراجباری
api_public_key کلید عمومی سرویس بله
api_private_key کلید خصوصی سرویس بله
subscriber_id شناسه ثابت مخاطب (Subscriber ID) دستگاه (استفاده از شناسه ثابت مخاطب توصیه می‌شود) بله
topic_uuid شناسه UUID تاپیک (از پنل دریافت کنید) بله
curl -X POST https://pushfa.com/api/topics/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "subscriber_id": "USER_SUBSCRIBER_ID",
    "topic_uuid": "TOPIC_UUID"
  }'

وب‌سرویس: لغو عضویت مخاطب از تاپیک

POST
https://pushfa.com/api/topics/unsubscribe

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

فیلد subscriber_id شناسه ثابت مخاطب (Subscriber ID) را می‌پذیرد. توصیه می‌شود از شناسه ثابت مخاطب (Subscriber ID) دستگاه استفاده کنید.
پارامترمقداراجباری
api_public_key کلید عمومی سرویس بله
api_private_key کلید خصوصی سرویس بله
subscriber_id شناسه ثابت مخاطب (Subscriber ID) دستگاه (استفاده از شناسه ثابت مخاطب توصیه می‌شود) بله
topic_uuid شناسه UUID تاپیک (از پنل دریافت کنید) بله
curl -X POST https://pushfa.com/api/topics/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "subscriber_id": "USER_SUBSCRIBER_ID",
    "topic_uuid": "TOPIC_UUID"
  }'

وب‌سرویس: دریافت تاپیک‌های یک دستگاه

POST
https://pushfa.com/api/webservices/topics/user-topics

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

پاسخ آرایه‌ای از تاپیک‌ها شامل uuid، name و id است. فیلد subscriber_id شناسه ثابت مخاطب (Subscriber ID) را می‌پذیرد؛ استفاده از شناسه ثابت مخاطب (Subscriber ID) توصیه می‌شود.
پارامترمقداراجباری
api_public_key کلید عمومی سرویس بله
api_private_key کلید خصوصی سرویس بله
subscriber_id شناسه ثابت مخاطب (Subscriber ID) دستگاه بله
curl -X POST https://pushfa.com/api/webservices/topics/user-topics \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "subscriber_id": "SUBSCRIBER_UUID"
  }'

وب‌سرویس: دریافت اعضای یک تاپیک

POST
https://pushfa.com/api/webservices/topics/topic-members

برای دریافت لیست دستگاه‌های عضو یک تاپیک خاص (حداکثر ۱۰۰ دستگاه اول):

پاسخ حداکثر ۱۰۰ دستگاه اول عضو تاپیک را برمی‌گرداند. هر دستگاه شامل توکن و subscriber_id (شناسه ثابت) است؛ برای ارسال‌های بعدی استفاده از subscriber_id توصیه می‌شود.
پارامترمقداراجباری
api_public_key کلید عمومی سرویس بله
api_private_key کلید خصوصی سرویس بله
topic_uuid شناسه UUID تاپیک (از پنل دریافت کنید) بله
curl -X POST https://pushfa.com/api/webservices/topics/topic-members \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "topic_uuid": "TOPIC-UUID"
  }'
Ctrl+I