الإشعارات
الإشعارات
أرسل إشعارات إلى أجهزة محددة، أو إلى مستخدميك على كل أجهزتهم، أو إلى موضوع عبر REST API الخاص بـ Lerix.
POST
الإشعارات
أرسل إشعاراً إلى واحد من ثلاثة أهداف:
احتفظ بـ
الجهاز الموجود على منصة لم تُعدّ مفاتيح الإشعارات الخاصة بها بعد لا يمنع
بقية الأجهزة: يُسجَّل له تسليم فاشل بالرمز
deviceTokens: أجهزة مسجّلة محددة.externalUserIds: معرّفات المستخدمين الخاصة بك. يسلّم Lerix الإشعار إلى كل جهاز سجّل فيه كل مستخدم دخوله (iOS وAndroid والويب وmacOS) في طلب واحد. تربط تطبيقاتك الجهاز بالمستخدم عبرsetUser؛ راجع تعريف المستخدمين.topic(معsendByTopic: true): كل جهاز مشترك في موضوع.
externalUserIds و
deviceTokens أو sendByTopic، ويُرفَض هذا الطلب بالرمز NOTIFICATION_TARGET_INVALID.
راجع مقدمة الـ API لإعداد الرابط الأساسي ومفتاحك الخاص قبل إرسال الطلبات.
المعاملات (Parameters)
string
مطلوب
معرّف مشروعك من إعدادات المشروع في لوحة التحكم.
string
مطلوب
عنوان الإشعار الذي يظهر للمستخدم.
string
مطلوب
نص رسالة الإشعار.
string[]
رمز جهاز واحد أو أكثر لتسليم الإشعار إليه. أحد الأهداف الثلاثة: لا تجمعه
مع
externalUserIds أو sendByTopic.string[]
معرّفات المستخدمين الخاصة بك، وهي نفس القيم التي تمرّرها تطبيقاتك إلى
setUser بعد تسجيل الدخول. يجد Lerix كل جهاز مرتبط حالياً بكل معرّف، عبر
كل المنصات في هذا المشروع، ويسلّم الإشعار إليها جميعاً. حتى 1000 معرّف في
الطلب الواحد، وطول كل معرّف من 1 إلى 255 حرفاً. أحد الأهداف الثلاثة: لا
تجمعه مع deviceTokens أو sendByTopic.المعرّف الذي لا يرتبط به أي جهاز لا يُعدّ خطأ (ربما لم يثبّت المستخدم
التطبيق بعد)، ويظهر في unknownUserIds في الاستجابة. عند جدولة الإشعار
عبر sentAt، يُعاد البحث عن الأجهزة وقت الإرسال، فيصل الإشعار أيضاً إلى
جهاز سجّل الدخول بعد الجدولة.boolean
افتراضي:"false"
اضبطه على
true للتسليم لكل جهاز مشترك في topic. أحد الأهداف الثلاثة:
لا تجمعه مع deviceTokens أو externalUserIds. تشترك
الأجهزة في موضوع من تطبيقك عبر الـ SDK؛ يُنشأ الموضوع تلقائياً أول مرة يشترك
فيها جهاز، أو يمكنك إنشاء واحد يدوياً من تبويب المواضيع في لوحة
التحكم.string
مفتاح الموضوع الذي يتم البث إليه. مطلوب عندما يكون
sendByTopic بقيمة
true، ويُتجاهَل خلاف ذلك.string
اسم صوت إشعار مخصّص. يجب أن يكون الملف نفسه مُرفقاً بالفعل داخل مشروع
تطبيقك — يمرّر Lerix اسم الملف فقط إلى APNs/FCM، ولا يستضيف أو يرفع
ملفات الصوت. اتركه فارغاً لاستخدام صوت الإشعار الافتراضي للجهاز.iOS: اسم ملف الصوت مع امتداده (مثال:
sound.mp3؛ مدعوم أيضاً
.caf/.wav).Android: اسم المورد (resource) بدون امتداد، بحيث يطابق ملفاً تحت
res/raw/ (مثال: sound لملف عند res/raw/sound.mp3).- الصيغ المدعومة:
.wav،.mp3،.ogg. - اجعل اسم الملف بأحرف صغيرة (lowercase) — بعض الأدوات/الأجهزة تتجاهل الأحرف الكبيرة في أسماء الموارد.
- اجعل حجم الملف صغيراً وأقل من ~30 ثانية؛ قد لا تعمل الملفات الكبيرة على بعض الأجهزة.
- إذا لم يُعثر على الملف المحدّد، يعود الإشعار إلى صوت الجهاز الافتراضي بدلاً من الفشل.
- يُثبَّت الصوت المحدّد أول مرة يُستخدم فيها على الجهاز — يُثبّت Android
صوت قناة الإشعارات (notification channel) عند إنشائها ولا يسمح بتغييره
لاحقاً، لذا فإن التبديل إلى قيمة
soundمختلفة لاحقاً يُنشئ قناة جديدة بدلاً من تحديث القناة القديمة.
object
بيانات مخصّصة حرّة لإرفاقها بالإشعار. أي كائن JSON؛ اتركه فارغاً لعدم إرفاق
أي بيانات وصفية. تصل إلى الجهاز جنباً إلى جنب مع
title/body، وتُقرأ من
الـ SDK كـ payload.metadata في
setOnNotificationReceived/setOnNotificationTapped.string
القيمة الافتراضية هي المشروع الموجود في الرابط (
/v1/:project-id/...)؛ مطلوب فقط للتكاملات القديمة.string
بديل قديم لترويسة
lerix-key، ولا يزال مقبولاً.string
افتراضي:"API"
المصدر الذي أُرسل منه الإشعار.
string
طابع زمني بصيغة ISO 8601 لجدولة التسليم لوقت لاحق بدلاً من الإرسال الفوري.
اتركه فارغاً (أو مرّر وقتاً في الماضي) للإرسال فوراً. يمكن تعديل الإشعار
المجدوَل أو إلغاؤه قبل إرساله — راجع تحديث إشعار وإلغاء إشعار مجدوَل.
الاستجابة (Response)
201 Created
notificationId، فهو ما تمرّره إلى نقاط النهاية الأخرى الخاصة
بالإشعارات (التحديث، إلغاء الإرسال، الإلغاء، وحالة التسليم).
عند الإرسال إلى externalUserIds، تبيّن الاستجابة أيضاً من وصل إليه الإشعار:
201 Created
number
عدد المعرّفات المطلوبة التي يرتبط بها جهاز واحد على الأقل.
number
عدد الأجهزة التي أُرسل إليها الإشعار، عبر كل المنصات.
string[]
المعرّفات المطلوبة التي لا يرتبط بها أي جهاز. لم يُرسَل لها شيء.
PLATFORM_NOT_CONFIGURED، ويظهر في
حالة التسليم.
الأخطاء
أي فشل آخر يتبع الشكل والرموز الموثّقة في رموز الأخطاء والنجاح.