إشعارات .NET MAUI Firebase دليل (2026)

لنكن صريحين — إشعارات الدفع (Push Notifications) هي من أول الأشياء التي يسألك عنها العميل أو مدير المنتج. "هل التطبيق يرسل إشعارات؟" سؤال تسمعه في كل مشروع تقريباً. وصراحةً، المستخدم اليوم يتوقع أن يصله تنبيه بالعرض الجديد أو الرسالة الواردة حتى لو كان التطبيق مغلقاً تماماً.

المشكلة؟ إعداد إشعارات الدفع في .NET MAUI ليس بالبساطة التي تتمنّاها. لديك Firebase Cloud Messaging لـ Android، و Apple Push Notification Service لـ iOS، وكل منصة لها عالمها الخاص من الإعدادات والمتطلبات. في هذا الدليل، سنمشي معاً خطوة بخطوة — من إنشاء مشروع Firebase إلى استقبال أول إشعار على جهازك الفعلي.

أعدّك أنك بنهاية هذا المقال ستكون قادراً على تشغيل الإشعارات على Android و iOS من مشروع .NET MAUI واحد.

ما ستتعلمه في هذا الدليل

إنشاء وتهيئة مشروع Firebase من الصفر
إعداد إشعارات الدفع لـ Android و iOS في .NET MAUI 10
التعامل مع الإشعارات في الواجهة الأمامية والخلفية
إدارة رموز التسجيل (Registration Tokens) بالطريقة الصحيحة
اختبار الإشعارات وحل المشكلات الشائعة
أفضل الممارسات عند النشر للإنتاج

المتطلبات الأساسية

قبل أن نبدأ، تأكد من توفر ما يلي:

.NET 10 SDK مثبت على جهازك
Visual Studio 2022 أو أحدث (أو VS Code مع إضافة .NET MAUI)
حساب Google للوصول إلى Firebase Console
حساب Apple Developer — مطلوب لإشعارات iOS ولا مفر منه
جهاز Mac للبناء والاختبار على iOS (أو Mac سحابي إذا كنت على Windows)
جهاز فعلي للاختبار — وهذه نقطة مهمة جداً لأن إشعارات الدفع لا تعمل بشكل موثوق على المحاكيات

الخطوة 1: إنشاء مشروع Firebase

أول شيء نحتاجه هو مشروع على Firebase. إذا عندك مشروع جاهز، تقدر تتخطى هذه الخطوة.

اذهب إلى Firebase Console على console.firebase.google.com
اضغط على "Add project"
أدخل اسم المشروع واختر الإعدادات المناسبة
فعّل أو عطّل Google Analytics حسب حاجتك (شخصياً أفضّل تفعيله من البداية)
اضغط "Create project" وانتظر ثوانٍ حتى يكتمل الإنشاء

تسجيل تطبيق Android

في لوحة التحكم، اضغط على أيقونة Android
أدخل اسم الحزمة (Package Name) — وهنا انتبه: يجب أن يطابق تماماً قيمة ApplicationId في ملف .csproj
قم بتنزيل ملف google-services.json
ضع الملف في مسار Platforms/Android/ في مشروعك

تسجيل تطبيق iOS

اضغط على "Add app" ثم اختر iOS
أدخل Bundle ID — نفس الكلام، يجب أن يطابق ApplicationId في مشروعك
قم بتنزيل ملف GoogleService-Info.plist
ضع الملف في مسار Platforms/iOS/

الخطوة 2: تثبيت حزمة NuGet

سنستخدم مكتبة Plugin.FirebasePushNotifications (الإصدار 3.2.11 أو أحدث). هذه المكتبة هي الأشهر والأكثر استقراراً لإشعارات Firebase في .NET MAUI، وقد استخدمتها في أكثر من مشروع بدون مشاكل تُذكر.

dotnet add package Plugin.FirebasePushNotifications

أو أضفها يدوياً في ملف .csproj:

<ItemGroup>
  <PackageReference Include="Plugin.FirebasePushNotifications" Version="3.2.11" />
