BackgroundDetector is an Android library written in Kotlin to provide tracking of foreground/background application status.

Integration

At the project level build.gradle, add a maven repo pointing to https://jitpack.io, e.g.:

allprojects {
    repositories {
        google()
        maven { url "https://jitpack.io" } // this is it
        jcenter()
    }
}

At a module level build.gradle, add the following dependency:

implementation 'com.github.vitkhudenko:background_detector:0.1.6'

How does it work?

App is assigned with background status when none of app’s activities are in started state.
And vice versa - if at least one activity in app is in started state, then app is assigned
with foreground status.

This approach has an undesired side effect: configuration changes, such as screen orientation changes,
would cause a short (typically 200-500 millis) period of background status followed by regaining
the foreground status. To mitigate this issue BackgroundDetector applies a status change debounce
delay which defaults to 700 ms (it is possible to supply a custom value via debounceDelayMillis param).

In order to track started state of activities, BackgroundDetector uses an implementation of
Application.ActivityLifecycleCallbacks reacting on onActivityStarted(activity: Activity) and
onActivityStopped(activity: Activity) invocations.

By default BackgroundDetector takes under account all activities in an app, however if your app requires
some activities to be ignored, then a custom implementation of BackgroundDetectorConfig can do the trick
(check the BackgroundDetectorConfig.shouldActivityBeProcessed(activity: Activity): Boolean).

Importance of a proper instantiation

For proper functioning BackgroundDetector must be instantiated at your app’s
Application.onCreate() callback. BackgroundDetector does not validate
correctness of its instantiation, so if this requirement is not met, then there will be no
warnings despite BackgroundDetector may report incorrect status.

Threading

The implementation is not thread-safe. BackgroundDetector must be accessed from the main thread only.

License

MIT License

Copyright (c) 2019 Vitaliy Khudenko

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.