benxu.AppPlatform.Firebase.Fcm 3.0.4

benxu.AppPlatform.Firebase.Fcm

Firebase Cloud Messaging (FCM) 實作套件 - 使用官方/社群套件 (Plugin.Firebase.CloudMessaging) 提供推播通知服務與 Deep Link 路由功能。

特色

• 真實 FCM 整合：使用 Plugin.Firebase.CloudMessaging 進行原生 API 呼叫。
• 推播通知接收：支援前景與背景通知接收。
• Deep Link 路由：內建 Deep Link 解析與導航機制。
• Device Token 管理：自動取得與更新 FCM Token。
• 權限管理：封裝各平台的通知權限請求邏輯。
• 背景通知增強：整合 Local Notification，支援 Data-only Message 以解決 Android 背景通知歷史紀錄問題。

背景通知與 Data-only Message

本服務支援兩種類型的 FCM 訊息：

1. Notification Message（預設）：包含 notification 欄位。由系統自動處理顯示。

   • 優點：簡單，整合容易。
   • 缺點：APP 在背景時無法執行程式碼，導致無法紀錄通知歷史，直到使用者點擊通知。

2. Data-only Message（推薦）：不包含 notification 欄位，僅包含 data。

   • APP 收到訊息後會自行觸發 LocalNotificationService 顯示通知，並同步紀錄歷史。
   • 這是解決背景通知無法紀錄歷史的最佳方案。
   • 需配合後端調整發送 Payload 格式。

測試 Data-only Message

專案提供 PowerShell 腳本協助測試 Data-only Message：

.\scripts\Send-FcmMessage.ps1 -ServerKey "YOUR_SERVER_KEY" -Token "DEVICE_TOKEN"

支援平台

• ✅ Android (完整支援)
• ✅ iOS (完整支援)

安裝

1. 安裝套件：

   dotnet add package benxu.AppPlatform.Firebase.Fcm
   

2. 平台設定：

   • Android: 需設定 AndroidManifest.xml 權限與 google-services.json。
   • iOS: 需設定 Info.plist 與 GoogleService-Info.plist，並啟用 Push Notifications Capability。

使用方式

1. 平台初始化

iOS 平台

在 iOS 專案的 AppDelegate.cs 中初始化 FCM：

using benxu.AppPlatform.Firebase.Fcm.Platforms.iOS;

[Register("AppDelegate")]
public class AppDelegate : MauiUIApplicationDelegate
{
    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        // 初始化 FCM（啟用前景通知）
        _ = FcmAppDelegate.InitializeFcmAsync(showForegroundNotifications: true);

        return base.FinishedLaunching(application, launchOptions);
    }

    public override void RegisteredForRemoteNotifications(UIApplication application, NSData deviceToken)
    {
        FcmAppDelegate.HandleRegisteredForRemoteNotifications(deviceToken);
    }

    public override void FailedToRegisterForRemoteNotifications(UIApplication application, NSError error)
    {
        FcmAppDelegate.HandleFailedToRegisterForRemoteNotifications(error);
    }

    public override void DidReceiveRemoteNotification(UIApplication application, NSDictionary userInfo,
        Action<UIBackgroundFetchResult> completionHandler)
    {
        FcmAppDelegate.HandleDidReceiveRemoteNotification(userInfo, completionHandler);
    }

    public override void OnActivated(UIApplication application)
    {
        FcmAppDelegate.HandleOnActivated();
        base.OnActivated(application);
    }
}

Android 平台

Android 平台已自動處理，無需額外初始化代碼。

2. 註冊服務

在 MauiProgram.cs 中：

using benxu.AppPlatform.MAUI.Bootstrap.Extensions;

builder.UseAppPlatform(options =>
{
    options.UseFcm(fcm =>
    {
        fcm.EnableForegroundNotifications = true;
        fcm.DefaultNotificationChannelId = "my_channel";
        fcm.AutoSubscribeTopics = new List<string> { "global" };
    });
});

3. 應用程式初始化

在 App.razor 或主要 Layout 初始化並訂閱事件：

@inject IPushNotificationService PushService

@code {
    protected override async Task OnInitializedAsync()
    {
        PushService.NotificationReceived += OnNotificationReceived;
        PushService.NotificationTapped += OnNotificationTapped;

        await PushService.InitializeAsync();
    }

    // ... 事件處理
}

4. Deep Link 路由

@inject IDeepLinkRouter DeepLinkRouter

// 註冊路由
DeepLinkRouter.RegisterRouteHandler("myapp", async (deepLink) =>
{
    if (deepLink.Host == "product")
    {
        var id = deepLink.QueryParameters.GetValueOrDefault("id");
        Navigation.NavigateTo($"/products/{id}");
        return Result.Success();
    }
    return Result.Failure("Unknown route");
});

iOS 平台專用功能

通知 Helper 工具

FcmNotificationHelper 提供 iOS 專用的通知管理功能：

using benxu.AppPlatform.Firebase.Fcm.Platforms.iOS;

// 請求通知權限
var granted = await FcmNotificationHelper.RequestNotificationPermissionAsync();

// 檢查通知權限
var hasPermission = await FcmNotificationHelper.HasNotificationPermissionAsync();

// 清除所有通知
FcmNotificationHelper.ClearAllNotifications();

// 設定 Badge 數字
FcmNotificationHelper.SetBadgeCount(5);

// 顯示本地通知
await FcmNotificationHelper.ShowLocalNotificationAsync("標題", "內容", data);

通知委派事件

FcmAppDelegate 提供事件訂閱功能：

// 訂閱前景通知接收事件
FcmAppDelegate.SubscribeNotificationReceived((sender, e) =>
{
    Console.WriteLine($"收到通知: {e.Title} - {e.Body}");
});

// 訂閱通知點擊事件
FcmAppDelegate.SubscribeNotificationTapped((sender, e) =>
{
    Console.WriteLine($"點擊通知: {e.Title}");
    // 處理 Deep Link 或導航
});

注意事項

• 模擬模式：目前尚未實作，請使用真實裝置測試推播功能。
• iOS 權限：iOS 模擬器無法接收遠端推播，必須使用實機測試。
• iOS 前景通知：需在 AppDelegate.cs 中呼叫 FcmAppDelegate.InitializeFcmAsync() 並設定 showForegroundNotifications: true。
• iOS Push Notifications Capability：必須在 Xcode 中啟用 Push Notifications Capability。

依賴項目

• Plugin.Firebase.CloudMessaging
• benxu.AppPlatform.Core

授權

MIT License - Copyright (c) 2025 benxu