Getting Started

Salin prompt pengaturan dengan langkah instalasi 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 mengizinkan aplikasi Capacitor mendaftarkan pekerjaan berulang untuk sinkronisasi, pembaruan cache, pengiriman analitik, dan operasi fetch latar belakang lainnya.

Instal

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin. Tambahkan keterampilan Capgo ke alat AI Anda menggunakan perintah 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 suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

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

Setup iOS

Tambahkan mode pengolahan latar belakang dan identifikasi 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';

Tentukan Tugas A

Tentukan callback di lingkungan modul sehingga terdaftar segera ketika aplikasi dimulai 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 aplikasi Anda memiliki konteks yang cukup untuk mengaktifkan pekerjaan latar.

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

minimumInterval dalam menit. Android menetapkan batasan minimum 15 menit. iOS menganggap nilai sebagai tanggal mulai terakhir dan mungkin menjalankan lebih lambat.

Periksa Status

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

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

Aktifkan Pengujian

Gunakan trigger pengujian dalam pengembangan atau QA. Ini memanggil setiap tugas yang terdaftar secara langsung.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Batal Daftar Tugas

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

Masa Berlaku iOS

iOS dapat menghentikan tugas latar belakang sebelum pekerjaan JavaScript Anda selesai. Dengarkan event kedaluwarsa ketika hal-hal cleanup atau checkpointing penting.

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

await expiration.remove();

Kemampuan Tugas Latar Belakang React Native Kompatibilitas

Plugin ini juga mengekspos layer 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

Pengaturan latar belakang adalah oportunis, bukan tepat.
Tetapkan pekerjaan singkat dan idempoten.
Simpan semua keadaan yang dibutuhkan sebelum kembali BackgroundTaskResult.Success.
Hindari mengandalkan tugas latar belakang untuk deadline atau alarm yang terlihat oleh pengguna.

Lanjutkan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan kerja plugin native, hubungkannya dengan Menggunakan @capgo/capacitor-tugas-kebelakang untuk kemampuan native di Menggunakan @capgo/capacitor-tugas-kebelakang, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo, Mengambah atau Mengupdate Plugin untuk detail implementasi di Mengambah atau Mengupdate Plugin, dan Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic.