Broadcast Receiver

Section 2 · BroadcastReceiver — Deep Dive

System signals, custom events, and the rules for surviving Android 8+ broadcast restrictions

What Is a BroadcastReceiver?

A BroadcastReceiver is an Android component that receives and reacts to Intent-based messages broadcast by the system or other apps. It is the listener side of Android’s publish-subscribe messaging bus.

Typical system broadcasts:

Action constant	When it fires
`Intent.ACTION_BOOT_COMPLETED`	After the device finishes booting
`Intent.ACTION_BATTERY_LOW`	Battery drops below the system threshold
`ConnectivityManager.CONNECTIVITY_ACTION`	Network connectivity changed (legacy)
`Intent.ACTION_AIRPLANE_MODE_CHANGED`	Airplane mode toggled
`Intent.ACTION_PACKAGE_ADDED`	A new app was installed
`Intent.ACTION_LOCALE_CHANGED`	System language changed
`Intent.ACTION_TIME_CHANGED` / `TIMEZONE_CHANGED`	Clock or timezone changed

Android Developers — Broadcasts overview

Static vs Dynamic Registration

Static (Manifest-Declared)

Declared in AndroidManifest.xml. The system can deliver the broadcast even when the app has never been launched.

<receiver
    android:name=".BootReceiver"
    android:exported="false">
    <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED" />
    </intent-filter>
</receiver>

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

class BootReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action != Intent.ACTION_BOOT_COMPLETED) return
        // Re-schedule WorkManager periodic jobs — they survive reboots
        // but their schedule entry does not; re-enqueue here
        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "hourly-sync",
            ExistingPeriodicWorkPolicy.KEEP,
            PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS).build()
        )
    }
}

Dynamic (Code-Registered)

Registered programmatically. Only receives broadcasts while registered; unregistering stops delivery.

class MainActivity : ComponentActivity() {

    private val downloadReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val id = intent.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID, -1L)
            handleDownloadComplete(id)
        }
    }

    override fun onStart() {
        super.onStart()
        val filter = IntentFilter(DownloadManager.ACTION_DOWNLOAD_COMPLETE)
        registerReceiver(downloadReceiver, filter)
    }

    override fun onStop() {
        super.onStop()
        unregisterReceiver(downloadReceiver)
    }
}

Android 13+ (API 33): registerReceiver requires an RECEIVER_EXPORTED or RECEIVER_NOT_EXPORTED flag for receivers that handle implicit broadcasts, to prevent third-party apps from sending unexpected intents.

// API 33+
registerReceiver(
    downloadReceiver,
    IntentFilter(DownloadManager.ACTION_DOWNLOAD_COMPLETE),
    Context.RECEIVER_NOT_EXPORTED   // only receive from our own app
)

The Android 8+ Implicit Broadcast Restrictions

Android 8.0 (API 26) introduced a major restriction: manifest-declared receivers can no longer receive most implicit broadcasts. If a broadcast is implicit (no specific target component), and you declare the receiver in the manifest, the system will not deliver it.

Android Developers — Background Execution Limits

Exceptions that still work with manifest receivers (explicit list in official docs):

Action	Why it’s exempt
`ACTION_BOOT_COMPLETED`	Device startup — no app is running to register dynamically
`ACTION_LOCKED_BOOT_COMPLETED`	Direct Boot completion
`ACTION_MY_PACKAGE_REPLACED`	App update — app isn’t running yet
`ACTION_LOCALE_CHANGED`	Language change — every app must update resources
`ACTION_TIMEZONE_CHANGED` / `TIME_CHANGED`	System time signals
`ACTION_NEW_OUTGOING_CALL`	Phone subsystem

For everything else (including CONNECTIVITY_ACTION), register dynamically while the app is running, or use WorkManager with a network constraint.

Approach	Works on API 26+?
Static manifest receiver for implicit broadcast	No — silently ignored
Dynamic receiver for implicit broadcast	Yes
WorkManager with `NetworkType.CONNECTED` constraint	Yes — preferred

`onReceive()` Threading Rules

onReceive() runs on the main thread with a 10-second deadline. Any ANR risk, I/O, or network call must be handed off immediately.

// WRONG — blocks the main thread
class BadReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val data = api.fetchSync()   // ANR risk
        db.insert(data)              // ANR risk
    }
}

Option 1: Delegate to WorkManager (preferred)

class ConnectivityReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        WorkManager.getInstance(context)
            .enqueueUniqueWork(
                "sync-on-connect",
                ExistingWorkPolicy.KEEP,
                OneTimeWorkRequestBuilder<SyncWorker>().build()
            )
    }
}

Option 2: `goAsync()` for short coroutine work

goAsync() extends the 10-second deadline by returning a PendingResult. You must call pendingResult.finish() when the work completes, or the system assumes you abandoned the broadcast.

class DataReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val pendingResult = goAsync()

        CoroutineScope(Dispatchers.IO).launch {
            try {
                processIntentData(intent)
            } finally {
                pendingResult.finish()   // MANDATORY — or the process may be killed
            }
        }
    }
}

goAsync() is appropriate for short bursts of work (a few seconds). For anything that could take more than a few seconds, use WorkManager.

Sending Custom Broadcasts

App-internal broadcasts (preferred)

For events within your own process, use explicit intents or — far better — a MutableSharedFlow / EventBus. They are fast, type-safe, and do not cross process boundaries.

App-internal broadcasts via `sendBroadcast`

// Sender
val intent = Intent("com.example.ACTION_SYNC_COMPLETE").apply {
    setPackage(packageName)   // make it explicit to your app only
    putExtra("count", 42)
}
context.sendBroadcast(intent)

// Receiver
class SyncCompleteReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val count = intent.getIntExtra("count", 0)
        // update UI or trigger next step
    }
}

Ordered broadcasts

sendOrderedBroadcast delivers the intent to receivers one at a time in priority order. Each receiver can pass a result to the next, or abort the chain entirely.

context.sendOrderedBroadcast(intent, null)

class PriorityReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        setResult(Activity.RESULT_OK, "processed", null)   // pass result to next
        // abortBroadcast()   // stop delivery to lower-priority receivers
    }
}

Security Considerations

Always set android:exported="false" for receivers that should only be triggered by your own app. If a receiver must accept intents from the system (e.g., BOOT_COMPLETED), it must be exported, but use permissions to gate it:

<receiver
    android:name=".SensitiveReceiver"
    android:exported="true"
    android:permission="com.example.CUSTOM_PERMISSION">
    <intent-filter>
        <action android:name="com.example.SECURE_ACTION" />
    </intent-filter>
</receiver>

Only senders who hold com.example.CUSTOM_PERMISSION can deliver intents to this receiver.

For dynamically registered receivers on Android 13+, always use RECEIVER_NOT_EXPORTED unless you deliberately want to accept broadcasts from other apps.