廣播總覽

Android 應用程式會向 Android 系統和其他 Android 應用程式傳送及接收廣播訊息，類似於發布/訂閱設計模式。系統和應用程式通常會在特定事件發生時傳送廣播。舉例來說，Android 系統會在發生各種系統事件 (例如系統啟動或裝置充電) 時傳送廣播。應用程式也會傳送自訂廣播訊息，例如通知其他應用程式可能感興趣的內容 (例如新資料下載)。

應用程式可以註冊接收特定廣播訊息。傳送廣播訊息時，系統會自動將廣播訊息傳送至已訂閱該特定類型廣播訊息的應用程式。

一般來說，廣播訊息可用於跨應用程式和非一般使用者流程的通訊系統。不過，請務必小心，不要濫用回應廣播和在背景執行工作，這可能會導致系統效能變慢。

關於系統廣播訊息

系統會在發生各種系統事件時自動傳送廣播，例如系統切換飛航模式時。所有已訂閱的應用程式都會收到這些廣播。

Intent 物件會包裝廣播訊息。action 字串會識別發生的事件，例如 android.intent.action.AIRPLANE_MODE。意圖也可能包含額外資訊，並整合至額外欄位。舉例來說，飛航模式意圖包含布林值額外資料，可指出是否已開啟飛航模式。

如要進一步瞭解如何讀取意圖，以及從意圖取得動作字串，請參閱「意圖和意圖篩選器」。

系統廣播動作

如需系統廣播動作的完整清單，請參閱 Android SDK 中的 BROADCAST_ACTIONS.TXT 檔案。每個廣播動作都有相關聯的常數欄位。例如，常數 ACTION_AIRPLANE_MODE_CHANGED 的值為 android.intent.action.AIRPLANE_MODE。每個廣播動作的說明文件皆可在相關聯的常數欄位中找到。

系統廣播變更

隨著 Android 平台的演進，系統會定期變更系統廣播的行為。請注意下列變更，以便支援所有 Android 版本。

Android 14

當應用程式處於快取狀態時，系統會針對系統健康狀態最佳化廣播傳送作業。舉例來說，當應用程式處於快取狀態時，系統會延遲較不重要的系統廣播訊息，例如 ACTION_SCREEN_ON。應用程式從快取狀態進入有效程序生命週期後，系統會傳送所有延遲廣播訊息。

在資訊清單中宣告的重要廣播訊息會暫時將應用程式從快取狀態移除，以便進行傳送。

Android 9

自 Android 9 (API 級別 28) 起，NETWORK_STATE_CHANGED_ACTION 廣播不會收到使用者位置或可識別個人身分的資料。

如果應用程式安裝在搭載 Android 9.0 (API 級別 28) 以上版本的裝置上，系統就不會在 Wi-Fi 廣播中加入 SSID、BSSID、連線資訊或掃描結果。如要取得這項資訊，請改為呼叫 getConnectionInfo()。

Android 8.0

從 Android 8.0 (API 級別 26) 開始，系統會對清單宣告的接收器施加額外限制。

如果應用程式指定 Android 8.0 以上版本，您就無法使用資訊清單為大部分隱含廣播 (未明確指定應用程式的廣播) 宣告接收器。當使用者正在積極使用應用程式時，您仍可使用已註冊內容的接收器。

Android 7.0

Android 7.0 (API 級別 24) 以上版本不會傳送下列系統廣播訊息：

此外，鎖定 Android 7.0 以上版本的應用程式必須使用 registerReceiver(BroadcastReceiver, IntentFilter) 註冊 CONNECTIVITY_ACTION 廣播訊息。在資訊清單中宣告接收器無法運作。

接收廣播

應用程式可以透過兩種方式接收廣播訊息：透過已註冊的內容相關接收器和資訊清單宣告的接收器。

註冊使用情境的接收器

只要註冊使用情境的接收器註冊情境有效，就會收到廣播訊息。通常是在呼叫 registerReceiver 和 unregisterReceiver 之間。當系統刪除對應的註冊內容時，註冊內容也會失效。舉例來說，如果您在 Activity 情境中註冊，只要活動仍處於啟用狀態，您就會收到廣播。如果您使用應用程式情境註冊，只要應用程式執行，您就會收到廣播訊息。

