*push

*push delegates remote push registration and receive/action events to sercrod.push. It is separate from local *notification display.

This is the standard route for ordinary notifications: FCM on Android, APNs on iPhone, and FCM Web or standards-based Web Push in supported browsers. The application may keep its backend, data, authentication, and notification decisions on its own server while using FCM/APNs only for device delivery. Delayed checks and Android foreground service delivery remain optional alternatives. See the notification route guide. Because push is a multi-stage workflow, start with the step-by-step push workflow guide before using this directive reference.

A non-clickable base *push declaration initializes push automatically. Capacitor may open the native OS permission dialog; a browser continues automatically when permission is already granted and otherwise reports $push.needs_action. Sercrod does not insert fallback text or controls.

• *push: coordinate permission, registration, optional endpoint handoff, and the default watch.
• *push.register: explicitly continue the shared registration.
• *push.unregister: remove the server registration, then the provider registration.
• *push.check-permissions: check permission.
• *push.request-permissions: request permission.
• *push.watch: watch receive and notification action events.
• *push.clear: clear the stored or explicit watch.
• Matching n-push forms are aliases.

<button type="button" *push.request-permissions *response="'pushPermissions'">Allow push</button>
<button type="button" *push.register *response="'pushRegistration'">Register device</button>
<p *push.watch *response="'lastPushEvent'"></p>
<button type="button" *push.clear>Stop watch</button>

Automatic setup

<p *push="/api/push"></p>

<button *if="$push && $push.needs_action" *push.register>
  Enable notifications
</button>

The first declaration will try permission checking, registration, and receive watching. In Capacitor it may invoke the native permission request without a WebView click. In a browser, a first permission request generally requires user interaction, so $push.needs_action will allow application-authored fallback UI to appear.

The fallback is optional. Without it, an ungranted browser will leave push inactive. Sercrod will expose state and an event but will not invent visible wording, localization, layout, or controls. needs_action means that a user action can continue setup. A denied permission is a separate status because application or site settings may need to be changed. The application cannot select Allow in the OS permission dialog for the user.

See Push workflow for application-wide registration reuse, the application endpoint contract, named watches, and server-first unregister behavior.

Timing and data

Register, unregister, permission, and clear actions are explicit. Base *push and *push.watch start automatically once on non-clickable declarations.

Registration writes $push, $push_registration, and $push_token. Permission results also write $push_permissions. Watch callbacks write $push_event and $push_notification; watch start writes $push_watch and $push_watch_id.

FCM Web

The push sample includes an FCM Web project bridge, firebase-config.js, and firebase-messaging-sw.js. The developer adds the public Firebase Web configuration and VAPID public key, serves the app over HTTPS, stores the returned FCM registration token, and sends through FCM from the application server. The Firebase JavaScript SDK is loaded by the browser; the end user does not install it.

Developer: configure Web app + VAPID + Service Worker + sending server
User: open site → press register → grant notification permission

Permission cannot be forced. iPhone and iPad Web Push additionally requires the user to add the web app to the Home Screen and open it there.

Browser FCM needs the public Web app configuration and public VAPID key. Capacitor Android instead needs google-services.json. A Firebase service-account JSON file is a private server-only credential and must never be placed in either client configuration.

Responsibility boundary

The adapter selects a project bridge, Capacitor PushNotifications, browser Web Push, or explicit no-op. FCM Web uses the existing project bridge position; it does not introduce another directive or runtime format.

The Capacitor app must install @capacitor/push-notifications. Android also requires the selected Firebase project's google-services.json; iOS requires the Push Notifications capability and Capacitor AppDelegate registration hooks. Confirm current setup in the Capacitor, Firebase, and Apple documentation.

*push does not send notifications. It hands a registration to the application endpoint only when its value or options explicitly declare an application registration endpoint; value-less *push remains device-side. Provider accounts, private credentials, token databases, hosting, server-side FCM/APNs delivery, recipient selection, and production notification policy remain application-operator responsibilities.

On iPhone, ordinary timely notifications use APNs. VoIP wake-up is not an APNs-free alternative: it uses APNs PushKit and must be limited to genuine incoming-call behavior with the required CallKit flow.