Getting Started

@capgo/capacitor-background-task lets a Capacitor app register named periodic jobs for sync, cache refreshes, analytics delivery, and other background fetch operations.

Ready to paste

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.

Manual Setup을 선호하시면 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래에 플랫폼별로 설명된 지침을 따르세요.

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

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

작업을 정의하세요.

애플리케이션이 운영 체제에 의해 시작되면 즉시 등록되도록 모듈 스코프에서 콜백을 정의하세요.

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

스케줄을 등록하세요.

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

테스트 실행

클립보드에 복사

await BackgroundTask.triggerTaskWorkerForTestingAsync();

Task를 해제하세요

await BackgroundTask.unregisterTaskAsync(SYNC_TASK);

iOS 만료

iOS는 JavaScript 작업이 끝나기 전에 백그라운드 작업을 중단할 수 있습니다. cleanup 또는 checkpointing이 중요할 때는 만료 이벤트를 듣는 것이 좋습니다.

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

await expiration.remove();

리액트 네이티브 백그라운드 작업 호환성

앱이 리액트 네이티브에서 Capacitor로 이전하는 경우에도 이 플러그인은 작은 호환성 layer를 제공합니다. 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,
});

생산 환경 참고 사항

• 배경 스케줄링은 정확하지 않으며 기회주의적입니다.
• 작업을 짧고 idempotent 하게 유지하세요.
• 반환하기 전에 필요한 모든 상태를 저장하세요. BackgroundTaskResult.Success.
• 사용자에게 보이는 마감일이나 알람을 위해 배경 작업에 의존하지 마세요.

Getting Started에서 계속하세요.

이미 사용 중이라면 Getting Started를 사용하여 네이티브 플러그인 작업을 계획하고 Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-background-task를 사용하여 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-background-task와 연결하세요. Using @capgo/capacitor-background-task를 사용하여 @capgo/capacitor-background-task를 사용하세요. Using @capgo/capacitor-background-task Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우를 위해 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부 정보를 위해 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 정보를 위해, 그리고 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 대체의 제품 워크플로우를 위해