시작하기

@capgo/capacitor-background-task 앱이 Capacitor을 통해 주기적으로 동기화, 캐시 갱신, 분석 데이터 전송 및 다른 배경 데이터 가져오기 작업을 등록할 수 있도록 합니다.

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. 다음 명령어를 사용하여 Capgo 기능을 AI 도구에 추가하세요:

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을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-background-task
bunx 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>

그런 다음 실행하세요:

bunx cap sync ios

수입

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

스케줄 등록

호출 registerTaskAsync 앱이 충분한 맥락을 갖고 배경 작업을 활성화할 수 있을 때

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

minimumInterval 15분 이상입니다. 안드로이드는 최소 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 작업이 완료되기 전에 백그라운드 작업을 중지할 수 있습니다. cleanup 또는 checkpointing이 중요할 때 만료 이벤트를 듣는 것이 좋습니다.

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

await expiration.remove();

React Native 백그라운드 작업 호환성

플러그인은 React Native 앱이 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 Getting Started와 연결하세요. Using @capgo/capacitor-background-task Using @capgo/capacitor-background-task Capgo 플러그인 디렉토리 Capgo 제품 워크플로우에 대한 Capgo 플러그인 디렉토리에서 Capacitor 플러그인에 대한 Capgo Capgo 제품 워크플로우에 대한 Capacitor 플러그인에 대한 Capgo 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에 대한 구현 세부 정보, 그리고 아이오닉 엔터프라이즈 플러그인 대체 Capgo 제품 워크플로우에 대한 아이오닉 엔터프라이즈 플러그인 대체