Background Sync Plugin moves the synchronization of offline data and heavy files out of the WebView and into the native layer (Kotlin on Android, Objective-C on iOS). The app puts records in a private queue; the native engine sends them to your REST API one by one, retries when the network comes back, and shows a progress notification. WebView suspension does not stop it.

Demo video (84 s): 336 photos (418 MB) keep syncing with the app in the background, the screen locked and the network cut: https://media.hfps.dev/showcase/background-sync-demo.mp4

What it is for

• Field apps that capture many photos or documents (inspections, audits, deliveries) and cannot make the user wait with the app open.
• Unstable networks: the queue survives network drops, app restarts and reboots, and resumes on its own.
• Saving data and battery: optionally sync only on Wi-Fi or only while charging (Android).

How it works

1. Call InitSyncEngine once at app start (server URL, headers, notification texts, optional SQLCipher encryption).

2. Add one record per item with EnqueueUpload: an id, a JSON payload, the API endpoint and, optionally, the local file path.

3. Call TriggerSync. The engine sends each record as POST { "payload": {...}, "file": { "filename", "contentType", "base64Data" } }, or uploads the file straight to cloud storage with a pre-signed URL (PRESIGNED_URL).

4. Follow the run with the EventListenners block (OnStarted, OnProgress, OnFailed, OnCompleted) and query the queue with GetQueuedUploads and GetCompletedUploads.

Features

• Private SQLite queue (bg_sync.db), isolated from your local entities; optional SQLCipher encryption with the key in Android Keystore / iOS Keychain.
• Uploads (REST payload with base64 file, or pre-signed URL to S3/GCS/Azure) and background downloads (JSON deltas or binary files).
• Files are streamed from disk: large files do not cross the JavaScript bridge or load into memory.
• Automatic retries, sequential processing, idempotent record ids.
• Native progress and result notifications with your own texts.
• Native Database Inspector screen for support and recovery.

Platform behaviour

• Android: runs under WorkManager; continues with the app in the background, closed, or the device locked.
• iOS: runs in the foreground and for the background window iOS grants (about 30 seconds), then pauses and resumes when the app returns. No background modes are declared.

Demo

The attached demo, BGS Sample Mobile, is a field audit app: capture photos offline, sync them in the background, and watch them arrive in BGS Sample Backoffice. It needs BGS Sample Backoffice, a separate Forge asset; install that first. See the Documentation tab for the setup.

Source, native code and full documentation: https://github.com/henriquefps/cordova-background-sync-plugin