Skip to main content
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 لجدولة التسليم لوقت لاحق بدلاً من الإرسال الفوري. اتركه فارغاً (أو مرّر وقتاً في الماضي) للإرسال فوراً. يمكن تعديل الإشعار المجدوَل أو إلغاؤه قبل إرساله — راجع تحديث إشعار وإلغاء إشعار مجدوَل.
لا تعرِض مفتاحك الخاص أبداً في كود جهة العميل (client-side) أو في مستودعات عامة. أرسل طلبات الـ API من باك إند موثوق فقط.

الاستجابة (Response)

201 Created
احتفظ بـ notificationId، فهو ما تمرّره إلى نقاط النهاية الأخرى الخاصة بالإشعارات (التحديث، إلغاء الإرسال، الإلغاء، وحالة التسليم). عند الإرسال إلى externalUserIds، تبيّن الاستجابة أيضاً من وصل إليه الإشعار:
201 Created
number
عدد المعرّفات المطلوبة التي يرتبط بها جهاز واحد على الأقل.
number
عدد الأجهزة التي أُرسل إليها الإشعار، عبر كل المنصات.
string[]
المعرّفات المطلوبة التي لا يرتبط بها أي جهاز. لم يُرسَل لها شيء.
الجهاز الموجود على منصة لم تُعدّ مفاتيح الإشعارات الخاصة بها بعد لا يمنع بقية الأجهزة: يُسجَّل له تسليم فاشل بالرمز PLATFORM_NOT_CONFIGURED، ويظهر في حالة التسليم.

الأخطاء

أي فشل آخر يتبع الشكل والرموز الموثّقة في رموز الأخطاء والنجاح.