flutter_background 0.1.5

A plugin to keep flutter apps running in the background by using foreground service, wake lock and disabling battery optimizations

flutter_background

A plugin to keep flutter apps running in the background. Currently only works with Android.

It achieves this functionality by running an Android foreground service in combination with a partial wake lock and disabling battery optimizations in order to keep the flutter isolate running.

Note: This plugin currently only works with Android. PRs for iOS are very welcome, although I am not sure if a similiar effect can be achieved with iOS at all.

Getting started

To use this plugin, add flutter_background as a dependency in your pubspec.yaml file.

Android

Add the following permissions to the AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="de.julianassmann.flutter_background_example">

    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />

    <application>
    ...
    </application>
</manifest>

iOS

iOS is currently not supported.

Usage

Import flutter_background.dart:

import 'package:flutter_background/flutter_background.dart';

Initializing plugin and handling permissions

Before you can use this plugin, you need to initialize it by calling FlutterBackground.initialize(...):

final androidConfig = FlutterBackgroundAndroidConfig(
    notificationTitle: "Title of the notification",
    notificationText: "Text of the notification",
    importance: AndroidNotificationImportance.Default,
);
bool success = await FlutterBackground.initialize(androidConfig: androidconfig);

In order to function correctly, this plugin needs a few permissions. FlutterBackground.initialize(...) will request permissions from the user if necessary.

In 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

bool hasPermissions = await FlutterBackground.hasPermissions;

before calling FlutterBackground.initialize(...). If the app already has all necessary permissions, no permission requests will be displayed to the user.

Run app in background

With

bool success = await FlutterBackground.enableBackgroundExecution();

you can try to get the app running in the background. You must call FlutterBackground.initialize() before calling FlutterBackground.enableBackgroundExecution().

With

await FlutterBackground.disbleBackgroundExecution();

you can stop the background execution of the app. You must call FlutterBackground.initialize() before calling FlutterBackground.disbleBackgroundExecution().

To check whether background execution is currently enabled, use

bool enabled = FlutterBackground.isBackgroundExecutionEnabled

Notes

The plugin is currently hard-coded to load the icon for the foreground service notification from a drawable resource with the identifier ic_launcher. So if you want to change the logo for the notification, you have to change this resource. I'm planning to allow for custom resource names.

Example

The 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.

Using 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.

ToDo

• Add automated tests
• On android, add ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS as an option to obtain excemption from battery optimizations, as declaring REQUEST_IGNORE_BATTERY_OPTIMIZATIONS might lead to a ban of the app in the Play Store, "unless the core function of the app is adversely affected" (see the note here)
• On android, allow for other notification icon resource names than ic_launcher
• Explore options of background execution for iOS (help needed, I don't have any Mac/iOS devices or experience with programming for them)

Maintainer

Julian Aßmann

If you experience any problems with this package, please create an issue on Github. Pull requests are also very welcome.