패키지 상세v0.9.11

workmanager_apple

workmanager 플러그인의 Apple 플랫폼(iOS/macOS) 구현.

iOSmacOS

pub.dev API 문서 소스 코드

30일 다운로드: 27.9만
좋아요: 4
Pub 점수: 150

패키지 설치

flutter pub add workmanager_apple

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

workmanager_apple 패키지는 workmanager 플러그인에 대한 Apple 플랫폼(iOS 및 macOS) 지원을 제공하여 Flutter 애플리케이션에서 백그라운드 작업 실행을 가능하게 합니다. 개발자는 앱이 종료된 후에도 실행되는 주기적 또는 한 번만 실행되는 작업을 예약할 수 있으며, Apple 기기에서 신뢰할 수 있는 백그라운드 처리를 보장합니다. 이 구현은 iOS 및 macOS 시스템 API와 통합되어 플랫폼별 제약 조건과 전력 절약 기능을 존중하면서 효율적으로 백그라운드 실행을 관리합니다.

사용 사례

정기적인 데이터 동기화 스케줄링
백그라운드 위치 업데이트 실행 중
지연 알림 실행
오프라인 데이터 처리 수행
백그라운드 작업의 지속성 유지

주요 기능

Apple 플랫폼 고유의 백그라운드 작업 처리
iOS/macOS 시스템 API와의 통합
주기적 및 일회성 작업 지원
에너지 효율적인 백그라운드 실행
workmanager core와의 원활한 통합

적합한 대상

iOS에서 백그라운드 처리가 필요한 Flutter 앱
백그라운드 요구 사항이 있는 macOS 대상 개발자
신뢰할 수 있는 백그라운드 작업 스케줄링이 필요한 앱
다중 플랫폼에서 workmanager 플러그인을 사용하는 프로젝트
데이터 동기화 또는 모니터링 요구 사항이 있는 애플리케이션

고려 사항

Xcode 프로젝트 설정에서 올바른 구성이 필요합니다
iOS에서 제한된 백그라운드 실행 시간
앱 기능에서 백그라운드 모드를 활성화해야 합니다
모든 백그라운드 작업 유형과 호환되지 않습니다
일부 작업은 사용자 권한이 필요할 수 있습니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

Flutter Workmanager

Execute Dart code in the background, even when your app is closed (Android and iOS). On macOS, background tasks run while the app is running or backgrounded and the Mac is awake. Perfect for data sync, file uploads, and periodic maintenance tasks.

⚠️ Experimental web support now exists via workmanager_web (Service Worker + Web Worker based background execution). See the Web (experimental) page and the package README for honest limitations and how to test it in Chrome.

📖 Documentation

Get started with background tasks in Flutter:

→ Quick Start Guide - Installation and setup

→ API Documentation - Complete Dart API reference

→ Debugging Guide - Troubleshooting help

→ Troubleshooting Guide - Why tasks stop after app close (OEM battery optimization, constraints, verification)

🎯 Use Cases

Background tasks are perfect for:

Sync data from API - Keep your app's data fresh
Upload files in background - Reliable file uploads
Clean up old data - Remove old files and cache
Fetch notifications - Check for new messages
Database maintenance - Optimize and clean databases

⏱ Long-Running Tasks (Android)

For work that takes longer than the regular background execution window (bulk uploads/downloads, ML processing), Android tasks can run as a foreground service with a persistent notification. Pass a foregroundServiceConfig to registerOneOffTask or registerPeriodicTask:

await Workmanager().registerOneOffTask(
  "upload-task",
  "upload_files",
  foregroundServiceConfig: ForegroundServiceConfig(
    notificationTitle: "Uploading files",
    notificationText: "Your files are being uploaded",
  ),
);

See the Quick Start guide for details and platform caveats.

🛑 Cancelling Running Work (Android)

cancelByUniqueName, cancelByTag and cancelAll stop the WorkManager worker immediately, but the Dart callback that is currently running keeps executing unless it reacts to the stop. Pass an onTaskStopped handler to executeTask inside your callbackDispatcher to be notified when a running task is stopped before it finishes:

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask(
    (taskName, inputData) async {
      return true;
    },
    onTaskStopped: (taskName, stopReason) async {
      // Mark the task as cancelled / persist state, then return promptly.
    },
  );
}

The handler receives the task name and the WorkManager stop reason (cancelledByApp, timeout, preempt, ...); on Android < 12 the reason is StopReason.unknown. Android-only — iOS has no way to stop a running task. See the Customization guide for details.