Push Notifications — Gotchas & Best Practices

Troubleshooting Table

Issue	Cause	Fix
Token changes every debug run (Android)	Debug builds regenerate Firebase tokens	Always re-register in `OnNewToken`
`HttpClient` requests fail silently	`BaseAddress` missing trailing `/`	Ensure endpoint ends with `/`
iOS push won't arrive on simulator	Simulators don't support APNS	Use a physical iOS device
No notifications on Android 13+	`POST_NOTIFICATIONS` required (API 33+)	Call `RequestPermissions` in `OnCreate`
Notification channel missing (API 26+)	Android requires explicit channel creation	Create channel before sending
`SendNotificationAsync` throws for >20 tags	Azure NH tag expression limit	Batch tags in groups of 20
`422` on device registration	Platform string mismatch	Use `"fcmv1"` (not `"gcm"`) and `"apns"`
Token empty at `RegisterAsync`	Race condition on cold start	Guard with `IsNullOrWhiteSpace` check

Critical Gotchas

⚠️ BaseAddress trailing slash

HttpClient.BaseAddress must end with /. Without it, relative URI resolution silently breaks.

// ❌ Relative URIs resolve incorrectly
_http = new HttpClient { BaseAddress = new Uri("https://example.com") };

// ✅ Trailing slash required
_http = new HttpClient { BaseAddress = new Uri("https://example.com/") };

⚠️ Android: Always re-register on token refresh

Firebase tokens regenerate frequently in debug builds. If you skip OnNewToken, the backend holds a stale token and pushes silently fail.

// ❌ Only registering once at startup
// (token may change later without re-registration)

// ✅ Always re-register in OnNewToken
public override void OnNewToken(string token)
{
    var svc = IPlatformApplication.Current?.Services.GetService<IPushNotificationService>();
    if (svc is null) return;
    svc.Token = token;
    _ = svc.RegisterAsync();
}

⚠️ Android 13+ requires POST_NOTIFICATIONS permission

Without explicitly requesting POST_NOTIFICATIONS on API 33+, notifications are silently dropped.

⚠️ Azure NH tag expression limit: 20 tags

SendNotificationAsync throws if a tag expression references more than 20 tags. Batch into chunks:

// ✅ Batch tags to stay under the limit
var batches = request.Tags.Chunk(20);
foreach (var batch in batches)
{
    var tagExpr = string.Join(" || ", batch);
    await _hub.SendFcmV1NativeNotificationAsync(payload, tagExpr, ct);
}

⚠️ Use "fcmv1" not "gcm"

The legacy "gcm" platform string causes 422 errors on device registration. Always use "fcmv1" for Android and "apns" for iOS.

⚠️ iOS simulators cannot receive push notifications

APNS only works on physical iOS devices. Simulators silently ignore push registrations.

Platform Checklist

Android

google-services.json in Platforms/Android/ with <GoogleServicesJson> in .csproj
Xamarin.Firebase.Messaging NuGet package added (Android-only condition)
POST_NOTIFICATIONS permission requested on API 33+
Notification channel created before first notification (API 26+)
OnNewToken always calls RegisterAsync
FirebaseMessagingService registered in manifest with MESSAGING_EVENT intent filter

iOS

Push Notifications capability enabled in Apple Developer portal
APNs key (.p8) uploaded to Azure Notification Hub
Entitlements.plist with aps-environment set to development or production
CodesignEntitlements set in .csproj
RegisterForRemoteNotifications called on main thread after authorization grant
Device token converted to lowercase hex string (no dashes)

Backend

Azure Notification Hub configured with FCM V1 JSON and APNS key
BaseAddress ends with trailing /
Tag expressions batched in groups of ≤20
Platform strings: "fcmv1" and "apns" (not legacy values)

Architecture Overview

MAUI app → ASP.NET Core backend → Azure Notification Hub → FCM / APNS → device

See references/push-notifications-api.md for full implementation templates.

/maui-push-notifications

SKILL.md