Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-push-notifications

@79bb4bf
Run it yourself

End-to-end guide for adding push notifications to .NET MAUI apps. Covers Firebase Cloud Messaging (Android), Apple Push Notification Service (iOS), Azure Notification Hubs as the cross-platform broker, an ASP.NET Core backend API, and the MAUI client wiring on every platform. USE FOR: "push notification", "FCM", "APNS", "Firebase Cloud Messaging", "Azure Notification Hubs", "device registration", "remote notification", "send push notification", "notification token". DO NOT USE FOR: local/scheduled notifications (use maui-local-notifications), general permission handling (use maui-permissions), or background tasks without notifications (use maui-app-lifecycle).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-push-notifications

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈173 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈3.7k more on demand in 1 file.

Description uses 8.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈694 characters, or 8.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides a comprehensive and safe set of implementation templates and guides for integrating push notifications into .NET MAUI applications using Azure Notification Hubs, Firebase, and APNs.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-push-notifications