{"id":31563012,"url":"https://github.com/julianassmann/flutter_background","last_synced_at":"2025-10-05T04:55:29.131Z","repository":{"id":37865600,"uuid":"311698758","full_name":"JulianAssmann/flutter_background","owner":"JulianAssmann","description":"A flutter plugin to keep apps running in the background via foreground services. Android only.","archived":false,"fork":false,"pushed_at":"2024-08-28T10:07:43.000Z","size":5304,"stargazers_count":89,"open_issues_count":24,"forks_count":52,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-18T09:37:32.133Z","etag":null,"topics":["android","background-android","background-jobs","flutter","package"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/flutter_background","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JulianAssmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-10T15:19:22.000Z","updated_at":"2024-11-19T02:28:33.000Z","dependencies_parsed_at":"2024-03-26T10:36:50.156Z","dependency_job_id":"ced9edc4-0cf2-49e9-ba31-4e11064ab4a6","html_url":"https://github.com/JulianAssmann/flutter_background","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JulianAssmann/flutter_background","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianAssmann%2Fflutter_background","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianAssmann%2Fflutter_background/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianAssmann%2Fflutter_background/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianAssmann%2Fflutter_background/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JulianAssmann","download_url":"https://codeload.github.com/JulianAssmann/flutter_background/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianAssmann%2Fflutter_background/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278411267,"owners_count":25982368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","background-android","background-jobs","flutter","package"],"created_at":"2025-10-05T04:55:27.421Z","updated_at":"2025-10-05T04:55:29.121Z","avatar_url":"https://github.com/JulianAssmann.png","language":"Dart","funding_links":["https://www.buymeacoffee.com/julianassmann"],"categories":[],"sub_categories":[],"readme":"# flutter_background\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/julianassmann)\n\nA plugin to keep flutter apps running in the background. Currently only works with Android.\n\nIt achieves this functionality by running an [Android foreground service](https://developer.android.com/guide/components/foreground-services) in combination with a [partial wake lock](https://developer.android.com/training/scheduling/wakelock#cpu) and [disabling battery optimizations](https://developer.android.com/training/monitoring-device-state/doze-standby#support_for_other_use_cases) in order to keep the flutter isolate running.\n\n**Note:** This plugin currently only works with Android.\nPRs for iOS are very welcome, although I am not sure if a similar effect can be achieved with iOS at all.\n\n## Getting started\n\nTo use this plugin, add `flutter_background` as a [dependency in your `pubspec.yaml` file](https://pub.dev/packages/flutter_background/install).\n\n### Android\n\nAdd the following permissions to the `AndroidManifest.xml`:\n\n```xml\n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    package=\"de.julianassmann.flutter_background_example\"\u003e\n\n    \u003c!-- Adapt to the foreground service type(s) desired, these are just examples --\u003e\n    \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE_DATA_SYNC\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE_SPECIAL_USE\" /\u003e\n\n    \u003capplication\u003e\n        ...\n\n        \u003c!-- Adapt to the foreground service type(s) desired, these are just examples --\u003e\n        \u003cservice\n            android:name=\"de.julianassmann.flutter_background.IsolateHolderService\"\n            android:exported=\"false\"\n            android:foregroundServiceType=\"dataSync|specialUse|...\" /\u003e\n    \u003c/application\u003e\n\u003c/manifest\u003e\n```\n\n**Important**: You must specify the appropriate `foregroundServiceType` for your use case. See the [Android docs](https://developer.android.com/about/versions/14/changes/fgs-types-required) and the [list of available service typs](https://developer.android.com/develop/background-work/services/fg-service-types) for more information on foreground service types.\n\n### Other platforms\n\nAndroid is the only supported platform. There are currently no plans to extend support for other platforms, but feel free to change that by contributing to this plugin.\n\n## Usage\n\nImport `flutter_background.dart`:\n\n```dart\nimport 'package:flutter_background/flutter_background.dart';\n```\n\n### Initializing plugin and handling permissions\n\nBefore you can use this plugin, you need to initialize it by calling `FlutterBackground.initialize(...)`:\n\n```dart\nfinal androidConfig = FlutterBackgroundAndroidConfig(\n    notificationTitle: \"flutter_background example app\",\n    notificationText: \"Background notification for keeping the example app running in the background\",\n    notificationImportance: AndroidNotificationImportance.normal,\n    notificationIcon: AndroidResource(name: 'background_icon', defType: 'drawable'), // Default is ic_launcher from folder mipmap\n);\nbool success = await FlutterBackground.initialize(androidConfig: androidConfig);\n```\n\nThis ensures all permissions are granted and requests them if necessary. It also configures the\nforeground notification. The configuration above results in the foreground notification shown below when\nrunning `FlutterBackground.enableBackgroundExecution()`.\n\n![The foreground notification created by the code above.](./images/notification.png \"The foreground notification created by the code above.\")\n\nThe arguments are:\n- `notificationTitle`: The title used for the foreground service notification.\n- `notificationText`: The body used for the foreground service notification.\n- `notificationImportance`: The importance of the foreground service notification.\n- `notificationIcon`: The icon used for the foreground service notification shown in the top left corner. This must be a drawable Android Resource (see [here](https://developer.android.com/reference/android/app/Notification.Builder#setSmallIcon(int,%20int)) for more). E. g. if the icon with name \"background_icon\" is in the \"drawable\" resource folder, it should be of value `AndroidResource(name: 'background_icon', defType: 'drawable').\n- `enableWifiLock`: Indicates whether or not a WifiLock is acquired when background execution is started. This allows the application to keep the Wi-Fi radio awake, even when the user has not used the device in a while (e.g. for background network communications).\n\nIn this example, `background_icon` is a drawable resource in the `drawable` folders (see the example app).\nFor more information check out the [Android documentation for creating notification icons](https://developer.android.com/studio/write/image-asset-studio#create-notification) for more information how to create and store an icon.\n\nIn order to function correctly, this plugin needs a few permissions.\n`FlutterBackground.initialize(...)` will request permissions from the user if necessary.\nYou can call initialize more than one time, so you can call `initalize()` every time before you call `enableBackgroundExecution()` (see below).\n\nIn order to notify the user about upcoming permission requests by the system, you need to know, whether or not the app already has these permissions. You can find out by calling\n\n```dart\nbool hasPermissions = await FlutterBackground.hasPermissions;\n```\nbefore calling `FlutterBackground.initialize(...)`. If the app already has all necessary permissions, no permission requests will be displayed to the user.\n\n### Run app in background\n\nWith\n\n```dart\nbool success = await FlutterBackground.enableBackgroundExecution();\n```\n\nyou can try to get the app running in the background. You must call `FlutterBackground.initialize()` before calling `FlutterBackground.enableBackgroundExecution()`.\n\nWith\n\n```dart\nawait FlutterBackground.disableBackgroundExecution();\n```\n\nyou can stop the background execution of the app. You must call `FlutterBackground.initialize()` before calling `FlutterBackground.disableBackgroundExecution()`.\n\nTo check whether background execution is currently enabled, use\n\n```dart\nbool enabled = FlutterBackground.isBackgroundExecutionEnabled;\n```\n\n## Example\n\nThe example is a TCP chat app: It can connect to a TCP server and send and receive messages. The user is notified about incoming messages by notifications created with the plugin [flutter_local_notifications](https://pub.dev/packages/flutter_local_notifications).\n\nUsing this plugin, the example app can maintain the TCP connection with the server, receiving messages and creating notifications for the user even when in the background.\n\n## Maintainer\n\n[Julian Aßmann](https://github.com/JulianAssmann)\n\nIf you experience any problems with this package, please [create an issue on Github](https://github.com/JulianAssmann/flutter_background/issues).\nPull requests are also very welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulianassmann%2Fflutter_background","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulianassmann%2Fflutter_background","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulianassmann%2Fflutter_background/lists"}