Flutter — الإشعارات

​

مقدمة

​

إعداد Android

1. أنشئ أو افتح تطبيقك في Firebase Console.
2. نزّل ملف google-services.json لتطبيق Android الخاص بك.
3. ارفع الملف إلى لوحة تحكم Lerix.

​

إعداد iOS

​

إعداد مصادقة APNs

1. في بوابة Apple Developer، اذهب إلى Certificates, Identifiers & Profiles → Keys.
2. أنشئ مفتاحاً جديداً مع تفعيل Apple Push Notifications service (APNs).
3. نزّل مفتاح المصادقة .p8 ولاحظ Key ID. يمكنك تنزيل المفتاح مرة واحدة فقط.
4. ارفع ملف .p8 إلى لوحة تحكم Lerix.

​

إعداد AppDelegate

import lerix

override func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceData: Data
) {
  lerix_didRegisterForRemoteNotifications(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceData)
}

override func application(
  _ application: UIApplication,
  didFailToRegisterForRemoteNotificationsWithError error: Error
) {
  lerix_didFailToRegisterForRemoteNotifications(application, didFailToRegisterForRemoteNotificationsWithError: error)
}

​

إعداد macOS

1. Signing & Capabilities: وقّع التطبيق بحساب فريقك في Apple وأضف Push Notifications. التطبيق الموقّع للتشغيل المحلي فقط لا يستقبل الإشعارات.
2. App Sandbox: فعّل Outgoing Connections (Client) حتى يتمكن الـ SDK من الاتصال بـ Lerix.
3. AppDelegate: مرّر استدعاءات APNs في macos/Runner/AppDelegate.swift:

import lerix_flutter

