Flutter — الإشعارات

​

مقدمة

​

إعداد Android

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

​

إعداد iOS

​

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

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

​

إعداد AppDelegate

import atelerix

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

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

​

إعداد الويب

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

​

إعداد Huawei

​

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

​

كود Flutter

await Atelerix.notifications.init();

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

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

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

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

​

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

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

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

​

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

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

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

​

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

• يجب أن يكون الملف موجوداً بالفعل داخل مشروع تطبيقك — يمرّر Atelerix اسم الملف فقط، ولا يستضيف أو يرفع ملفات الصوت.
• 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" }
}

Atelerix.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 المُولَّد بالملف الموجود في حزمة atelerix عند 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 القياسي إطلاقاً.

​

المواضيع (Topics)

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

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