Background work

#The permission

Add "background" to the Pulsar permissions. People see it before they install.

"pulsar": { "api": 1, "permissions": ["background"] }

#Two kinds of work

#Jobs

const job = await Pulsar.background.keepAlive("Checking 40 prices");   // title ≤ 80, shown to the user
try {
  for (const [i, item] of items.entries()) {
    await check(item);
    if (i % 10 === 9) await job.renew();      // another 10 minutes; only while connected
  }
} finally {
  await job.finish();
}

Pulsar.on("job.stopped", (m) => { if (m.jobId === job.jobId) stopChecking(); });

• A keepAlive job lasts 10 minutes. background.renew adds 10 more; it only works on an open connection.
• When your last connection drops (the page crashed or unloaded), you get 30 seconds to reconnect, then Pulsar stops your jobs. Schedules stay.
• Always finish() when you are done. People notice extensions that keep Pulsar running.

#Schedules

Pulsar.onConnect(async () => {
  const { intervalMin } = await Pulsar.background.schedule(60, "prices");   // name: A–Z a–z 0–9 . _ - (1–40)
  console.log("checking every", intervalMin, "minutes");
});

Pulsar.on("schedule.run", async (m) => {
  if (m.name !== "prices") return;
  await checkPrices();
});

// later
await Pulsar.background.cancel("prices");

• The shortest interval is 15 minutes (Android’s floor). The result says the interval used.
• Android may run checks late, to save battery. Don’t promise exact times.
• If Pulsar was closed, the schedule starts Pulsar’s engine and wakes your event page with schedule.run. Register the schedule again in onConnect; doing it twice is fine.

#What people see and control

• Every job shows in Settings › Background activity and in Pulsar’s “Pulsar is active” notification, with your title. People can stop it.
• Your row in the extensions list says “N running in background”. There is never a badge on your icon.
• When people switch your extension off or remove it, or Pulsar’s kill switch stops it, every job and schedule stops.