ForegroundAppChecker

Lightweight Android library that reports the package name of the application currently on top of other apps.

Built with Kotlin and Coroutines. Compatible with API 21 – 37.

Author: Mostafa Ashrafi
License: MIT

---

Features

• Callback (and optional Flow) with the foreground app’s package name
• Coroutine-based polling with a configurable interval
• Tiny dependency footprint (only kotlinx-coroutines-android)
• Helper APIs to check and open Usage access settings

---

Requirements

Item	Value
minSdk	21
compileSdk / targetSdk	37
Permission	PACKAGE_USAGE_STATS (Usage access)

The library merges PACKAGE_USAGE_STATS into your manifest. The user must still grant Usage access in system settings — this cannot be requested with a normal runtime permission dialog.

---

Installation

JitPack

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
        maven(url = "https://jitpack.io")
    }
}

app/build.gradle.kts

dependencies {
    implementation("com.github.ashrafimostafa:Forground-App-Checker:1.0.0")
}

Use a release tag or commit hash as the version.

Groovy

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.ashrafimostafa:Forground-App-Checker:1.0.0'
}

Local module

implementation(project(":foregroundappchecker"))

---

Quick start

val checker = ForegroundAppChecker(context)

if (!checker.hasUsageStatsPermission()) {
    checker.openUsageAccessSettings()
} else {
    checker.start { packageName ->
        // e.g. "com.android.chrome"
        Log.d("Foreground", packageName)
    }
}

// When finished:
checker.stop()
// Or fully release the internal scope:
checker.release()

Custom poll interval

val checker = ForegroundAppChecker(context, intervalMs = 500L)

One-shot query

lifecycleScope.launch {
    val pkg = checker.getCurrentForegroundPackage()
}

Flow API

lifecycleScope.launch {
    checker.observeForegroundApp().collect { packageName ->
        // handle packageName
    }
}

---

Sample app

This repository includes a sample module that demonstrates:

1. Granting Usage access
2. Starting / stopping monitoring
3. Showing the live foreground package name

Open the project in Android Studio and run the sample configuration on a device or emulator.

---

How it works

ForegroundAppChecker uses UsageStatsManager (available since API 21):

1. Prefer recent UsageEvents (MOVE_TO_FOREGROUND / ACTIVITY_RESUMED)
2. Fall back to queryUsageStats and pick the package with the latest lastTimeUsed

Polling runs on a background dispatcher; callbacks are delivered on the main thread.

---

Public API

API	Description
start { packageName -> }	Start monitoring; callback on change
stop()	Stop monitoring
release()	Cancel scope; instance is done
getCurrentForegroundPackage()	Suspend one-shot query
observeForegroundApp()	Cold Flow of package names
hasUsageStatsPermission()	Whether Usage access is granted
openUsageAccessSettings()	Open system Usage access screen

---

Project structure

ForegroundAppChecker/
├── foregroundappchecker/   # Android library (publishable AAR)
├── sample/                 # Demo application
├── README.md
└── LICENSE

---

Size

The library avoids AndroidX UI dependencies. Runtime dependency:

• org.jetbrains.kotlinx:kotlinx-coroutines-android

Keep ProGuard / R8 enabled in release apps; consumer-rules.pro keeps the public API.

---

Publishing checklist (maintainers)

1. Tag a release: git tag -a 1.0.0 -m "1.0.0" && git push origin 1.0.0
2. Open JitPack and wait for the build
3. Consumers depend on com.github.ashrafimostafa:Forground-App-Checker:1.0.0

---

Copyright

Copyright (c) 2026 Mostafa Ashrafi. All rights reserved.
Distributed under the MIT License — see LICENSE.