maui-push-notifications（毛伊岛推送通知）

Push Notifications — Gotchas & Best Practices

Troubleshooting Table

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.