دادهٔ اضافی (Additional Data) — مستندات پوشفا

Additional Data چیست؟

گاهی لازم است همراه نوتیفیکیشن، داده‌های ساختاریافته‌ای (مثل شناسهٔ سفارش، نوع کمپین یا هر متادیتای دلخواه) به سمت کلاینت بفرستید تا اپ یا سرویس‌ورکر بر اساس آن تصمیم بگیرد. با فیلد additional_data می‌توانید یک شیء JSON دلخواه ضمیمه کنید. این داده داخل بخش data پیام FCM قرار می‌گیرد و از طریق API دریافت نوتیفیکیشن‌ها هم برگردانده می‌شود.

این قابلیت فقط برای کاربران حرفه‌ای فعال است و مدیر سامانه می‌تواند آن را به‌صورت سراسری روشن/خاموش کند. در غیر این صورت مقدار ارسالی نادیده گرفته می‌شود.

استفاده از پنل

در فرم ارسال، فیلد «Additional Data (JSON)» را با یک شیء JSON معتبر پر کنید؛ مثلاً {"order_id": 42, "type": "promo"}.

پارامتر API

فیلد additional_data در تمام endpoint‌های ارسال پوشفا پشتیبانی می‌شود:

فیلد	توضیح	اجباری
additional_data	شیء JSON دلخواه که همراه نوتیفیکیشن ارسال و قابل بازیابی است	خیر

نمونه درخواست API

ارسال تکی همراه دادهٔ اضافی:

curl -X POST https://pushfa.com/api/webservices/send-single-message \
  -H "Content-Type: application/json" \
  -d '{
    "api_public_key": "YOUR_PUBLIC_KEY",
    "api_private_key": "YOUR_PRIVATE_KEY",
    "fcm_token": "USER_FCM_TOKEN",
    "title": "سفارش شما ارسال شد",
    "body": "کد رهگیری را ببینید",
    "additional_data": { "order_id": 42, "type": "order_update" },
    "sendTime": "current"
  }'

دریافت در سایت با رویداد pushfaMessage

ساده‌ترین راه برای خواندن دادهٔ اضافی در سایت شما، گوش دادن به رویداد pushfaMessage است. SDK پوشفا هر پیام دریافتی (چه در پیش‌زمینه و چه هنگام نمایش از سرویس‌ورکر) را به‌صورت یک CustomEvent روی window منتشر می‌کند و مقدار additional_data را به‌صورت یک شیء JavaScript آمادهٔ مصرف (نه رشته) در e.detail.additionalData قرار می‌دهد:

مقدار additionalData از قبل JSON.parse شده است؛ نیازی به تبدیل دستی ندارید. اگر چیزی ارسال نشده باشد مقدار آن null است.

window.addEventListener('pushfaMessage', (e) => {
  const data = e.detail.additionalData; // { order_id: 42, type: "order_update" }
  if (data && data.type === 'order_update') {
    // مثال: نمایش وضعیت سفارش داخل سایت
    showOrderStatus(data.order_id);
  }
});

دریافت در سرویس‌ورکر و هنگام کلیک

اگر منطق شما در خود سرویس‌ورکر اجرا می‌شود، داده هم در شیء data نوتیفیکیشن (event.notification.data.additionalData، به‌صورت شیء آماده) و هم در payload خام پیام FCM زیر کلید additional_data (به‌صورت رشتهٔ JSON) در دسترس است. این مقدار را می‌توانید هنگام نمایش یا در رویداد notificationclick بخوانید.

دریافت از طریق API

علاوه بر سمت کلاینت، API دریافت نوتیفیکیشن‌های کاربر نیز همان مقدار additional_data را در پاسخ هر آیتم برمی‌گرداند — مناسب پردازش سمت سرور:

در پاسخ، هر آیتم فیلد additional_data مربوط به خودش را دارد.

curl https://pushfa.com/api/notifications/USER_FCM_TOKEN

چه زمانی از Additional Data استفاده کنیم؟

این قابلیت زمانی به کار می‌آید که علاوه بر نمایش نوتیفیکیشن، می‌خواهید سایت یا اپ شما رفتار خاصی بر اساس محتوای پیام انجام دهد. موارد رایج: همگام‌سازی وضعیت سفارش یا سبد خرید بدون نیاز به درخواست جداگانه به سرور، هدایت کاربر به صفحهٔ مرتبط با شناسهٔ موجود در داده، به‌روزرسانی شمارندهٔ پیام‌های خوانده‌نشده، برچسب‌گذاری کمپین برای تحلیل (utm/campaign_id)، یا اجرای منطق سفارشی هنگام کلیک. اگر فقط می‌خواهید کاربر را به یک URL ببرید، به Additional Data نیاز ندارید و استفاده از «لینک مقصد» کافی است.

حجم additional_data را کوچک نگه دارید؛ این داده داخل payload پیام FCM ارسال می‌شود و محدودیت اندازهٔ پیام را اشغال می‌کند. اطلاعات حساس را در آن قرار ندهید چون در سمت کلاینت قابل خواندن است.