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