مدیریت تاپیک‌ها — مستندات پوشفا

تاپیک چیست؟

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

توکن FCM یا Subscriber ID؟ (توصیه‌شده)

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

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

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

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

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

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

از سمت سرور خودتان می‌توانید یک تاپیک جدید بسازید و 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
  }'

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

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

فیلد fcm_token هم توکن FCM و هم Subscriber ID را می‌پذیرد. توصیه می‌شود ابتدا Subscriber ID دستگاه را دریافت و همان را ارسال کنید؛ چون برخلاف توکن FCM ثابت است و امن‌تر و پایدارتر است.

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا 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",
    "fcm_token": "USER_SUBSCRIBER_ID",
    "topic_uuid": "TOPIC_UUID"
  }'

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

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

فیلد fcm_token هم توکن FCM و هم Subscriber ID را می‌پذیرد. توصیه می‌شود از Subscriber ID ثابت دستگاه استفاده کنید.

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا 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",
    "fcm_token": "USER_SUBSCRIBER_ID",
    "topic_uuid": "TOPIC_UUID"
  }'

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

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

پاسخ آرایه‌ای از تاپیک‌ها شامل uuid، name و id است. فیلد fcm_token هم توکن FCM و هم Subscriber ID را می‌پذیرد؛ استفاده از Subscriber ID ثابت توصیه می‌شود.

پارامتر	مقدار	اجباری
api_public_key	کلید عمومی سرویس	بله
api_private_key	کلید خصوصی سرویس	بله
fcm_token	توکن FCM یا 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",
    "fcm_token": "USER_FCM_TOKEN"
  }'

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

برای دریافت لیست دستگاه‌های عضو یک تاپیک خاص از این وب‌سرویس استفاده کنید. UUID تاپیک را از پنل کپی کنید.

پاسخ حداکثر ۱۰۰ دستگاه اول عضو تاپیک را برمی‌گرداند. هر دستگاه شامل token و 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"
  }'