如要註冊含有內容的接收器，請執行下列步驟：

  1. 在應用程式的模組層級建構檔案中，加入 AndroidX 核心資料庫的 1.9.0 以上版本：

    Groovy

    dependencies {
    def core_version = "1.13.1"

    // Java language implementation
    implementation "androidx.core:core:$core_version"
    // Kotlin
    implementation "androidx.core:core-ktx:$core_version"

    // To use RoleManagerCompat
    implementation "androidx.core:core-role:1.0.0"

    // To use the Animator APIs
    implementation "androidx.core:core-animation:1.0.0"
    // To test the Animator APIs
    androidTestImplementation "androidx.core:core-animation-testing:1.0.0"

    // Optional - To enable APIs that query the performance characteristics of GMS devices.
    implementation "androidx.core:core-performance:1.0.0"

    // Optional - to use ShortcutManagerCompat to donate shortcuts to be used by Google
    implementation "androidx.core:core-google-shortcuts:1.1.0"

    // Optional - to support backwards compatibility of RemoteViews
    implementation "androidx.core:core-remoteviews:1.1.0"

    // Optional - APIs for SplashScreen, including compatibility helpers on devices prior Android 12
    implementation "androidx.core:core-splashscreen:1.2.0-alpha02"
}

    Kotlin

    dependencies {
    val core_version = "1.13.1"

    // Java language implementation
    implementation("androidx.core:core:$core_version")
    // Kotlin
    implementation("androidx.core:core-ktx:$core_version")

    // To use RoleManagerCompat
    implementation("androidx.core:core-role:1.0.0")

    // To use the Animator APIs
    implementation("androidx.core:core-animation:1.0.0")
    // To test the Animator APIs
    androidTestImplementation("androidx.core:core-animation-testing:1.0.0")

    // Optional - To enable APIs that query the performance characteristics of GMS devices.
    implementation("androidx.core:core-performance:1.0.0")

    // Optional - to use ShortcutManagerCompat to donate shortcuts to be used by Google
    implementation("androidx.core:core-google-shortcuts:1.1.0")

    // Optional - to support backwards compatibility of RemoteViews
    implementation("androidx.core:core-remoteviews:1.1.0")

    // Optional - APIs for SplashScreen, including compatibility helpers on devices prior Android 12
    implementation("androidx.core:core-splashscreen:1.2.0-alpha02")
}

  2. 建立 BroadcastReceiver 的例項：

    Kotlin

    val myBroadcastReceiver = MyBroadcastReceiver()

    Java

    MyBroadcastReceiver myBroadcastReceiver = new MyBroadcastReceiver();

  3. 建立 IntentFilter 的例項：

    Kotlin

    val filter = IntentFilter("com.example.snippets.ACTION_UPDATE_DATA")

    Java

    IntentFilter filter = new IntentFilter("com.example.snippets.ACTION_UPDATE_DATA");

  4. 選擇是否要匯出廣播接收器，並讓裝置上的其他應用程式可見。如果這個接收器會監聽系統或其他應用程式 (包括您擁有的其他應用程式) 傳送的廣播訊息，請使用 RECEIVER_EXPORTED 標記。如果這個接收器只會監聽應用程式傳送的廣播訊息，請使用 RECEIVER_NOT_EXPORTED 旗標。

    Kotlin

    val listenToBroadcastsFromOtherApps = false
val receiverFlags = if (listenToBroadcastsFromOtherApps) {
    ContextCompat.RECEIVER_EXPORTED
} else {
    ContextCompat.RECEIVER_NOT_EXPORTED
}
    BroadcastReceiverSnippets.kt

    Java

    boolean listenToBroadcastsFromOtherApps = false;
int receiverFlags = listenToBroadcastsFromOtherApps
        ? ContextCompat.RECEIVER_EXPORTED
        : ContextCompat.RECEIVER_NOT_EXPORTED;
    BroadcastReceiverJavaSnippets.java

  5. 呼叫 registerReceiver() 註冊接收器：

    Kotlin

    ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, receiverFlags)

    Java

    ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, receiverFlags);

  6. 如要停止接收廣播，請呼叫 unregisterReceiver(android.content.BroadcastReceiver)。請務必在不再需要接收器或情境不再有效時取消註冊。

取消註冊廣播接收器

廣播接收器註冊時，會保留您註冊時使用的 Context 參照。如果接收器的註冊範圍超出 Context 生命週期範圍，這可能會導致發生漏洞。舉例來說，如果您在活動範圍中註冊接收器，但在系統刪除活動時忘記取消註冊，就可能發生這種情況。因此，請務必註銷廣播接收器。

Kotlin

