FireForNet.Firebase.Messaging.Apple 1.0.1-preview.22

FireForNet.Firebase.Messaging.Apple

Apple-native platform integration for FireForNet Firebase Cloud Messaging (iOS, macOS, Mac Catalyst).

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 Apple-specific Firebase Cloud Messaging for FireForNet. It implements all four platform contracts (IMessagingRegistrar, IMessagingEventSource, IMessagingPermissionManager, IMessagingTopicSubscriber) over public HTTPS — registration, unregistration, and topic operations hit fcmregistrations.googleapis.com directly; APNs handles delivery. It has zero Firebase bindings: FireForNet's own IFirebaseInstallations FID + FIS token is the single registration identity.

Installation

dotnet add package FireForNet.Firebase.Messaging.Apple

Usage

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

UseApple() fails fast at composition when AddFirebaseInstallations() has not been called.

Required consumer setup

1. APNs capability + entitlements

Enable Push Notifications for the app and add the aps-environment entitlement:

• iOS (Entitlements.plist): aps-environment = development/production.
• macOS / Mac Catalyst: the entitlement key is com.apple.developer.aps-environment (distinct from iOS), and the provisioning profile is embedded.provisionprofile (vs embedded.mobileprovision on iOS). APNs environment auto-detection mirrors the official SDK: simulator and App Store/TestFlight builds default to production; otherwise the profile entitlement decides; unreadable/missing profiles default to production. Override via MessagingAppleOptions.ApnsEnvironmentOverride when needed.

2. Register for remote notifications

UIApplication.SharedApplication.RegisterForRemoteNotifications();

Then forward the token before calling RegisterAsync:

[Export("application:didRegisterForRemoteNotificationsWithDeviceToken:")]
public void RegisteredForRemoteNotifications(UIApplication app, NSData deviceToken)
{
    var forwarder = Services.GetRequiredService<IAppleApnsTokenForwarder>();
    forwarder.SetApnsToken(Hex(deviceToken));
}

The registrar refuses to register without a forwarded token (FailedPrecondition with an actionable message) — the wire contract requires the APNs token in the registration body.

3. Wire the notification-center delegate

Assign FireForNet's delegate (or forward from your own) in FinishedLaunching:

UNUserNotificationCenter.Current.Delegate =
    Services.GetRequiredService<FireForNetNotificationCenterDelegate>();

Forwarding covers foreground presentation (WillPresentNotification), taps (DidReceiveNotificationResponse), and background data messages (DidReceiveRemoteNotification). Implement DidFinishLaunching notification-response forwarding via AppleMessagingForwarder.RetainLaunchNotification for cold-start pickup through GetInitialMessageAsync().

4. Authorization

One UNUserNotificationCenter authorization flow serves iOS, macOS, and Mac Catalyst — no Catalyst branch. MessagingAppleOptions.UseProvisionalAuthorization opt-in grants notifications silently (iOS 12+). On Mac Catalyst the returned MessagingPermissionStatus (not the grant callback) is authoritative because macOS may auto-grant or route the prompt to System Settings.

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

None. The Apple FID + APNs registration flow is plain public HTTPS (fcmregistrations.googleapis.com, two X-Goog-* headers, small JSON body) — a native implementation needs no third-party binding.

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.