</ItemGroup>

الخطوة 3: تهيئة ملف المشروع (.csproj)

هذه الخطوة يغفل عنها كثير من المطورين وتسبب إحباطاً كبيراً. نحتاج إلى تعديل ملف .csproj لتضمين ملفات Firebase لكل منصة:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0-android;net10.0-ios</TargetFrameworks>
    <OutputType Condition="'$(TargetFramework)' != 'net10.0'">Exe</OutputType>
    <ApplicationId>com.yourcompany.yourapp</ApplicationId>
    <ApplicationDisplayVersion>1.0</ApplicationDisplayVersion>
    <ApplicationVersion>1</ApplicationVersion>
    <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">26.0</SupportedOSPlatformVersion>
    <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">15.0</SupportedOSPlatformVersion>
  </PropertyGroup>

  <!-- ملف إعدادات Firebase لـ Android -->
  <ItemGroup Condition="$(TargetFramework.Contains('-android'))">
    <GoogleServicesJson Include="Platforms\Android\google-services.json" />
  </ItemGroup>

  <!-- ملف إعدادات Firebase لـ iOS -->
  <ItemGroup Condition="$(TargetFramework.Contains('-ios'))">
    <BundleResource Include="Platforms\iOS\GoogleService-Info.plist"
                    Link="GoogleService-Info.plist" />
  </ItemGroup>
</Project>

لاحظ أننا عيّنا SupportedOSPlatformVersion لـ Android على 26.0 لأن قنوات الإشعارات (Notification Channels) أصبحت إلزامية من Android 8.0 فصاعداً. هذا شيء لا يمكن تجاوزه.

الخطوة 4: تهيئة MauiProgram.cs

الآن نسجّل خدمة إشعارات Firebase. الجميل في الموضوع أن التهيئة سطر واحد فعلياً:

using Plugin.FirebasePushNotifications;

namespace YourApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiApp<App>()
            .UseFirebasePushNotifications()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        return builder.Build();
    }
}

دالة UseFirebasePushNotifications() هي Extension Method تقوم بتسجيل كل الخدمات المطلوبة تلقائياً. لا تحتاج لفعل أي شيء إضافي هنا.

الخطوة 5: إعداد Android

تهيئة MainActivity.cs

هنا الجزء الذي يحتاج انتباهاً. يجب تعديل MainActivity لدعم إشعارات الدفع، والنقطة الأهم هي تعيين LaunchMode إلى SingleTop. لماذا؟ لأنك لا تريد أن يُنشئ النظام Activity جديد كل مرة يضغط فيها المستخدم على إشعار:

using Android.App;
using Android.Content;
using Android.Content.PM;
using Android.OS;
using Plugin.FirebasePushNotifications.Platforms;

namespace YourApp;

[Activity(
    Theme = "@style/Maui.SplashTheme",
    MainLauncher = true,
    LaunchMode = LaunchMode.SingleTop,
    ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation |
                           ConfigChanges.UiMode | ConfigChanges.ScreenLayout |
                           ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        HandleIntent(Intent);
        CreateNotificationChannelIfNeeded();
    }

    protected override void OnNewIntent(Intent? intent)
    {
        base.OnNewIntent(intent);
        HandleIntent(intent);
    }

    private static void HandleIntent(Intent? intent)
    {
        FirebasePushNotificationManager.OnNewIntent(intent);
    }

    private void CreateNotificationChannelIfNeeded()
    {
        if (Build.VERSION.SdkInt >= BuildVersionCodes.O)
        {
            var channelId = "default_channel";
            var channelName = "Default Notifications";
            var channelDescription = "إشعارات التطبيق الافتراضية";
            var importance = NotificationImportance.High;

            var channel = new NotificationChannel(channelId, channelName, importance)
            {
                Description = channelDescription
            };

            var notificationManager = (NotificationManager?)GetSystemService(NotificationService);
            notificationManager?.CreateNotificationChannel(channel);
        }
    }
}

