Panduan Memulai

Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-background-task`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/background-task/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

@capgo/capacitor-background-task memungkinkan aplikasi Capacitor mendaftarkan job periodik bernama untuk sinkronisasi, pembaruan cache, pengiriman analitik, dan operasi background fetch lainnya.

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-background-task` plugin in my project.

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

npm install @capgo/capacitor-background-task
npx cap sync

Setup iOS

Tambahkan mode pemrosesan latar belakang dan identifier tugas yang diizinkan ke ios/App/App/Info.plist:

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

Lalu jalankan:

npx cap sync ios

Impor

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

Kesalahan umum

Cakupan modul: daftarkan defineTask sebelum registerTaskAsync.
ID iOS: cocokkan BGTaskSchedulerPermittedIdentifiers entri.
Interval: OS mungkin menunda job melebihi minimumInterval.

Definisikan Task

Definisikan callback di scope module agar langsung terdaftar saat app dijalankan oleh sistem operasi.

import { BackgroundTask, BackgroundTaskResult } from '@capgo/capacitor-background-task';

const SYNC_TASK = 'sync-offline-data';

BackgroundTask.defineTask(SYNC_TASK, async () => {
  try {
    await fetch('https://api.example.com/sync', { method: 'POST' });
    return BackgroundTaskResult.Success;
  } catch {
    return BackgroundTaskResult.Failed;
  }
});

Daftarkan Jadwal

Panggil registerTaskAsync setelah app memiliki cukup context untuk mengaktifkan background job.

await BackgroundTask.registerTaskAsync(SYNC_TASK, {
  minimumInterval: 30,
  requiresNetwork: true,
});

minimumInterval dalam satuan menit. Android mewajibkan minimal 15 menit. iOS menganggap nilai tersebut sebagai waktu mulai paling awal dan mungkin berjalan lebih lambat.

Cek Status

const status = await BackgroundTask.getStatusAsync();
const isRegistered = await BackgroundTask.isTaskRegisteredAsync(SYNC_TASK);
const registeredTasks = await BackgroundTask.getRegisteredTasksAsync();

console.log({ status, isRegistered, registeredTasks });

Jalankan Uji Coba

Gunakan test trigger saat development atau QA. Trigger ini memanggil semua task yang terdaftar secara langsung.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Batalkan Pendaftaran Tugas

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Kedaluwarsa iOS

iOS dapat menghentikan background task sebelum pekerjaan JavaScript Anda selesai. Dengarkan event expiration saat cleanup atau checkpointing penting.

const expiration = await BackgroundTask.addExpirationListener((event) => {
  console.warn('Background task expired', event.taskName, event.taskId);
});

await expiration.remove();

Kompatibilitas Background Task React Native

Plugin ini juga menyediakan lapisan kompatibilitas kecil untuk aplikasi yang bermigrasi dari react-native-background-task.

import { BackgroundTask } from '@capgo/capacitor-background-task';

BackgroundTask.define(async () => {
  await fetch('https://api.example.com/sync', { method: 'POST' });
});

await BackgroundTask.schedule({
  period: 1800,
});

Catatan Produksi

Penjadwalan background bersifat oportunistik, bukan tepat waktu.
Jaga agar pekerjaan singkat dan idempoten.
Persist state yang Anda butuhkan sebelum mengembalikan BackgroundTaskResult.Success.
Hindari mengandalkan background task untuk tenggat waktu atau alarm yang terlihat oleh pengguna.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-background-task untuk kapabilitas native di Menggunakan @capgo/capacitor-background-task, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.