ارسال با شناسه مستعار (Alias)
ارسال اعلان به کاربران از طریق Alias ثبت‌شده بدون نیاز به مدیریت مستقیم توکن‌ها.
کاربرد
وقتی با setUserAliasID شناسه کاربر را در پوشفا ثبت کرده‌اید، می‌توانید به‌جای توکن از همان شناسه برای ارسال استفاده کنید. به‌شکل هوشمندانه، پیام فقط به بهترین دستگاه این شناسه ارسال می‌شود؛ بنابراین پیام تنها به یک دستگاه خواهد رسید.
پارامترهای ورودی
| پارامتر | مقدار | اجباری |
|---|---|---|
| alias | شناسه مستعار کاربر (مقدار ثبت‌شده با setUserAliasID) | بله |
| only_last_device | اگر true باشد، فقط به آخرین دستگاهی که کاربر از آن استفاده کرده ارسال می‌شود. اولویت‌بندی بر اساس visit_at و در صورت برابری، updated_at (جدیدتر = برتر). پیش‌فرض: false | خیر |
| smart_targeting | به‌شکل هوشمندانه، پیام فقط به بهترین دستگاه این شناسه ارسال می‌شود؛ بنابراین پیام تنها به یک دستگاه خواهد رسید. | خیر |
| device | محدودیت دستگاه: mobile | desktop | all | خیر |
| api_public_key | کلید عمومی سرویس پوشفا | بله |
| api_private_key | کلید خصوصی سرویس پوشفا | بله |
| title | عنوانی که بالای اعلان نمایش داده می‌شود | بله |
| body | متن اصلی که زیر عنوان اعلان نمایش داده می‌شود | بله |
| link_url | لینک مقصد پس از کلیک روی اعلان (مثال: https://example.com) | خیر |
| image_url | آدرس تصویر ضمیمه اعلان | خیر |
| use_brackets | برای شخصی‌سازی پیام، مقدار true را بفرستید. در این حالت بخش‌های متغیر عنوان (title) و متن (body) با اطلاعات پروفایل هر گیرنده پر می‌شوند. مقدار پیش‌فرض false است. | خیر |
| btn_left[title] | عنوان دکمه سمت چپ | در صورت تعریف دکمه چپ، الزامی است |
| btn_left[url] | لینک دکمه سمت چپ (مثال: https://example.com) | در صورت تعریف دکمه چپ، الزامی است |
| btn_right[title] | عنوان دکمه سمت راست | در صورت تعریف دکمه راست، الزامی است |
| btn_right[url] | لینک دکمه سمت راست (مثال: https://example.com) | در صورت تعریف دکمه راست، الزامی است |
| throttle_rate_per_minute | نرخ ارسال این پیام بر حسب پیام در دقیقه. فقط وقتی Push Throttling سرویس فعال و اجازه Override روشن باشد مقدار ارسالی جایگزین نرخ پیش‌فرض می‌شود. | خیر |
| silentپوش بی‌صدا | مقدار true اعلان را بدون صدا و لرزش نمایش می‌دهد؛ این گزینه اعلان را پنهان نمی‌کند. | خیر |
| collapse_idCollapse ID | Collapse ID — رشته متنی حداکثر ۱۰۰ کاراکتر برای جایگزینی اعلان قبلی با اعلان جدید دارای همان شناسه. | خیر |
| additional_dataAdditional DataPro | Additional Data (JSON) — شیء JSON دلخواه که همراه پیام ارسال می‌شود و در SDK/Service Worker قابل خواندن است. | خیر - فقط Pro |
| last_visit[operator] | شرط اختیاری آخرین بازدید مخاطب — عملگر مقایسه: >=، >، <=، < یا = | اگر last_visit ارسال شود، الزامی است |
| last_visit[date] | تاریخ مبنای شرط: today (امروز)، today-N (N روز قبل، مثلاً today-7) یا تاریخ میلادی با قالب Y-m-d. پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان (به وقت تهران) با این شرط بخواند؛ مثلاً operator برابر >= و date برابر today یعنی فقط کسانی که امروز بازدید داشته‌اند. اگر last_visit را نفرستید، ارسال بدون این شرط انجام می‌شود. | اگر last_visit ارسال شود، الزامی است |
| get_delivery_status | درخواست گزارش تحویل (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) | خیر |
| webhook_url | آدرس وب‌هوک بومرنگ — در صورت عدم تحویل، نتیجه به این آدرس ارسال می‌شود | خیر |
| get_click_status | درخواست گزارش کلیک (مقدار 1/0 در ارسال تکی یا true/false در ارسال گروهی) | خیر |
| send_time | زمان ارسال؛ current برای ارسال فوری و delay برای زمان‌بندی‌شده. اختیاری و پیش‌فرض current است. نام قدیمی sendTime فعلاً پشتیبانی می‌شود، اما نباید هر دو نام همزمان ارسال شوند. | خیر |
| time | تاریخ میلادی و ساعت تهران (Asia/Tehran) را با قالب Y-m-d H:i وارد کنید؛ ثانیه صفر در نظر گرفته می‌شود. در حالت delay زمان باید بعد از اکنون باشد. تاریخ شمسی پذیرفته نمی‌شود. این قرارداد برای همه وب‌سرویس‌های ارسال، از جمله ارسال به تاپیک، یکسان است. | اگر send_time برابر delay باشد، الزامی است |
| ttl | مدت اعتبار پیام برای تحویل، بر حسب ثانیه. مقدار پیش‌فرض 86400 ثانیه، یعنی ۲۴ ساعت است. | خیر |
نمونه شخصی‌سازی‌شده
{
"alias": "customer-42",
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"title": "{name:کاربر} عزیز",
"body": "سفارش {custom_alias:order_id:شما} آماده ارسال است.",
"use_brackets": true,
"send_time": "current"
}شرط اختیاری آخرین بازدید (last_visit)
با پارامتر اختیاری last_visit پیام فقط برای مخاطبانی ارسال می‌شود که روز آخرین بازدیدشان از سایت یا اپ (به وقت تهران) با شرط شما بخواند. نمونه زیر فقط برای کسانی ارسال می‌شود که امروز بازدید داشته‌اند. شرط برای هر دستگاه این Alias جداگانه بررسی می‌شود و فقط دستگاه‌های واجد شرط پیام می‌گیرند؛ با smart_targeting هم بهترین دستگاه از میان همین دستگاه‌ها انتخاب می‌شود. با only_last_device ابتدا آخرین دستگاه کاربر انتخاب و شرط روی همان دستگاه بررسی می‌شود و اگر شرط را نداشته باشد، پیام به دستگاه قدیمی‌تری فرستاده نمی‌شود. اگر هیچ دستگاهی ارسال نشود، خطای 422 با کد LAST_VISIT_CONDITION_NOT_MET برمی‌گردد.
{
"api_public_key": "YOUR_PUBLIC_KEY",
"api_private_key": "YOUR_PRIVATE_KEY",
"alias": "customer-42",
"title": "پیشنهاد امروز",
"body": "ویژه کاربرانی که امروز به ما سر زده‌اند",
"last_visit": { "operator": ">=", "date": "today" },
"send_time": "current"
}خطاها و کدهای پاسخ
خطاهای عمومی مانند INVALID_API_KEYS، VALIDATION_ERROR و INSUFFICIENT_BALANCE در همه وب‌سرویس‌های ارسال مشترک‌اند. اگر ارسال ممکن نباشد، درخواست با یکی از کدهای ALIAS_NOT_FOUND، NO_ACTIVE_PUSH_SUBSCRIPTION، NO_MATCHING_DEVICE یا FREQUENCY_CAP_REACHED رد می‌شود. اگر only_last_device را بدون smart_targeting بفرستید و ثبت آخرین بازدید سرویس خاموش باشد، خطای LAST_VISIT_TRACKING_DISABLED برمی‌گردد. اگر شرط اختیاری last_visit را بفرستید، LAST_VISIT_TRACKING_DISABLED و LAST_VISIT_CONDITION_NOT_MET هم ممکن است برگردند. معنی هر کد و اینکه چه زمانی باید توکن یا شناسه را حذف کنید در صفحه خطاها آمده است.
send_time برابر delay)، time باید تاریخ میلادی با قالب Y-m-d H:i و ساعت تهران (Asia/Tehran) باشد. قالب نامعتبر با VALIDATION_ERROR و زمان گذشته یا همین لحظه با خطای 422 و کد INVALID_SEND_TIME رد می‌شود؛ در هر دو حالت پیامی ساخته نمی‌شود و هزینه‌ای کسر نمی‌شود.