صلاحيات Android

أضف الصلاحيات التالية في ملف AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

ملاحظة مهمة: بدءاً من Android 13 (API 33)، صلاحية POST_NOTIFICATIONS يجب طلبها من المستخدم وقت التشغيل — لم يعد يكفي إضافتها في الـ Manifest فقط. سنتعامل مع هذا في الكود لاحقاً.

الخطوة 6: إعداد iOS

سأكون صريحاً معك — إعداد iOS أكثر تعقيداً بمراحل. ليس لأن الكود صعب، بل لأن Apple تحب الإجراءات البيروقراطية (شهادات، مفاتيح، Provisioning Profiles... تعرف القصة).

إعداد Apple Developer Portal

سجّل الدخول إلى Apple Developer Portal
اذهب إلى Certificates, Identifiers & Profiles
أنشئ App ID جديد (أو عدّل الموجود) وفعّل خاصية Push Notifications
أنشئ APNs Authentication Key من قسم Keys:
- اضغط على "+" لإنشاء مفتاح جديد
- فعّل Apple Push Notifications service (APNs)
- قم بتنزيل المفتاح واحفظ Key ID — ستحتاجه لاحقاً ولن تستطيع تنزيله مرة أخرى
أنشئ Provisioning Profile جديد يتضمن Push Notifications

ربط مفتاح APNs بـ Firebase

في Firebase Console، اذهب إلى Project Settings → Cloud Messaging
في قسم Apple app configuration، اضغط على "Upload"
ارفع ملف المفتاح (بامتداد .p8)
أدخل Key ID و Team ID

إضافة Entitlements.plist

أنشئ ملف Entitlements.plist في مجلد Platforms/iOS/:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>aps-environment</key>
  <string>development</string>
</dict>
</plist>

غيّر القيمة إلى production عند النشر على App Store. هذا من الأخطاء الشائعة — كثير من المطورين ينسون تغييرها ثم يتساءلون لماذا لا تعمل الإشعارات في الإنتاج!

تهيئة AppDelegate.cs لـ iOS

using Foundation;
using UIKit;
using UserNotifications;
using Plugin.FirebasePushNotifications.Platforms;

namespace YourApp;

[Register("AppDelegate")]
public class AppDelegate : MauiUIApplicationDelegate
{
    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        var result = base.FinishedLaunching(application, launchOptions);

        // طلب إذن الإشعارات من المستخدم
        UNUserNotificationCenter.Current.RequestAuthorization(
            UNAuthorizationOptions.Alert | UNAuthorizationOptions.Badge | UNAuthorizationOptions.Sound,
            (granted, error) =>
            {
                if (granted)
                {
                    InvokeOnMainThread(() =>
                    {
                        UIApplication.SharedApplication.RegisterForRemoteNotifications();
                    });
                }
            });

        return result;
    }
}

الخطوة 7: التعامل مع الإشعارات في الكود المشترك

هذا هو الجزء الممتع فعلاً — الكود المشترك الذي يعمل على المنصتين. سننشئ خدمة إشعارات نظيفة باستخدام Dependency Injection:

إنشاء خدمة الإشعارات

using Plugin.FirebasePushNotifications;

namespace YourApp.Services;

public class NotificationService
{
    private readonly IFirebasePushNotification _pushNotification;

    public NotificationService(IFirebasePushNotification pushNotification)
    {
        _pushNotification = pushNotification;
    }

    public async Task InitializeAsync()
    {
        // التسجيل لاستقبال الإشعارات
        await _pushNotification.RegisterForPushNotificationsAsync();

        // الاستماع لتحديث الرمز
        _pushNotification.TokenRefreshed += OnTokenRefreshed;

        // الاستماع لاستقبال إشعار جديد
        _pushNotification.NotificationReceived += OnNotificationReceived;

        // الاستماع لضغط المستخدم على إشعار
        _pushNotification.NotificationOpened += OnNotificationOpened;
    }

