Skip to content
Capgo - Live Updates for Capacitor Apps Capgo

iOS setup

GitHub

iOS background processing uses BGTaskScheduler. The app must declare the background mode and the permitted task identifier before scheduling can work on a physical device.

Info.plist

Section titled “Info.plist”

Add these keys to ios/App/App/Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>processing</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>app.capgo.backgroundtask.processing</string>
</array>

Sync

Section titled “Sync”
Terminal window
npx cap sync ios

Behavior

Section titled “Behavior”
  • minimumInterval is mapped to earliestBeginDate.
  • iOS decides the actual run time based on battery, network, usage patterns, and system policy.
  • Background task execution does not run reliably in the simulator. Test on a physical device.
  • The plugin re-schedules the next background processing request after each task launch.

Expiration

Section titled “Expiration”

Use addExpirationListener when work needs cleanup if iOS ends the task early.

const handle = await BackgroundTask.addExpirationListener((event) => {
  console.warn('Task expired', event.taskName);
});


await handle.remove();

Keep going from iOS setup

Section titled “Keep going from iOS setup”

If you are using iOS setup to plan native plugin work, connect it with Using @capgo/capacitor-background-task for the native capability in Using @capgo/capacitor-background-task, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.