دادهٔ اضافی (Additional Data)
یک شیء JSON دلخواه همراه اعلان پوش ارسال کنید و در سرویسورکر/SDK یا از طریق API دریافت آن را بخوانید. ویژهٔ کاربران حرفهای.
Additional Data چیست؟
گاهی لازم است همراه اعلان، دادههای ساختاریافتهای (مثل شناسهٔ سفارش، نوع کمپین یا هر متادیتای دلخواه) به سمت کلاینت بفرستید تا اپ یا سرویسورکر بر اساس آن تصمیم بگیرد. با فیلد additional_data میتوانید یک شیء JSON دلخواه ضمیمه کنید. این داده داخل بخش data پیام FCM قرار میگیرد و از طریق API دریافت اعلانها هم برگردانده میشود.
استفاده از پنل
در فرم ارسال، فیلد «Additional Data (JSON)» را با یک شیء JSON معتبر پر کنید؛ مثلاً {"order_id": 42, "type": "promo"}.
پارامتر API
فیلد additional_data در وبسرویسهای ارسال کامل پوشفا پشتیبانی میشود و در مسیرهای lite پشتیبانی نمیشود:
| فیلد | توضیح | اجباری |
|---|---|---|
| additional_dataAdditional DataPro | Additional Data (JSON) — شیء JSON دلخواه که همراه اعلان ارسال و قابل بازیابی است | خیر - فقط Pro |
نمونه درخواست 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",
"subscriber_id": "SUBSCRIBER_UUID",
"title": "سفارش شما ارسال شد",
"body": "کد رهگیری را ببینید",
"additional_data": { "order_id": 42, "type": "order_update" },
"send_time": "current"
}'دریافت در سایت با رویداد pushfaMessage
سادهترین راه برای خواندن دادهٔ اضافی در سایت شما، گوش دادن به رویداد pushfaMessage است. SDK پوشفا هر پیام دریافتی (چه در پیشزمینه و چه هنگام نمایش از سرویسورکر) را بهصورت یک CustomEvent روی window منتشر میکند و مقدار additional_data را بهصورت یک شیء JavaScript آمادهٔ مصرف (نه رشته) در e.detail.additionalData قرار میدهد:
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، بهصورت شیء آماده) و هم در دادههای پیام خام پیام FCM زیر کلید additional_data (بهصورت رشتهٔ JSON) در دسترس است. این مقدار را میتوانید هنگام نمایش یا در رویداد notificationclick بخوانید.
دریافت از طریق API
علاوه بر سمت کلاینت، API دریافت اعلانهای کاربر نیز همان مقدار additional_data را در پاسخ هر آیتم برمیگرداند — مناسب پردازش سمت سرور:
curl https://pushfa.com/api/notifications/SUBSCRIBER_UUIDچه زمانی از Additional Data استفاده کنیم؟
این قابلیت زمانی به کار میآید که علاوه بر نمایش اعلان، میخواهید سایت یا اپ شما رفتار خاصی بر اساس محتوای پیام انجام دهد. موارد رایج: همگامسازی وضعیت سفارش یا سبد خرید بدون نیاز به درخواست جداگانه به سرور، هدایت کاربر به صفحهٔ مرتبط با شناسهٔ موجود در داده، بهروزرسانی شمارندهٔ پیامهای خواندهنشده، برچسبگذاری کمپین برای تحلیل (utm/campaign_id)، یا اجرای منطق سفارشی هنگام کلیک. اگر فقط میخواهید کاربر را به یک URL ببرید، به Additional Data نیاز ندارید و استفاده از «لینک مقصد» کافی است.