Plugin.FirebasePushNotifications 2.5.0-pre

This is a prerelease version of Plugin.FirebasePushNotifications.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Plugin.FirebasePushNotifications --version 2.5.0-pre                
NuGet\Install-Package Plugin.FirebasePushNotifications -Version 2.5.0-pre                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Plugin.FirebasePushNotifications" Version="2.5.0-pre" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Plugin.FirebasePushNotifications --version 2.5.0-pre                
#r "nuget: Plugin.FirebasePushNotifications, 2.5.0-pre"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Plugin.FirebasePushNotifications as a Cake Addin
#addin nuget:?package=Plugin.FirebasePushNotifications&version=2.5.0-pre&prerelease

// Install Plugin.FirebasePushNotifications as a Cake Tool
#tool nuget:?package=Plugin.FirebasePushNotifications&version=2.5.0-pre&prerelease                

Plugin.FirebasePushNotifications

Version Downloads

Plugin.FirebasePushNotifications provides a seamless way to engage users and keep them informed about important events in your .NET MAUI applications. This open-source C# library integrates Firebase Cloud Messaging (FCM) into your .NET MAUI projects, enabling you to receive push notifications effortlessly.

Features

  • Cross-platform Compatibility: Works seamlessly with .NET MAUI, ensuring a consistent push notification experience across different devices and platforms.
  • Easy Integration: Simple setup process to incorporate Firebase Push Notifications into your .NET MAUI apps.
  • Flexible Messaging: Utilize FCM's powerful features, such as targeted messaging, to send notifications based on user segments or specific conditions.

Download and Install Plugin.FirebasePushNotifications

This library is available on NuGet: https://www.nuget.org/packages/Plugin.FirebasePushNotifications Use the following command to install Plugin.FirebasePushNotifications using NuGet package manager console:

PM> Install-Package Plugin.FirebasePushNotifications

You can use this library in any .NET MAUI project compatible to .NET 7 and higher.

Setup

Setup Firebase Push Notifications
  • Go to https://console.firebase.google.com and create a new project. The setup of Firebase projects is not (yet?) documented here. Contributors welcome!
  • You have to download the resulting Firebase service files and integrate them into your .NET MAUI csproj file. google-services.json is used by Android while GoogleService-Info.plist is accessible to iOS. Make sure the Include and the Link paths match.
<ItemGroup Condition="$(TargetFramework.Contains('-android'))">
	<GoogleServicesJson Include="Platforms\Android\Resources\google-services.json" Link="Platforms\Android\Resources\google-services.json" />
</ItemGroup>

<ItemGroup Condition="$(TargetFramework.Contains('-ios'))">
	<BundleResource Include="Platforms\iOS\GoogleService-Info.plist" Link="GoogleService-Info.plist" />
</ItemGroup>
  • iOS apps need to be enabled to support push notifications. Turn on the "Push Notifications" capability of your app in the Apple Developer Portal.
App Startup

This plugin provides an extension method for MauiAppBuilder UseFirebasePushNotifications which ensure proper startup and initialization. Call this method within your MauiProgram just as demonstrated in the MauiSampleApp:

var builder = MauiApp.CreateBuilder()
    .UseMauiApp<App>()
    .UseFirebasePushNotifications();

UseFirebasePushNotifications has optional configuration parameters which are documented in another section of this document.

API Usage

IFirebasePushNotification is the main interface which handles most of the desired Firebase push notification features. This interface is injectable via dependency injection or accessible as a static singleton instance IFirebasePushNotification.Current. We strongly encourage you to use the dependency injection approach in order to keep your code testable.

The following lines of code demonstrate how the IFirebasePushNotification instance is injected in MainViewModel and assigned to a local field for later use:

public MainViewModel(
    ILogger<MainViewModel> logger,
    IFirebasePushNotification firebasePushNotification)
{
    this.logger = logger;
    this.firebasePushNotification = firebasePushNotification;
}
Managing Notification Permissions