override func application(_ application: NSApplication,
                          didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  lerix_didRegisterForRemoteNotifications(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

override func application(_ application: NSApplication,
                          didFailToRegisterForRemoteNotificationsWithError error: Error) {
  lerix_didFailToRegisterForRemoteNotifications(application, didFailToRegisterForRemoteNotificationsWithError: error)
}

override func application(_ application: NSApplication,
                          didReceiveRemoteNotification userInfo: [String: Any]) {
  lerix_didReceiveRemoteNotification(application, didReceiveRemoteNotification: userInfo)
}

​

إعداد الويب

1. انسخ عامل الخدمة (service worker). لا يمكن لحزمة Flutter إضافة ملف إلى مجلد web/ في تطبيقك تلقائياً — انسخ ملف web_sw/lerix-sw.js من حزمة lerix_flutter إلى web/lerix-sw.js في تطبيقك، بحيث يُقدَّم من جذر موقعك (مثال: https://yoursite.com/lerix-sw.js).
2. أنشئ مفتاح Web Push من لوحة التحكم: الإشعارات ← الإعدادات ← Web Push ← إنشاء المفاتيح. نقرة واحدة — ينشئ Lerix زوج مفاتيح VAPID ويخزّنه لك؛ لا حاجة لنسخ أي شيء في كودك.

​

إعداد Huawei

​

إعدادات لوحة التحكم

​

كود Flutter

await Lerix.notifications.init();

final granted = await Lerix.notifications.requestPermissions();

Lerix.notifications.setOnNotificationReceived((payload) {
  // يُستدعى أثناء فتح التطبيق (foreground) — اعرض إشعاراً داخل التطبيق مثلاً.
  debugPrint("Notification received: ${payload.title} — ${payload.body}");
});

Lerix.notifications.setOnNotificationTapped((payload) {
  // يُستدعى عند ضغط المستخدم على الإشعار — بما في ذلك إشعار فتح التطبيق
  // من حالة إغلاق كامل (راجع الملاحظة أدناه).
  debugPrint("Notification tapped: ${payload.metadata}");
});

final deviceId = await Lerix.notifications.getDeviceId();
final status = await Lerix.notifications.checkPermissionStatus();
// "authorized", "denied", "notDetermined"

​

البيانات (Payload) المُستلَمة مع الإشعار

class LerixNotificationPayload {
  String? notificationId; // معرّف هذا الإشعار في Lerix — نفس المعرّف المستخدم لحالة التسليم وإلغاء الإرسال
  String? title;
  String? body;
  Map<String, dynamic> metadata; // أي بيانات مررتها كـ metadata عند الإرسال
  String? imageUrl; // أي قيمة مررتها كـ imageUrl عند الإرسال، إن وُجدت
}

Lerix.notifications.setOnNotificationTapped((payload) {
  final screen = payload.metadata['screen'];
  final orderId = payload.metadata['orderId'];
  // انتقل بناءً على payload.metadata، إلخ.
});

​

معرّفات الجهاز: getDeviceId() مقابل getDeviceToken()

final deviceId = await Lerix.notifications.getDeviceId();
print('Send test notifications to: $deviceId');

final token = await Lerix.notifications.getDeviceToken();
print('Raw platform token: $token');

​

إرسال صوت مخصّص

• يجب أن يكون الملف موجوداً بالفعل داخل مشروع تطبيقك — يمرّر Lerix اسم الملف فقط، ولا يستضيف أو يرفع ملفات الصوت.
• iOS: مرّر اسم الملف مع امتداده، مثل sound.mp3 (مدعوم أيضاً .wav/.caf).
• Android: مرّر اسم الملف بدون امتداد، بحيث يطابق ملفاً تحت res/raw/ (مثال: sound لملف عند res/raw/sound.mp3). الصيغ المدعومة: .wav، .mp3، .ogg.
• الويب: غير مدعوم — لا توفّر واجهة Web Notifications طريقة موحّدة عبر المتصفحات لتحديد صوت مخصّص، لذا يُتجاهَل هذا المعامل بالنسبة لمستلمي الويب.

​

إرسال بيانات وصفية (Metadata)

{
  "title": "New message from John",
  "body": "Hey, are you free later?",
  "metadata": { "chatId": "456", "screen": "chat" }
}

Lerix.notifications.setOnNotificationTapped((payload) {
  final chatId = payload.metadata['chatId'];
  // انتقل إلى شاشة المحادثة، إلخ.
});

​

إرسال صورة

• Android: يعمل تلقائياً، بدون إعداد إضافي. تُعرَض الصورة كإشعار من نوع BigPictureStyle.
• الويب: يعمل تلقائياً أيضاً، بدون إعداد إضافي — يعرضها عامل الخدمة (service worker) مباشرة كأيقونة/صورة الإشعار.
• iOS: يتطلّب أن يملك تطبيقك Notification Service Extension — لا تملك APNs حقل “صورة” أصلياً، لذا يحتاج النظام إلى امتداد صغير لتنزيل الصورة وإرفاقها قبل عرض الإشعار. هذه خطوة إعداد لمرة واحدة لكل تطبيق:
  1. في Xcode: File → New → Target… → Notification Service Extension. سمِّه (مثلاً NotificationServiceExtension).
  2. استبدل ملف NotificationService.swift المُولَّد بالملف الموجود في حزمة lerix_flutter عند ios/NotificationServiceExtension/NotificationService.swift.
  3. ابنِ التطبيق وشغّله — لا حاجة لأي إعداد آخر. يضبط الباك إند تلقائياً علم mutable-content الخاص بـ APNs كلما حمل الإشعار قيمة imageUrl، وهذا ما يُشغّل الامتداد.

​

الفروقات بين المنصات على الويب

• تفعل requestPermissions() أكثر على الويب. على الجوال، يحدث تسجيل الدفع (push) تلقائياً داخل init()، وتُعنى requestPermissions() فقط بإذن الإشعارات المرئية. لا يمكن للمتصفح الاشتراك في Push قبل منح الإذن، لذا على الويب، تقوم requestPermissions() أيضاً بتسجيل اشتراك الدفع الخاص بعامل الخدمة لدى الباك إند بمجرد سماح المستخدم — نفس استدعاء الدالة، لكنه يؤدي مهمّتين.
• تُرجع getSenderId() القيمة null على الويب — فهي مفهوم خاص بـ Android/FCM فقط (يستخدم Web Push بروتوكول VAPID، وليس Firebase).
• تُرجع getDeviceToken() أيضاً القيمة null على الويب — فكائن PushSubscription الخاص بالمتصفح ليس رمزاً واحداً معتماً بنفس طريقة APNs/FCM، فلا يوجد ما يستحق إرجاعه. استخدم getDeviceId() على كل منصة بدلاً منه.
• الصوت المخصّص غير مدعوم — راجع إرسال صوت مخصّص أعلاه.
• دعم المتصفحات: Chrome وFirefox وEdge بشكل كامل؛ يتطلّب Safari إصدار macOS 13+‎ أو iOS 16.4+‎ — الإصدارات الأقدم من Safari لا تدعم Web Push القياسي إطلاقاً.

​

استهدف مستخدماً على كل أجهزته

await Lerix.setUser('user_123'); // after login
await Lerix.clearUser();         // on logout

​

المواضيع (Topics)

final subscribed = await Lerix.notifications.subscribeToTopic('promotions');

await Lerix.notifications.unsubscribeFromTopic('promotions');