FireForNet.Firebase.Messaging.Android 1.0.1-preview.21

FireForNet.Firebase.Messaging.Android

Native (non-MAUI) Android platform integration for FireForNet Firebase Cloud Messaging.

About FireForNet

FireForNet is a platform-agnostic, .NET-native Firebase Client SDK developed as part of the Circuids ecosystem. It provides a consistent Firebase client development experience across .NET application environments, while allowing platform-specific implementations where Firebase requires them.

About This Package

This package provides Android-specific Firebase Cloud Messaging for FireForNet. It implements all four platform contracts (IMessagingRegistrar, IMessagingEventSource, IMessagingPermissionManager, IMessagingTopicSubscriber) over the GMS CloudMessaging transport (registration + delivery) and FireForNet's native HTTPS topic client — using FireForNet's own IFirebaseInstallations FID + FIS token as the single registration identity.

Installation

dotnet add package FireForNet.Firebase.Messaging.Android

Usage

services.AddFirebase(new FirebaseOptions { /* ... */ });
services.AddFirebaseInstallations().UseAndroid();
services.AddFirebaseMessaging().UseAndroid();

UseAndroid() fails fast at composition when AddFirebaseInstallations() has not been called: every FCM call is authenticated with FireForNet's FID and FIS token.

MAUI apps on Android should normally call UseMaui() from FireForNet.Firebase.Messaging.Maui-chained flows, which delegate to this package on the Android TFM.

Required consumer setup

1. Manifest flag (registration precondition)

The V1 registration path requires the manifest meta-data flag in your AndroidManifest.xml:

<application>
  <meta-data
      android:name="firebase_messaging_installation_id_enabled"
      android:value="true" />
</application>

Registration without the flag fails with MessagingErrorCode.FailedPrecondition naming the flag. Devices with Google Play Services below the Y2026W12 floor (261200000) also receive an actionable FailedPrecondition; no legacy fallback exists.

2. Declare the messaging service

The package manifest-merges the receiver hop automatically. You declare the service hop:

[Service(Name = "com.example.app.MyMessagingService", Exported = false, DirectBootAware = true)]
[IntentFilter(new[] { "com.google.firebase.MESSAGING_EVENT" }, Priority = (int)IntentFilterPriority.Lowest)]
public sealed class MyMessagingService : FireForNetMessagingService
{
}

priority=-500 (Lowest) lets your service win intent-filter resolution. The receiver (FireForNetMessagingReceiver) and the four permissions (ACCESS_NETWORK_STATE, POST_NOTIFICATIONS, WAKE_LOCK, com.google.android.c2dm.permission.RECEIVE) are merged from the package manifest — no consumer action needed.

3. Attach the activity context (permission prompt)

Notification permission requires a resumed activity. Attach the lifecycle tracker at startup:

// In Application.OnCreate or MainActivity.OnCreate:
var activityContext = new DefaultAndroidActivityContext();
activityContext.Attach(this);

4. Initialize Messaging before MainActivity.OnCreate returns (cold-start taps)

Delivery events are raised to a scoped event source. On a cold start from a notification tap the receiver hop runs before your DI container exists, so initialize IFirebaseMessaging before MainActivity.OnCreate returns:

protected override void OnCreate(Bundle? savedInstanceState)
{
    var messaging = Services.GetRequiredService<IFirebaseMessaging>();
    messaging.EnsureReadyAsync().GetAwaiter().GetResult();
    base.OnCreate(savedInstanceState);
}

Cold-start launch payloads are retained by the bridge for one-shot consumption via GetInitialMessageAsync(); warm-start taps surface through OnNotificationOpened.

5. Notification channel (background notifications)

Background notification messages display on the channel from MessagingAndroidOptions:

.UseAndroid(options => options.DefaultNotificationChannelId = "my_channel");

Create the channel in your app; when unset or missing, the FCM fallback channel is created lazily.

Topic operations

SubscribeToTopicAsync/UnsubscribeFromTopicAsync are platform-level operations independent of RegisterAsync state: the FID and FIS token are obtained per attempt from Installations, and the public fcmregistrations.googleapis.com endpoint is called directly (30-second timeout, 2xx success, 404/403 failure, 5xx retryable).

Dependency rationale

The single third-party dependency is Xamarin.GooglePlayServices.CloudMessaging — Google's minimal, supported client for the device-internal GMS IPC that carries FCM registration and delivery acknowledgment. No Xamarin.Firebase.* packages are referenced: topics, payload mapping, permission handling, and every HTTP surface are native FireForNet code.

Platform / Framework Support

Documentation

Comprehensive FireForNet documentation is being prepared for the Release Candidate stage.

Project Status

FireForNet is currently available as a Preview release and is approaching its Release Candidate milestone. APIs, package structure, and implementation details may continue to evolve before RC and GA.

The RC milestone will be followed by an extensive cross-platform validation and testing phase before the first GA release.

All FireForNet packages are part of a coordinated release train and share the same version number.

Source Availability

FireForNet is currently being developed in a private source repository during the Preview development phase. The source will be made publicly available as the project approaches its open-source phase, with the public repository established from the appropriate release milestone.

Until then, NuGet Preview packages provide the public distribution channel for evaluating and using FireForNet.

License

This package is licensed under the Apache-2.0 license.