Before we can receive any notification we need to make sure the user has given consent to receive notifications. INotificationPermissions is the service you can use to check the current authorization status or ask for notification permission. You can either inject INotificationPermissions into your view models or access it via the the static singleton instance INotificationPermissions.Current.

  • Check the current notification permission status:
this.AuthorizationStatus = await this.notificationPermissions.GetAuthorizationStatusAsync();
  • Ask the user for notification permission:
await this.notificationPermissions.RequestPermissionAsync();

Notification permissions are handled by the underlying operating system (iOS, Android). This library just wraps the platform-specific methods and provides a uniform API for them.

Receive Notifications

The main goal of a push notification client library is to receive notification messages. This library provides a set of classic .NET events to inform your code about incoming push notifications. Before any notification event is received, we have to inform the Firebase client library, that we're ready to receive notifications. RegisterForPushNotificationsAsync registers our app with the Firebase push notification backend and receives a token. This token is used by your own server/backend to send push notifications directly to this particular app instance. The token may change after some time. It is not controllable by this library if/when the token is going to be updated. The TokenRefreshed event will be fired whenever a new token is available. See Token property and TokenRefreshed event provided by IFirebasePushNotification for more info.

await this.firebasePushNotification.RegisterForPushNotificationsAsync();

If we want to turn off any incoming notifications, we can unregister from push notifications. The Token can no longer be used to send push notifications to.

await this.firebasePushNotification.UnregisterForPushNotificationsAsync();

Following .NET events can be subscribed:

  • IFirebasePushNotification.TokenRefreshed is raised whenever the Firebase push notification token is updated. You'll need to inform your server/backend whenever a new push notification token is available.

  • IFirebasePushNotification.NotificationReceived is raised when a new push notification message was received.

  • IFirebasePushNotification.NotificationOpened is raised when a received push notification is opened. This means, a user taps on a received notification listed in the notification center provided by the OS.

  • IFirebasePushNotification.NotificationAction is raised when the user taps a notification action. Notification actions allow users to make simple decisions when a notification is received, e.g. "Do you like to take your medicine?" could be answered with "Take medicine" and "Skip medicine".

  • IFirebasePushNotification.NotificationDeleted is raised when the user deletes a received notification.

Topics

The most common way of sending push notifications is by targeting notification message directly to push tokens. Firebase allows to send push notifications to groups of devices, so-called topics. If a user subscribes to a topic, e.g. "weather_updates" you can send push notifications to this topic instead of a list of push tokens.

Subscribe to Topics

Use method SubscribeTopic with the name of the topic.

this.firebasePushNotification.SubscribeTopic("weather_updates");

Important:

  • Make sure you did run RegisterForPushNotificationsAsync before you subscribe to topics.
  • Topic names are case-sensitive: Registrations for topic "weather_updates" will not receive messages targeted to topic "Weather_Updates".
Send Notifications to Topic Subscribers

Use the Firebase Admin SDK (or any other HTTP client) to send a push notification targeting subscribers of the "weather_updates" topic:

HTTP POST https://fcm.googleapis.com/v1/projects/{{project_id}}/messages:send

{
    "message": {
        "topic": "weather_updates",
        "notification": {
            "title": "Weather Update",
            "body": "Pleasant with clouds and sun"
        },
        "data": {
            "sunrise": "1684926645",
            "sunset": "1684977332",
            "temp": "292.55",
            "feels_like": "292.87"
        }
    }
}

Notification Topic weather_updates

Notification Actions

Notification actions are special buttons which allow for immediate response to a particular notification. A list of NotificationActions is consolidated within a NotificationCategory.

Register Notification Actions

The following example demonstrates the registration of a notification category with identifier "medication_intake" and two actions "Take medicine" and "Skip medicine":

var categories = new[]
{
    new NotificationCategory("medication_intake", new[]
    {
        new NotificationAction("take_medication", "Take medicine", NotificationActionType.Foreground),
        new NotificationAction("skip_medication", "Skip medicine", NotificationActionType.Foreground),
    })
};

Notification categories are usually registered at app startup time using the following method call:

IFirebasePushNotification.Current.RegisterNotificationCategories(categories);
Subscribe to Notification Actions