class MyActivity : ComponentActivity() {
    private val myBroadcastReceiver = MyBroadcastReceiver()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        ContextCompat.registerReceiver(this, myBroadcastReceiver, filter, receiverFlags)
        setContent { MyApp() }
    }

    override fun onDestroy() {
        super.onDestroy()
        // When you forget to unregister your receiver here, you're causing a leak!
        this.unregisterReceiver(myBroadcastReceiver)
    }
}
BroadcastReceiverSnippets.kt

Java

class MyActivity extends ComponentActivity {
    MyBroadcastReceiver myBroadcastReceiver;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...
        ContextCompat.registerReceiver(this, myBroadcastReceiver, filter, receiverFlags);
        // Set content
    }
}
BroadcastReceiverJavaSnippets.java

在最小範圍內註冊接收器

只有在您實際感興趣的情況下，才應註冊廣播接收器。請選擇最小的可能接收器範圍：

  • LifecycleResumeEffect 或活動 onResume/onPause 生命週期方法：廣播接收器只會在應用程式處於已暫停狀態時收到更新。
  • LifecycleStartEffect 或活動 onStart/onStop 生命週期方法：廣播接收器只會在應用程式處於已暫停狀態時收到更新。
  • DisposableEffect：廣播接收器只會在可組合函式位於組合樹狀結構時接收更新。這個範圍不會附加至活動生命週期範圍。建議您在應用程式內容中註冊接收器。這是因為可組合項在理論上可能會存活超過活動生命週期範圍，並導致活動發生漏洞。
  • 活動 onCreate/onDestroy：廣播接收器會在活動處於已建立狀態時接收更新。請務必在 onDestroy() 中取消註冊，而非在 onSaveInstanceState(Bundle) 中取消註冊，因為後者可能不會呼叫。
  • 自訂範圍：舉例來說，您可以在 ViewModel 範圍中註冊接收器，讓接收器在活動重建後仍可運作。請務必使用應用程式內容註冊接收器，因為接收器的生命週期範圍可能會比活動長，並導致活動發生漏洞。

建立有狀態和無狀態的可組合函式

Compose 提供有狀態和無狀態的可組合函式。在可組合項中註冊或取消註冊廣播接收器，會使其具有狀態。可組合函式並非確定性函式，無法在傳遞相同參數時算繪相同內容。內部狀態可根據對已註冊廣播接收器的呼叫而變更。

根據 Compose 的最佳做法，建議您將可組合項分割為有狀態和無狀態版本。因此，建議您將廣播接收器的建立作業從可組合項中提升，使其無狀態：

@Composable
fun MyStatefulScreen() {
    val myBroadcastReceiver = remember { MyBroadcastReceiver() }
    val context = LocalContext.current
    LifecycleStartEffect(true) {
        // ...
        ContextCompat.registerReceiver(context, myBroadcastReceiver, filter, flags)
        onStopOrDispose { context.unregisterReceiver(myBroadcastReceiver) }
    }
    MyStatelessScreen()
}

@Composable
fun MyStatelessScreen() {
    // Implement your screen
}
BroadcastReceiverSnippets.kt

資訊清單宣告的接收器

如果您在資訊清單中宣告廣播接收器，系統會在廣播訊息傳送時啟動應用程式。如果應用程式尚未執行，系統會啟動應用程式。

如要在資訊清單中宣告廣播接收器，請執行下列步驟：

  1. 在應用程式資訊清單中指定 <receiver> 元素。

    <!-- If this receiver listens for broadcasts sent from the system or from
     other apps, even other apps that you own, set android:exported to "true". -->
<receiver android:name=".MyBroadcastReceiver" android:exported="false">
    <intent-filter>
        <action android:name="com.example.snippets.ACTION_UPDATE_DATA" />
    </intent-filter>
</receiver>
    AndroidManifest.xml

    意圖篩選器會指定接收器訂閱的廣播動作。

  2. 建立 BroadcastReceiver 子類別，並實作 onReceive(Context, Intent)。以下範例中的廣播接收器會記錄並顯示廣播內容：

    Kotlin

    class MyBroadcastReceiver : BroadcastReceiver() {

    @Inject
    lateinit var dataRepository: DataRepository

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == "com.example.snippets.ACTION_UPDATE_DATA") {
            val data = intent.getStringExtra("com.example.snippets.DATA") ?: "No data"
            // Do something with the data, for example send it to a data repository:
            dataRepository.updateData(data)
        }
    }
}
    BroadcastReceiverSnippets.kt

    Java

    public static class MyBroadcastReceiver extends BroadcastReceiver {

    @Inject
    DataRepository dataRepository;

    @Override
    public void onReceive(Context context, Intent intent) {
        if (Objects.equals(intent.getAction(), "com.example.snippets.ACTION_UPDATE_DATA")) {
            String data = intent.getStringExtra("com.example.snippets.DATA");
            // Do something with the data, for example send it to a data repository:
            if (data != null) { dataRepository.updateData(data); }
        }
    }
}
    BroadcastReceiverJavaSnippets.java

