Wi-Fi 掃描總覽

您可以使用 WifiManager API 取得 可透過裝置顯示的 Wi-Fi 存取點。

Wi-Fi 掃描程序

掃描程序分為三個步驟：

1. 註冊廣播事件監聽器： SCAN_RESULTS_AVAILABLE_ACTION, 當系統完成掃描請求時，系統就會呼叫此方法 。如果是搭載 Android 10 (API 級別 29) 以上版本的裝置，這個 將會在裝置完整掃描 Wi-Fi 時，將 平台或其他應用程式應用程式可以被動聆聽所有掃描 透過廣播確保裝置完整播放

2. 使用以下電子郵件地址要求掃描： WifiManager.startScan()。 呼叫可能會失敗，請務必檢查方法的傳回狀態 ：

   • 由於短時間內掃描的掃描過多，掃描要求可能會受到限制。
   • 裝置處於閒置狀態，因此掃描功能已停用。
   • Wi-Fi 硬體回報掃描失敗。

3. 取得掃描結果： WifiManager.getScanResults()。 傳回的掃描結果是最近更新的結果， 如果您目前的掃描作業尚未完成或成功，則執行先前的掃描作業 這代表如果呼叫這個方法，可能會傳回較舊的掃描結果 才會收到成功 SCAN_RESULTS_AVAILABLE_ACTION 廣播。

以下程式碼提供實作這些步驟的範例：

KotlinJava

val wifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager

val wifiScanReceiver = object : BroadcastReceiver() {

  override fun onReceive(context: Context, intent: Intent) {
    val success = intent.getBooleanExtra(WifiManager.EXTRA_RESULTS_UPDATED, false)
    if (success) {
      scanSuccess()
    } else {
      scanFailure()
    }
  }
}

val intentFilter = IntentFilter()
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION)
context.registerReceiver(wifiScanReceiver, intentFilter)

val success = wifiManager.startScan()
if (!success) {
  // scan failure handling
  scanFailure()
}

....

private fun scanSuccess() {
  val results = wifiManager.scanResults
  ... use new scan results ...
}

private fun scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  val results = wifiManager.scanResults
  ... potentially use older scan results ...
}

WifiManager wifiManager = (WifiManager)
                   context.getSystemService(Context.WIFI_SERVICE);

BroadcastReceiver wifiScanReceiver = new BroadcastReceiver() {
  @Override
  public void onReceive(Context c, Intent intent) {
    boolean success = intent.getBooleanExtra(
                       WifiManager.EXTRA_RESULTS_UPDATED, false);
    if (success) {
      scanSuccess();
    } else {
      // scan failure handling
      scanFailure();
    }
  }
};

IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION);
context.registerReceiver(wifiScanReceiver, intentFilter);

boolean success = wifiManager.startScan();
if (!success) {
  // scan failure handling
  scanFailure();
}

....

private void scanSuccess() {
  List<ScanResult> results = wifiManager.getScanResults();
  ... use new scan results ...
}

private void scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  List<ScanResult> results = wifiManager.getScanResults();
  ... potentially use older scan results ...
}

限制

Android 8.0 (API 級別 26) 推出了權限和 Wi-Fi 掃描頻率的限制。

為了改善網路效能、安全性和電池續航力，Android 9 (API 級別 28) 加強了權限要求，並進一步限制 Wi-Fi 掃描的頻率。

權限

注意： 以下每個提及位置存取權的部分， 位置收集邏輯，請注意，當您的應用程式在 背景，位置資訊存取權則應為 以及應用程式的核心功能 向使用者揭露。

Android 8.0 和 Android 8.1：

如要成功呼叫 WifiManager.getScanResults()，您必須具備下列任一權限：

• ACCESS_FINE_LOCATION
• ACCESS_COARSE_LOCATION
• CHANGE_WIFI_STATE

如果發出呼叫的應用程式並未擁有上述任何權限，呼叫就會失敗，並顯示 SecurityException。

或者，在搭載 Android 8.0 (API 級別 26) 以上版本的裝置上，您也可以 請使用 CompanionDeviceManager 可以代表您的應用程式掃描鄰近的隨附裝置 要求位置存取權。如要進一步瞭解這個選項，請參閱「配件裝置配對」。

Android 9：

如要成功呼叫 WifiManager.startScan()，必須符合下列「所有」條件：

• 您的應用程式含有 ACCESS_FINE_LOCATION 或 ACCESS_COARSE_LOCATION 權限。
• 您的應用程式具有 CHANGE_WIFI_STATE 權限。
• 裝置上已啟用定位服務 (位於「設定」>「位置資訊」下方)。

Android 10 (API 級別 29) 以上版本：

如要成功呼叫 WifiManager.startScan()，必須符合下列「所有」條件：

• 如果應用程式指定的是 Android 10 (API 級別 29) SDK 以上版本，則應用程式具有 ACCESS_FINE_LOCATION 權限。
• 如果應用程式指定的 SDK 版本低於 Android 10 (API 級別 29)，則應用程式具有 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION 權限。
• 您的應用程式含有 CHANGE_WIFI_STATE 權限。
• 裝置已啟用定位服務 (在「設定」之下 > Location)。

如要成功呼叫 WifiManager.getScanResults()，請確認已滿足下列所有條件：

• 如果應用程式指定 Android 10 (API 級別 29) SDK 以上版本，則會具備 ACCESS_FINE_LOCATION 權限。
• 如果應用程式指定的 SDK 版本低於 Android 10 (API 級別 29)，則應用程式會具備 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION 權限。
• 您的應用程式含有 ACCESS_WIFI_STATE 權限。
• 裝置已啟用定位服務 (在「設定」之下 > Location)。

如果發出呼叫的應用程式不符合上述所有規定，則呼叫會失敗，並顯示 SecurityException。

節流

以下限制適用於使用 WifiManager.startScan() 的掃描頻率。

Android 8.0 和 Android 8.1：

每個背景應用程式可在 30 分鐘內掃描一次。

Android 9：

每個前景應用程式可以在 2 分鐘內掃描四次。這樣一來，您就能在短時間內執行大量掃描作業。

所有背景應用程式合併的單位可在 30 分鐘內掃描一次。

Android 10 以上版本：

適用 Android 9 的相同節流限制。我們新增了一個開發人員選項，可切換關閉節流功能以進行本機測試 (位於「開發人員選項」>「網路」>「Wi-Fi 掃描節流」下)。