Subscribe the event IFirebasePushNotification.NotificationAction to get notified if a user presses one of the notification action buttons. The delivered event args FirebasePushNotificationResponseEventArgs will let you know which action was pressed.

Send Notification Actions

Use the Firebase Admin SDK (or any other HTTP client) to send a push notification with:

HTTP POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

{
    "message": {
        "token": "XXXXXXXXXX",
        "notification": {
            "title": "Medication Intake",
            "body": "Do you want to take your medicine?"
        },
        "data": {
            "priority": "high"
        },
        "android": {
            "notification": {
                "click_action": "medication_intake"
            }
        },
        "apns": {
            "payload": {
                "aps": {
                    "category": "medication_intake"
                }
            }
        }
    }
}

If everything works fine, the mobile device with the given token displays the notification action as follows:

Notification Category medication_intake

More Push Notification Scenarios

There are a lot of features in this library that can be controlled via specific data flags. The most common scenarios are end-to-end tested using postman calls. You can find an up-to-date postman collection in this repository: FCM Plugin.FirebasePushNotifications.postman_collection.json

  • Import the collection in postman.
  • Adjust the variables, especially the project_id and the fcm_token accordingly.
  • Authenticate each call by selecting the Auth Type "Firebase Cloud Messaging API (Oauth 2.0)".
  • Press "Authorize" and enter the credentials of a user which is allowed to send FCM messages for the configured FCM project.

Options

to be documented

Contribution

Contributors welcome! If you find a bug or you want to propose a new feature, feel free to do so by opening a new issue on github.com.

Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-android33.0 is compatible.  net7.0-ios was computed.  net7.0-ios16.0 is compatible.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-android34.0 is compatible.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-ios17.0 is compatible.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.1.8-pre 194 11/12/2024
3.1.6-pre 107 10/31/2024
3.1.3-pre 71 10/31/2024
3.1.1-pre 71 10/30/2024
3.0.17 1,417 11/7/2024
3.0.11-pre 82 10/28/2024
3.0.10-pre 76 10/24/2024
3.0.8-pre 77 10/24/2024
3.0.3-pre 92 10/14/2024
2.5.35 1,073 10/28/2024
2.5.34-pre 64 10/24/2024
2.5.32-pre 63 10/24/2024
2.5.30-pre 59 10/24/2024
2.5.28-pre 51 10/21/2024
2.5.25-pre 88 10/18/2024
2.5.23-pre 65 10/14/2024
2.5.20-pre 93 10/7/2024
2.5.15-pre 77 10/7/2024
2.5.13 1,635 10/7/2024
2.5.10-pre 88 10/3/2024
2.5.8-pre 184 10/3/2024
2.5.7-pre 79 10/2/2024
2.5.4-pre 86 10/2/2024
2.5.3-pre 80 10/2/2024
2.5.0-pre 83 10/1/2024
2.4.22 1,148 9/17/2024
2.4.17-pre 125 9/15/2024
2.4.9-pre 97 9/12/2024
2.4.6-pre 111 9/6/2024
2.4.4-pre 105 9/3/2024
2.4.2-pre 92 9/2/2024
2.4.0-pre 83 8/31/2024
2.3.15-pre 86 9/12/2024
2.3.13-pre 81 9/1/2024
2.3.12 987 8/21/2024
2.3.5-pre 148 8/19/2024
2.3.0-pre 163 8/13/2024
2.2.117 311 8/13/2024
1.0.26 3,398 10/6/2023

2.5
- Move static properties from Android's FirebasePushNotificationManager to FirebasePushNotificationAndroidOptions
     
2.4
- Refactor instanciation of IFirebasePushNotification.
- Refactor startup procedure of platform-specific services.
- Add singleton instance INotificationPermissions.Current.

2.3
- General bug fixes and code cleanup.
- Bug fixes in the area of topic subscriptions.
- IFirebasePushNotification.Current.
- Add singleton instance IFirebasePushNotification.Current and INotificationPermissions.Current.

2.2
- Complete refactoring of the original 1.x implementation.
- Simplified APIs, less static code, support for dependency injection.

1.0
- Initial release.