    private void OnTokenRefreshed(object? sender, FirebasePushNotificationTokenEventArgs e)
    {
        var token = e.Token;
        Console.WriteLine($"FCM Token: {token}");

        // هنا يجب إرسال الرمز إلى الخادم الخلفي
        // await _apiService.UpdateDeviceTokenAsync(token);
    }

    private void OnNotificationReceived(object? sender,
        FirebasePushNotificationDataEventArgs e)
    {
        // تم استقبال إشعار والتطبيق مفتوح
        if (e.Data.TryGetValue("title", out var title) &&
            e.Data.TryGetValue("body", out var body))
        {
            Console.WriteLine($"إشعار جديد: {title} - {body}");
        }
    }

    private void OnNotificationOpened(object? sender,
        FirebasePushNotificationResponseEventArgs e)
    {
        // المستخدم ضغط على الإشعار
        if (e.Data.TryGetValue("action", out var action))
        {
            HandleNotificationAction(action?.ToString());
        }
    }

    private void HandleNotificationAction(string? action)
    {
        switch (action)
        {
            case "open_order":
                Shell.Current.GoToAsync("//OrderDetailsPage");
                break;
            case "open_chat":
                Shell.Current.GoToAsync("//ChatPage");
                break;
            default:
                Shell.Current.GoToAsync("//MainPage");
                break;
        }
    }

    public async Task SubscribeToTopicAsync(string topic)
    {
        await _pushNotification.SubscribeAsync(topic);
    }

    public async Task UnsubscribeFromTopicAsync(string topic)
    {
        await _pushNotification.UnsubscribeAsync(topic);
    }
}

تسجيل الخدمة في MauiProgram.cs

builder.Services.AddSingleton<NotificationService>();

تهيئة الخدمة عند بدء التطبيق

// في App.xaml.cs أو في الصفحة الرئيسية
public partial class App : Application
{
    private readonly NotificationService _notificationService;

    public App(NotificationService notificationService)
    {
        InitializeComponent();
        _notificationService = notificationService;
    }

    protected override async void OnStart()
    {
        base.OnStart();
        await _notificationService.InitializeAsync();
    }
}

الخطوة 8: إرسال إشعار تجريبي

الآن اللحظة التي ننتظرها — لنتأكد أن كل شيء يعمل!

اذهب إلى Firebase Console → Engage → Messaging
اضغط على "Create your first campaign" ثم اختر "Firebase Notification messages"
أدخل عنوان ونص الإشعار
اضغط "Send test message"
الصق رمز FCM الذي ظهر في مخرجات التطبيق
اضغط "Test" وانتظر ثوانٍ

إذا وصل الإشعار، فتهانينا! أنت جاهز للمرحلة التالية.

يمكنك أيضاً إرسال إشعارات برمجياً من الخادم الخلفي باستخدام Firebase Admin SDK. هذا هو السيناريو الأقرب لما ستفعله في الإنتاج:

// مثال باستخدام C# و Firebase Admin SDK
using FirebaseAdmin;
using FirebaseAdmin.Messaging;
using Google.Apis.Auth.OAuth2;

// تهيئة Firebase Admin
FirebaseApp.Create(new AppOptions
{
    Credential = GoogleCredential.FromFile("service-account-key.json")
});

// إنشاء الرسالة
var message = new Message
{
    Token = "FCM_DEVICE_TOKEN_HERE",
    Notification = new Notification
    {
        Title = "عرض خاص!",
        Body = "خصم 50% على جميع المنتجات لفترة محدودة"
    },
    Data = new Dictionary<string, string>
    {
        { "action", "open_order" },
        { "orderId", "12345" }
    },
    Android = new AndroidConfig
    {
        Priority = Priority.High,
        Notification = new AndroidNotification
        {
            ChannelId = "default_channel",
            Icon = "notification_icon",
            Color = "#4CAF50"
        }
    },
    Apns = new ApnsConfig
    {
        Aps = new Aps
        {
            Badge = 1,
            Sound = "default"
        }
    }
};

