Documentation on the configuration and use of the plugin is not clear. about capacitor-background-runner

[theproducer]

Hello!

For both iOS and Android, in what directory exactly is the background.js file supposed to live for each platform respectively?

It should in your build or dist folder - we are currently working on a process to help with this (and to facilitate using TypeScript for your runner file), but for now you'll need to copy your runner file into the appropriate directory. See our example test app:

capacitor-background-runner/apps/example-app/package.json

Line 51 in e954d30

"build": "react-scripts build && cp src/background.js build/background.js",

In capacitor.config.ts is it possible to define multiple events in event: 'myCustomEvent'?
Or is it that we can only define one event to execute automatically?

No, that's currently not possible at the moment.

Does interval: 2 mean 2 minutes? or 2 seconds?

This is in minutes. Keep in mind there are other constraints on the interval in which the OS will call your background task (Limitations of Background Tasks), so the interval you set here may not be hit exactly when running on a device.

When and where is it appropriate to execute an event that is defined in our runner?
Is it OK to do this inside the @capacitor/app plugin's appStateChange listener event?

You don't need to do anything to get your event called once everything is set up properly. So long as autoStart is true, the plugin will automatically register and schedule your background task with the OS.

For example, if you have the following config:

{
  autoStart: true,
  event: "runPeriodicUpdate",
  interval: 60,
  repeat: true
}

Once the app is sent to the background and no longer active, after 1 hour - every hour (or thereabouts, if you are on iOS), the OS will execute the task, and the plugin will call the runPeriodicUpdate event that has been defined in your runner js file.

dispatchEvent can be called directly while your app is in the foreground if you want to execute any runner code on a separate background thread outside of the UI / WebView.

---

Let us know if that helps. We're continuing to update the docs, and just from typing this out I noticed a few things I need to tweak and add to the current docs. It may help if I created some visuals to help to explain the overall process too.

[DisruptLive]

Hello!

For both iOS and Android, in what directory exactly is the background.js file supposed to live for each platform respectively?

It should in your build or dist folder - we are currently working on a process to help with this (and to facilitate using TypeScript for your runner file), but for now you'll need to copy your runner file into the appropriate directory. See our example test app:

capacitor-background-runner/apps/example-app/package.json

Line 51 in e954d30

"build": "react-scripts build && cp src/background.js build/background.js",

This is not ideal in my case since i am using Ionic 7 whereas it compiles using vite. For the life of me i cannot remember how i ultimately got this to work, but i have placed my background.js runner file in my public directory, and in capacitor.config.ts i just define the src as src: "background.js". I feel like i am forgetting something else? But it is working even though i would imagine we do not want our runner to exist in the public directory. Better documentation for details like this would really be helpful. I cannot remember nor do i understand how my capacitor.config is able to find it sitting there in the public directory. I also have not tested any of this on Android yet, so it might very well be that my setup could be an issue.

In capacitor.config.ts is it possible to define multiple events in event: 'myCustomEvent'?
Or is it that we can only define one event to execute automatically?

No, that's currently not possible at the moment.

Does interval: 2 mean 2 minutes? or 2 seconds?

This is in minutes. Keep in mind there are other constraints on the interval in which the OS will call your background task (Limitations of Background Tasks), so the interval you set here may not be hit exactly when running on a device.

When and where is it appropriate to execute an event that is defined in our runner?
Is it OK to do this inside the @capacitor/app plugin's appStateChange listener event?

You don't need to do anything to get your event called once everything is set up properly. So long as autoStart is true, the plugin will automatically register and schedule your background task with the OS.

For example, if you have the following config:

{
  autoStart: true,
  event: "runPeriodicUpdate",
  interval: 60,
  repeat: true
}

Once the app is sent to the background and no longer active, after 1 hour - every hour (or thereabouts, if you are on iOS), the OS will execute the task, and the plugin will call the runPeriodicUpdate event that has been defined in your runner js file.

dispatchEvent can be called directly while your app is in the foreground if you want to execute any runner code on a separate background thread outside of the UI / WebView.

Let us know if that helps. We're continuing to update the docs, and just from typing this out I noticed a few things I need to tweak and add to the current docs. It may help if I created some visuals to help to explain the overall process too.

What i would like to know is if i can call a custom iOS Plugin that i created for my app using this basic capacitor guide which was really helpful. So far i have managed to avoid having to create an entire plugin package in-order to do some basic work in swift using that guide. Id like to be able to call a method that exists in MyPlugin.swift from the background runner.

[DisruptLive]

Not sure where to reach out for further support, so asking here given the topic in focus being documentation.
How do we pass data that is retrieved inside the background runner to our native app through a method that exists in a custom plugin, be it for iOS or Android?

[theproducer]

For the life of me i cannot remember how i ultimately got this to work, but i have placed my background.js runner file in my public directory, and in capacitor.config.ts i just define the src as src: "background.js". I feel like i am forgetting something else? But it is working even though i would imagine we do not want our runner to exist in the public directory. Better documentation for details like this would really be helpful.

Yeah, this sounds about right. The runner js file needs to be its own file outside the rest of your app JS bundle, and the plugin search its search from within the public directory. We'll come up with a more ergonomic way of handling this.

Id like to be able to call a method that exists in MyPlugin.swift from the background runner.

This isn't supported yet. Depending on what you are trying to do, your runner code can store bits of data in UserDefaults / SharedPreferences, then you access it in native code using the same APIs. Adding custom JS bindings to a underlying native function is something we can expose in the near future, but it's a rather advanced use case.

For more conservational questions and other support, you can come to the Ionic Discord, I keep an eye on it periodically during the day.
https://discord.com/invite/UPYYRhtyzp