系統套件管理工具會在應用程式安裝時註冊接收器。接收器隨後會成為應用程式的個別進入點，也就是說，如果應用程式未執行，系統可以啟動應用程式並傳送廣播。

系統會建立新的 BroadcastReceiver 元件物件，用於處理收到的每個廣播。這個物件只在呼叫 onReceive(Context, Intent) 的期間有效。程式碼從這個方法傳回後，系統會認為元件不再處於活動狀態。

對程序狀態的影響

BroadcastReceiver 是否運作會影響其所含程序，進而影響系統終止的可能性。前景程序會執行接收器的 onReceive() 方法。系統會執行該程序，除非記憶體壓力極大。

系統會在 onReceive() 後停用 BroadcastReceiver。接收器的主機程序的重要性取決於其應用程式元件。如果該程序只代管資訊清單宣告的接收器，系統可能會在 onReceive() 後終止該程序，為其他更重要的程序釋出資源。這通常是使用者從未或最近未與之互動的應用程式。

因此，廣播接收器不應啟動長時間執行的背景執行緒。系統可以在 onReceive() 之後的任何時間停止程序，以便回收記憶體，並終止已建立的執行緒。為確保程序持續運作，請使用 JobScheduler 從接收器排程 JobService，讓系統知道程序仍在運作。詳情請參閱「背景工作總覽」。

傳送廣播

Android 提供兩種方式，讓應用程式傳送廣播：

  • sendOrderedBroadcast(Intent, String) 方法會一次將廣播訊息傳送給一個接收器。由於每個接收器會按順序執行，因此可將結果傳播至下一個接收器。也可以完全中止廣播，以免傳送至其他接收器。您可以控制接收器執行的順序。如要這麼做，請使用相符意圖篩選器的 android:priority 屬性。優先順序相同的接收器會以任意順序執行。
  • sendBroadcast(Intent) 方法會以未定順序將廣播訊息傳送至所有接收器。這稱為「一般廣播」。這麼做雖然效率較高，但接收器就無法讀取其他接收器的結果、傳播從廣播接收的資料，或中止廣播。

以下程式碼片段說明如何建立意圖並呼叫 sendBroadcast(Intent)，藉此傳送廣播。

Kotlin

val intent = Intent("com.example.snippets.ACTION_UPDATE_DATA").apply {
    putExtra("com.example.snippets.DATA", newData)
    setPackage("com.example.snippets")
}
context.sendBroadcast(intent)
BroadcastReceiverSnippets.kt

Java

Intent intent = new Intent("com.example.snippets.ACTION_UPDATE_DATA");
intent.putExtra("com.example.snippets.DATA", newData);
intent.setPackage("com.example.snippets");
context.sendBroadcast(intent);
BroadcastReceiverJavaSnippets.java

廣播訊息會包裝在 Intent 物件中。意圖的 action 字串必須提供應用程式的 Java 套件名稱語法，並以唯一方式識別廣播事件。您可以使用 putExtra(String, Bundle) 將其他資訊附加至意圖。您也可以在意圖上呼叫 setPackage(String)，將廣播訊息限制在同一個機構中的一組應用程式。

限制具有權限的廣播

您可以使用權限，將廣播限制在擁有特定權限的應用程式組合中。您可以對廣播訊息的寄件者或收件者強制執行限制。

傳送含有權限的廣播訊息

呼叫 sendBroadcast(Intent, String) 或 sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 時，您可以指定權限參數。只有在資訊清單中使用 <uses-permission> 標記要求該權限的接收器，才能接收廣播訊息。如果權限屬於危險類別，您必須先授予權限，接收器才能接收廣播。例如，下列程式碼會傳送具有權限的廣播：

Kotlin

context.sendBroadcast(intent, android.Manifest.permission.ACCESS_COARSE_LOCATION)

Java

context.sendBroadcast(intent, android.Manifest.permission.ACCESS_COARSE_LOCATION);

