시작하기

@capgo/capacitor-background-task Capacitor 앱에서 동기화, 캐시 갱신, 분석 데이터 전송 및 기타 백그라운드 fetch 작업을 위한 이름이 지정된 주기 작업을 등록할 수 있습니다.

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

iOS 설정

배경 처리 모드와 허용된 작업 식별자를 다음에 추가하세요: ios/App/App/Info.plist:

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

그런 다음 실행하세요:

npx cap sync ios

가져오기

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

자주 하는 실수

• 모듈 범위: 등록 defineTask 첫 번째 제출이 승인되기 registerTaskAsync.
• iOS ID: 매칭 BGTaskSchedulerPermittedIdentifiers 항목.
• 간격: OS가 작업을 그보다 더 지연시킬 수 있음 minimumInterval.

태스크 정의하기

콜백을 모듈 스코프에 정의해서 OS가 앱을 시작하자마자 등록되도록 하세요.

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;
  }
});

스케줄 등록하기

호출하세요 registerTaskAsync 앱이 백그라운드 작업을 활성화할 수 있을 만큼 충분한 컨텍스트를 확보한 후에.

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

minimumInterval 단위는 분입니다. Android는 최소 15분을 요구합니다. iOS는 해당 값을 가장 빠른 시작 시간으로 간주하며 실제 실행은 더 늦어질 수 있습니다.

상태 확인

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

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

테스트 실행 트리거

개발 또는 QA 단계에서 테스트 트리거를 사용하세요. 등록된 모든 태스크를 즉시 호출합니다.

await BackgroundTask.triggerTaskWorkerForTestingAsync();

태스크 등록 해제

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

iOS 만료

iOS는 JavaScript 작업이 완료되기 전에 백그라운드 태스크를 중단할 수 있습니다. 정리나 체크포인트 저장이 중요할 때는 expiration 이벤트를 수신하세요.

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

await expiration.remove();

React Native Background Task 호환성

이 플러그인은 ...에서 마이그레이션하는 앱을 위해 작은 호환 레이어도 제공합니다. 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,
});

프로덕션 노트

• 백그라운드 스케줄링은 정확한 시간이 아니라 기회적으로 실행됩니다.
• 작업은 짧고 멱등하게 유지하세요.
• 반환하기 전에 필요한 상태를 모두 저장하세요. BackgroundTaskResult.Success.
• 사용자에게 보이는 마감 시간이나 알람을 백그라운드 태스크에 의존하지 마세요.

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-background-task 사용하기 @capgo/capacitor-background-task 사용에서 네이티브 기능을 위해, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.