ارسال پوش نوتیفیکیشن با PHP و Laravel؛ API پوشفا و صف ارسال

برای ارسال پوش نوتیفیکیشن از PHP یا Laravel، درخواست را از سرور به API پوشفا بفرستید. کلید خصوصی در تنظیمات سرور می‌ماند؛ مرورگر یا اپ فقط بخش عمومی اتصال را دارد. پیش از ارسال نیز باید شناسه مشترک معتبر را از جریان عضویت همان سرویس دریافت کرده باشید.

در این مقاله:

• اطلاعات لازم برای ارسال تکی
• کلیدها را در پیکربندی نگه دارید
• نمونه درخواست با HTTP Client لاراول
• ارسال را از درخواست کاربر جدا کنید
• گزارش تحویل و وب‌هوک
• چک‌لیست پیش از استفاده واقعی

اطلاعات لازم برای ارسال تکی

مسیر ارسال تکی POST https://pushfa.com/api/webservices/send-single-message است. api_public_key و api_private_key سرویس، گیرنده، عنوان، متن و نوع زمان ارسال را مشخص کنید. در قرارداد فعلی، subscriber_id یک UUID است؛ این شناسه با شناسه کاربر سایت شما یکی نیست.

فیلد قدیمی fcm_token نیز مسیر سازگار گیرنده دارد، اما آن را هم‌زمان با subscriber_id نفرستید. برای ارسال‌های جدید، از شناسه مشترک ارائه‌شده توسط اتصال سرویس استفاده کنید. نوع زمان ارسال فوری current است؛ مقدار حدسی immediate قرارداد این API نیست.

کلیدها را در پیکربندی نگه دارید

نمونه زیر، پیکربندی پیشنهادی در برنامه Laravel شماست. این تنظیم را خودتان در config/services.php اضافه کنید و مقادیر را از محیط استقرار بگیرید؛ کلید واقعی را در مخزن، لاگ یا پاسخ عمومی ذخیره نکنید.

'pushfa' => [
    'public_key' => env('PUSHFA_PUBLIC_KEY'),
    'private_key' => env('PUSHFA_PRIVATE_KEY'),
],

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

نمونه درخواست با HTTP Client لاراول

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->connectTimeout(10)
    ->timeout(30)
    ->post('https://pushfa.com/api/webservices/send-single-message', [
        'api_public_key' => config('services.pushfa.public_key'),
        'api_private_key' => config('services.pushfa.private_key'),
        'subscriber_id' => $subscriberId,
        'title' => 'وضعیت سفارش تغییر کرد',
        'body' => 'جزئیات تازه سفارش را در حساب خود ببینید.',
        'link_url' => $orderUrl,
        'sendTime' => 'current',
    ]);

$response->throw();
$result = $response->json();

$subscriberId و $orderUrl در این مثال باید قبلاً از داده معتبر برنامه تهیه شوند. تعلق مقصد و گیرنده به کاربر مجاز را بررسی کنید. throw() خطای HTTP را آشکار می‌کند؛ وضعیت کاربردی پاسخ JSON را نیز مطابق مستندات همان API بررسی کنید. پاسخ HTTP موفق را به معنی نمایش اعلان روی دستگاه نگیرید.

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

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

تلاش مجدد باید محدود و متناسب با علت خطا باشد. داده نامعتبر با تکرار همان درخواست درست نمی‌شود. قطع ارتباط نیز همیشه ثابت نمی‌کند درخواست قبلی پذیرفته نشده است. شناسه رویداد و سابقه تلاش‌های ارسال را در برنامه نگه دارید و امکان ارسال تکراری را در طراحی ببینید؛ فیلد idempotency فرضی به API اضافه نکنید.

گزارش تحویل و وب‌هوک

اگر گزارش نیاز دارید، گزینه‌های معتبر گزارش و webhook_url را مطابق تنظیمات ارسال استفاده کنید. گیرنده وب‌هوک در برنامه شما باید تکرار و تأخیر گزارش را مدیریت کند. راهنمای بومرنگ درباره واکنش به گزارش توضیح می‌دهد. نبود تأیید نمایش، به‌تنهایی اجازه ارسال فوری چندباره یا پیامک خودکار نیست.

برای بررسی نتیجه، شناسه پیام و وضعیت‌های ثبت‌شده را نگه دارید؛ کلید خصوصی و تمام payload حساس را لاگ نکنید. شاخص‌های عملکرد پوش کمک می‌کند پذیرش درخواست، نمایش، کلیک و تبدیل را از هم جدا کنید.

چک‌لیست پیش از استفاده واقعی

• کلیدها فقط از پیکربندی امن سرور خوانده می‌شوند.
• گیرنده متعلق به سرویس و کاربر مجاز است.
• عنوان، متن و زمان با قرارداد API سازگارند.
• لینک مقصد امن است و اطلاعات خصوصی در URL ندارد.
• timeout، محدودیت تلاش مجدد و جلوگیری از ارسال تکراری تعریف شده‌اند.
• برای پیام ضروری، سابقه داخل حساب کاربر هم وجود دارد.