// إرسال الإشعار
var response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
Console.WriteLine($"تم الإرسال بنجاح: {response}");

الخطوة 9: إدارة رموز التسجيل (Token Management)

هذا الموضوع لا يأخذ حقه من الاهتمام عادةً، لكنه بالغ الأهمية في الإنتاج. رمز FCM قد يتغير في أي لحظة، وإذا لم يكن خادمك محدّثاً بآخر رمز، فإن الإشعارات ببساطة لن تصل.

متى يتغير الرمز؟

عند إعادة تثبيت التطبيق
عند مسح بيانات التطبيق
عند استعادة التطبيق على جهاز جديد
بشكل دوري من قبل Firebase لأسباب أمنية
عند بدء جلسة Debug جديدة — وهذا يحدث كثيراً أثناء التطوير (لا تقلق، هذا طبيعي)

نمط تخزين الرمز المقترح

public class TokenStorageService
{
    private const string TokenKey = "fcm_token";

    public async Task SaveTokenAsync(string token)
    {
        var currentToken = await GetTokenAsync();

        if (currentToken != token)
        {
            await SecureStorage.Default.SetAsync(TokenKey, token);

            // إرسال الرمز الجديد للخادم
            // await _apiService.UpdateTokenAsync(token);
        }
    }

    public async Task<string?> GetTokenAsync()
    {
        return await SecureStorage.Default.GetAsync(TokenKey);
    }

    public void RemoveToken()
    {
        SecureStorage.Default.Remove(TokenKey);
    }
}

الفكرة بسيطة: نقارن الرمز الجديد بالمخزّن، وإذا تغيّر نحدّث الخادم. هذا يمنع إرسال طلبات تحديث غير ضرورية.

حل المشكلات الشائعة

من تجربتي الشخصية في أكثر من مشروع، هذه المشكلات تتكرر دائماً. أضعها هنا حتى توفر على نفسك ساعات من البحث والتجربة.

المشكلة 1: الإشعارات لا تصل على Android

تحقق من الصلاحيات: هل طلبت إذن POST_NOTIFICATIONS على Android 13+؟ هذا السبب الأول والأكثر شيوعاً
تحقق من القناة: تأكد من إنشاء Notification Channel — بدونها لن يظهر شيء
تحقق من google-services.json: تأكد أن اسم الحزمة مطابق بالضبط
تحقق من الرمز: تأكد أن رمز FCM صحيح ومحدّث ولم تنتهِ صلاحيته

المشكلة 2: الإشعارات لا تصل على iOS

تحقق من Provisioning Profile: يجب أن يتضمن Push Notifications — هذه أكثر مشكلة تأخذ وقتاً في اكتشافها
تحقق من Entitlements.plist: تأكد من وجود aps-environment بالقيمة الصحيحة
تحقق من مفتاح APNs: تأكد أنه مرفوع بشكل صحيح في Firebase Console
استخدم جهازاً فعلياً: لا فائدة من تجربة الإشعارات على المحاكي في iOS

المشكلة 3: الإشعارات تصل لكن بدون صوت أو ظهور

ربما المستخدم أوقف إشعارات التطبيق من إعدادات الجهاز — تحقق من ذلك أولاً
على Android، تحقق من أن NotificationImportance مضبوط على High
على iOS، تأكد أنك طلبت UNAuthorizationOptions.Sound عند التسجيل

أفضل الممارسات للإنتاج

عندما تكون جاهزاً لنقل تطبيقك من التطوير إلى الإنتاج، ضع هذه النقاط في اعتبارك:

لا تُخزّن google-services.json في Git: أضفه إلى .gitignore واستخدم متغيرات البيئة أو Secrets في CI/CD pipeline
استخدم Topics بذكاء: بدلاً من إرسال إشعار لكل جهاز على حدة، اشترك المستخدمين في مواضيع وأرسل إشعاراً واحداً للموضوع
احترم المستخدم: وفّر خيارات للتحكم في أنواع الإشعارات — لا أحد يحب التطبيق الذي يزعجه بإشعارات لا يريدها
راقب معدلات التسليم: Firebase Console يوفر إحصائيات ممتازة عن نسب التسليم والفتح
تعامل مع الأخطاء بذكاء: إذا فشل التسجيل، أعد المحاولة بنمط Exponential Backoff — لا تكرر المحاولة فوراً
اختبر على أجهزة حقيقية: خاصة iOS، الفرق بين المحاكي والجهاز الفعلي كبير جداً
لا تنسَ Entitlements.plist: غيّر aps-environment من development إلى production قبل النشر

الاشتراك في المواضيع (Topic Messaging)

من أقوى ميزات FCM هي المواضيع. تخيّل أن عندك تطبيق إخباري — بدل ما ترسل إشعار لكل مستخدم بشكل فردي، تشترك المستخدمين في مواضيع مثل "رياضة" أو "تقنية" وترسل إشعاراً واحداً للموضوع:

// اشتراك المستخدم في موضوع العروض
await _notificationService.SubscribeToTopicAsync("offers");

// اشتراك في موضوع الأخبار
await _notificationService.SubscribeToTopicAsync("news");

// إلغاء الاشتراك
await _notificationService.UnsubscribeFromTopicAsync("offers");

وعلى جانب الخادم:

var message = new Message
{
    Topic = "offers",
    Notification = new Notification
    {
        Title = "عرض جديد!",
        Body = "تخفيضات نهاية الموسم — خصومات تصل إلى 70%"
    }
};

await FirebaseMessaging.DefaultInstance.SendAsync(message);

بسيط وفعّال. Firebase يتكفل بإيصال الإشعار لكل الأجهزة المشتركة في الموضوع.

الأسئلة الشائعة

هل يمكن اختبار إشعارات الدفع على المحاكي؟

على Android، نعم — بشرط أن تكون Google Play Services مثبتة على المحاكي. لكن النتائج ليست موثوقة دائماً وقد تواجه تأخيراً. أما على iOS، فالإجابة القصيرة: لا. إشعارات الدفع لا تعمل على محاكي iOS. استخدم جهازاً فعلياً أو وزّع التطبيق عبر TestFlight.

ما الفرق بين Firebase Cloud Messaging و Azure Notification Hubs؟

FCM هو خدمة مجانية من Google تعمل مباشرة مع Android وعبر APNs لـ iOS. أما Azure Notification Hubs فهو طبقة وسيطة تدير إرسال الإشعارات لعدة منصات من مكان واحد. إذا كان مشروعك يعتمد على Azure أصلاً، فقد يكون Notification Hubs خياراً منطقياً. لكن إذا كنت تبدأ من الصفر، FCM أبسط وأسرع في الإعداد بلا منافس.

هل تعمل المكتبة مع .NET MAUI 10؟

نعم. مكتبة Plugin.FirebasePushNotifications تدعم .NET 7 وما بعده، بما في ذلك .NET 10.

كيف أتعامل مع الإشعارات عندما يكون التطبيق مغلقاً تماماً؟

عندما يكون التطبيق مغلقاً، نظام التشغيل هو من يعرض الإشعار. عندما يضغط المستخدم عليه، يُفتح التطبيق وتُمرر بيانات الإشعار عبر Intent على Android أو LaunchOptions على iOS. في الكود الذي كتبناه، نتعامل مع هذا تحديداً عبر OnNewIntent في Android و FinishedLaunching في iOS.

هل يمكن إرسال إشعارات صامتة لتحديث البيانات في الخلفية؟

نعم، يمكنك إرسال رسائل بيانات فقط (Data-only messages) بدون عنوان أو نص. لن تظهر للمستخدم، لكنها تُفعّل حدث NotificationReceived ويمكنك استخدامها لمزامنة البيانات. فقط انتبه أن iOS أكثر تشدداً مع الإشعارات الصامتة مقارنة بـ Android — قد يتجاهلها النظام إذا رأى أن التطبيق يستهلك موارد كثيرة في الخلفية.