*background-notification

This is Sercrod's standard starting point for notification checks that do not require immediate delivery. Capacitor Background Runner performs a short server check when the operating system grants an execution opportunity. It does not keep the app, WebView, Sercrod runtime, or a WebSocket alive.

OS grants a background opportunity
  → Background Runner checks the application endpoint
  → HTTP 204: finish
  → notification JSON: save result, show a local notification, finish
  → the user taps the notification and opens the app

This is not a complete replacement for push. Use *push when chat, calls, emergencies, or another feature requires timely delivery.

Actions

• *background-notification / .enable: save options and enable checks.
• .configure: save the endpoint and request options.
• .disable: make scheduled invocations exit without a request.
• .check-now: dispatch one check for setup and testing.
• .status: read configuration and the last saved result.
• .check-permissions / .request-permissions: manage local-notification permission.

<button type="button" *background-notification.request-permissions>Allow notifications</button>
<button type="button" *background-notification.enable="{ url: '/api/notifications/check' }">Enable checks</button>
<button type="button" *background-notification.check-now *response="'checkResult'">Check now</button>

Minimal development path

1. Create a small HTTPS endpoint that returns HTTP 204 when there is no update.
2. For an update, return JSON such as { "notification": { "id": 1001, "title": "New update", "body": "Open the app" } }.
3. Install @capacitor/background-runner and bundle background-notification-runner.js.
4. Register the runner label, source, scheduled event, repeat interval, and automatic start in the Capacitor build configuration.
5. Apply the plugin's Android repository setup. For iOS, enable Background Fetch and Background Processing, add the matching task identifier, and register Background Runner in AppDelegate.
6. Request notification permission, enable the endpoint, and verify the contract with .check-now.
7. Test delayed execution on a real device. Also check the endpoint when the app opens, because background execution is not guaranteed.

The sandbox/app/background-notification/ sample contains the plugin declaration, runner configuration, wrapper, directives, and tests. Follow the current Capacitor Background Runner documentation for platform setup details.

Platform behavior

Android repeating work has a minimum requested interval of 15 minutes and may be delayed. On iOS, the operating system decides when and how often the task runs and normally permits about 30 seconds per invocation. Neither platform provides an exact schedule or delivery guarantee. Background tasks must be tested on real devices.

Cost and responsibility boundary

This route does not require Firebase, APNs message sending, or a UnifiedPush distributor. It therefore has no push-provider subscription in the described flow. The application developer still pays any hosting, bandwidth, domain, TLS, monitoring, and mobile-store distribution costs used by the project. Apple currently lists Apple Developer Program membership at USD 99 per year for distribution and related capabilities; confirm current regional terms on the Apple membership page.

The adapter does not execute Sercrod directives in the background, open the app UI, keep a WebSocket connected, provide remote push, guarantee delivery, or guarantee an interval. The application developer owns the endpoint, authentication, response rules, deduplication, and production notification policy. Disabling stores a flag that makes later invocations exit immediately; it does not remove the build-time native task registration.