如要接收廣播訊息，接收應用程式必須要求以下權限：

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

您可以指定現有的系統權限 (例如 BLUETOOTH_CONNECT)，或是使用 <permission> 元素定義自訂權限。如要進一步瞭解權限和一般安全性，請參閱「系統權限」。

透過權限接收廣播訊息

如果您在註冊廣播接收器時指定權限參數 (使用 registerReceiver(BroadcastReceiver, IntentFilter, String, Handler) 或資訊清單中的 <receiver> 標記)，則只有在資訊清單中使用 <uses-permission> 標記要求權限的廣播器，才能將意圖傳送至接收器。如果權限屬於危險類別，則必須同時授予播送者該權限。

舉例來說，假設接收應用程式含有以下資訊清單宣告的接收器：

<!-- If this receiver listens for broadcasts sent from the system or from
     other apps, even other apps that you own, set android:exported to "true". -->
<receiver
    android:name=".MyBroadcastReceiverWithPermission"
    android:permission="android.permission.ACCESS_COARSE_LOCATION"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.snippets.ACTION_UPDATE_DATA" />
    </intent-filter>
</receiver>
AndroidManifest.xml

或者，接收應用程式具有以下已註冊使用情境的接收器：

Kotlin

ContextCompat.registerReceiver(
    context, myBroadcastReceiver, filter,
    android.Manifest.permission.ACCESS_COARSE_LOCATION,
    null, // scheduler that defines thread, null means run on main thread
    receiverFlags
)
BroadcastReceiverSnippets.kt

Java

ContextCompat.registerReceiver(
        context, myBroadcastReceiver, filter,
        android.Manifest.permission.ACCESS_COARSE_LOCATION,
        null, // scheduler that defines thread, null means run on main thread
        receiverFlags
);
BroadcastReceiverJavaSnippets.java

接著，為了能夠向這些接收端傳送廣播，傳送端應用程式必須要求以下權限：

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

安全性考量

以下是傳送及接收廣播時的安全性考量事項：

  • 如果許多應用程式在其資訊清單中註冊接收相同的廣播，可能會導致系統啟動許多應用程式，進而對裝置效能和使用者體驗造成重大影響。為避免這種情況，請改用內容註冊，而非資訊清單宣告。有時，Android 系統本身會強制使用已註冊使用情境的接收器。舉例來說，CONNECTIVITY_ACTION 廣播訊息只會傳送至已註冊情境的接收器。

  • 請勿使用隱含意圖廣播機密資訊。只要應用程式註冊接收廣播，就能讀取這項資訊。你可以透過三種方式控管誰可以接收你的廣播：

    • 您可以在傳送廣播時指定權限。
    • 在 Android 4.0 (API 級別 14) 以上版本中，您可以在傳送廣播時使用 setPackage(String) 指定套件。系統會將廣播限制在與套件相符的應用程式組合中。

  • 註冊接收器後，任何應用程式都能向應用程式的接收器傳送可能含有惡意的廣播訊息。您可以透過以下幾種方式限制應用程式收到的廣播：

    • 您可以在註冊廣播接收器時指定權限。
    • 針對資訊清單宣告的接收器，您可以在資訊清單中將 android:exported 屬性設為「false」。接收器不會接收來自應用程式以外來源的廣播。

  • 廣播動作的命名空間是全域性質。請確認動作名稱和其他字串是使用您擁有的命名空間編寫。否則可能會無意與其他應用程式發生衝突。

  • 由於接收器的 onReceive(Context, Intent) 方法會在主執行緒上執行，因此應快速執行並傳回。如果您需要執行長時間執行的工作，請小心產生執行緒或啟動背景服務，因為系統可以在 onReceive() 傳回後終止整個程序。詳情請參閱「對程序狀態的影響」。如要執行長時間執行的工作，建議您：

    • 在接收器的 onReceive() 方法中呼叫 goAsync()，並將 BroadcastReceiver.PendingResult 傳遞至背景執行緒。這樣一來，廣播就會在從 onReceive() 傳回後保持啟用狀態。不過，即使採用這種方法，系統仍會要求你盡快結束直播 (10 秒內)。但您可以將工作移至其他執行緒，避免主執行緒發生錯誤。
    • 使用 JobScheduler 安排工作。詳情請參閱「智慧型工作排程」。

  • 請勿從廣播接收器啟動活動，因為這會造成令人不悅的使用者體驗，特別是如果有多個接收器的話。建議您改為顯示通知。