Wi-Fi 位置：範圍涵蓋即時文字訊息

您可以使用 Wi-Fi RTT (封包往返時間) API 提供的 Wi-Fi 定位功能，測量與附近支援 RTT 的 Wi-Fi 存取點和對等 Wi-Fi Aware 裝置之間的距離。

如果測量與三個以上存取點的距離，可以使用多邊定位演算法，估算最符合這些測量結果的裝置位置。結果通常準確到 1 至 2 公尺內。

有了這項精確度，您就能開發精細的適地性服務，例如室內導航、明確的語音控制 (例如「開啟這盞燈」) 和適地性資訊 (例如「這項產品是否有特價優惠？」)。

要求裝置不需要連線至存取點，即可使用 Wi-Fi RTT 測量距離。為維護隱私，只有提出要求的裝置才能判斷與存取點的距離，存取點不會取得這項資訊。前景應用程式的 Wi-Fi RTT 作業不受限制，但背景應用程式會受到限制。

Wi-Fi RTT 和相關的精確時間測量 (FTM) 功能是由 IEEE 802.11-2016 標準指定。Wi-Fi RTT 需要 FTM 提供的精確時間測量，因為它會測量封包在兩個裝置之間來回所需的時間，並將該時間乘以光速，來計算兩個裝置之間的距離。

Android 15 (API 級別 35) 支援 IEEE 802.11az 非觸發式 (NTB) 測距。

Android 版本之間的導入差異

Wi-Fi RTT 是在 Android 9 (API 級別 28) 中推出。使用這項通訊協定，透過多邊定位技術判斷搭載 Android 9 的裝置位置時，您必須在應用程式中存取預先確定的存取點 (AP) 位置資料。您可以自行決定如何儲存及擷取這項資料。

在搭載 Android 10 (API 級別 29) 以上版本的裝置上，AP 位置資料可以表示為 ResponderLocation 物件，其中包含經度、緯度和高度。對於支援位置設定資訊/位置公民報告 (LCI/LCR 資料) 的 Wi-Fi RTT AP，通訊協定會在測距程序中傳回 ResponderLocation 物件。

這項功能可讓應用程式直接向 AP 查詢位置，不必預先儲存這項資訊。因此，即使 AP 先前未知 (例如使用者進入新建築物)，應用程式也能找到 AP 並判斷其位置。

搭載 Android 15 (API 級別 35) 以上版本的裝置，支援 IEEE 802.11az NTB 測距功能。也就是說，如果裝置支援 IEEE 802.11az NTB 啟動器模式 (以 WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR 表示)，應用程式就能透過單一測距要求，同時找到支援 IEEE 802.11mc 和 IEEE 802.11az 的 AP。RangingResult API 已擴充，可提供測距測量間隔的最小值和最大值資訊，讓應用程式控制確切間隔。

需求條件

• 提出測距要求的裝置硬體必須實作 802.11-2016 FTM 標準或 802.11az 標準 (非觸發式測距)。
• 提出測距要求的裝置必須搭載 Android 9 (API 級別 28) 以上版本。搭載 Android 15 (API 級別 35) 以上版本的裝置，會啟用 IEEE 802.11az 非觸發式測距功能。
• 發出測距要求的裝置必須啟用定位服務，並開啟 Wi-Fi 掃描功能 (依序前往「設定」>「位置」)。
• 如果發出測距要求的應用程式指定 Android 13 (API 級別 33) 以上版本，則必須具備 NEARBY_WIFI_DEVICES 權限。如果這類應用程式指定較舊的 Android 版本，則必須改為具備 ACCESS_FINE_LOCATION 權限。
• 應用程式必須在顯示或前景服務中查詢存取點範圍。應用程式無法在背景存取位置資訊。
• 存取點必須採用 IEEE 802.11-2016 FTM 標準或 IEEE 802.11az 標準 (非觸發式測距)。

設定

如要設定應用程式使用 Wi-Fi RTT，請按照下列步驟操作。

1. 要求權限

在應用程式資訊清單中要求下列權限：

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<!-- If your app targets Android 13 (API level 33)
     or higher, you must declare the NEARBY_WIFI_DEVICES permission. -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
                 <!-- If your app derives location information from Wi-Fi APIs,
                      don't include the "usesPermissionFlags" attribute. -->
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 <!-- If any feature in your app relies on precise location
                      information, don't include the "maxSdkVersion"
                      attribute. -->
                 android:maxSdkVersion="32" />

NEARBY_WIFI_DEVICES 和 ACCESS_FINE_LOCATION 權限屬於危險權限，因此每當使用者想執行 RTT 掃描作業時，您都必須在執行階段要求這些權限。如果尚未取得權限，應用程式必須向使用者要求權限。如要進一步瞭解執行階段權限，請參閱「要求應用程式權限」。

2. 確認裝置是否支援 Wi-Fi RTT

如要檢查裝置是否支援 Wi-Fi RTT，請使用 PackageManager API：

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_RTT);

3. 檢查 Wi-Fi RTT 是否可用

裝置上可能有 Wi-Fi RTT，但由於使用者已停用 Wi-Fi，因此可能無法使用。視硬體和韌體功能而定，如果使用 SoftAP 或網路共用，部分裝置可能不支援 Wi-Fi RTT。如要確認 Wi-Fi RTT 是否可用，請呼叫 isAvailable()。

Wi-Fi RTT 的可用性可能隨時變動。應用程式應註冊 BroadcastReceiver，以便在可用性變更時接收 ACTION_WIFI_RTT_STATE_CHANGED。應用程式收到廣播意圖時，應檢查目前的可用性狀態，並據此調整行為。

例如：

val filter = IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED)
val myReceiver = object: BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (wifiRttManager.isAvailable) {
            …
        } else {
            …
        }
    }
}
context.registerReceiver(myReceiver, filter)

IntentFilter filter =
    new IntentFilter(WifiRttManager.ACTION_WIFI_RTT_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (wifiRttManager.isAvailable()) {
            …
        } else {
            …
        }
    }
};
context.registerReceiver(myReceiver, filter);

詳情請參閱「廣播」。

建立測距要求

測距要求 (RangingRequest) 的建立方式是指定要求範圍的 AP 或 Wi-Fi Aware 對等點清單。您可以在單一測距要求中指定多個存取點或 Wi-Fi Aware 對等互連裝置，系統會測量並傳回與所有裝置的距離。

舉例來說，要求可以使用 addAccessPoint() 方法，指定要測量距離的存取點：

val req: RangingRequest = RangingRequest.Builder().run {
    addAccessPoint(ap1ScanResult)
    addAccessPoint(ap2ScanResult)
    build()
}

RangingRequest.Builder builder = new RangingRequest.Builder();
builder.addAccessPoint(ap1ScanResult);
builder.addAccessPoint(ap2ScanResult);

RangingRequest req = builder.build();

存取點是由其 ScanResult 物件識別，可透過呼叫 WifiManager.getScanResults() 取得。您可以使用 addAccessPoints(List<ScanResult>) 批次新增多個存取點。

ScanResult 物件可同時包含支援 IEEE 802.11mc (is80211mcResponder()) 和 IEEE 802.11az 非觸發式測距 (is80211azNtbResponder()) 的 AP。支援 IEEE 802.11az NTB 測距的裝置會根據 AP 的功能執行 802.11mc 或 802.11az 測距，如果 AP 同時支援兩者，則預設為 802.11az。不支援 IEEE 802.11az 的裝置會使用 IEEE 802.11mc 通訊協定執行所有測距。

同樣地，測距要求可以使用 addWifiAwarePeer(MacAddress peer) 和 addWifiAwarePeer(PeerHandle peer) 方法，分別使用 MAC 位址或 PeerHandle 新增 Wi-Fi Aware 對等互連。如要進一步瞭解如何探索 Wi-Fi Aware 對等互連，請參閱 Wi-Fi Aware 說明文件。

要求測距

應用程式會使用 WifiRttManager.startRanging() 方法發出測距要求，並提供下列項目：指定作業的 RangingRequest、指定回呼內容的 Executor，以及接收結果的 RangingResultCallback。

例如：

val mgr = context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE) as WifiRttManager
val request: RangingRequest = myRequest
mgr.startRanging(request, executor, object : RangingResultCallback() {

    override fun onRangingResults(results: List<RangingResult>) { … }

    override fun onRangingFailure(code: Int) { … }
})

WifiRttManager mgr =
      (WifiRttManager) Context.getSystemService(Context.WIFI_RTT_RANGING_SERVICE);

RangingRequest request ...;
mgr.startRanging(request, executor, new RangingResultCallback() {

  @Override
  public void onRangingFailure(int code) { … }

  @Override
  public void onRangingResults(List<RangingResult> results) { … }
});

測距作業會以非同步方式執行，測距結果則會透過 RangingResultCallback 的其中一個回呼傳回：

• 如果整個測距作業失敗，系統會觸發 onRangingFailure 回呼，並顯示 RangingResultCallback 中所述的狀態碼。如果服務無法在當下執行測距作業，就可能發生這類失敗，例如 Wi-Fi 停用、應用程式要求過多測距作業而受到限制，或權限問題。
• 測距作業完成後，系統會觸發 onRangingResults 回呼，並傳回與要求清單相符的結果清單，每個要求都會有一項結果。結果的順序不一定與要求的順序相符。請注意，測距作業可能會完成，但每項結果仍可能指出特定測量失敗。

解讀測距結果

onRangingResults 回呼傳回的每項結果都是由 RangingResult 物件指定。針對每項要求，請執行下列操作。

1. 找出要求

根據建立 RangingRequest 時提供的資訊找出要求：最常見的是 ScanResult 中提供的 MAC 位址，用於識別存取點。您可以使用 getMacAddress() 方法，從測距結果取得 MAC 位址。

測距結果清單的順序可能與測距要求中指定的對等點 (存取點) 不同，因此您應使用 MAC 位址來識別對等點，而非結果順序。

2. 判斷各項測量是否成功

如要判斷測量是否成功，請使用 getStatus() 方法。STATUS_SUCCESS 以外的任何值都表示失敗。失敗表示這項結果的所有其他欄位 (上述要求識別資訊除外) 無效，且對應的 get* 方法會失敗，並顯示 IllegalStateException 例外狀況。

3. 取得每次成功測量的結果

對於每次成功的測量 (RangingResult)，您可以使用對應的 get 方法擷取結果值：

• 距離 (以公釐為單位) 和測量值的標準差：

  getDistanceMm()

  getDistanceStdDevMm()

• 用於測量的封包 RSSI：

  getRssi()

• 測量時間 (以毫秒為單位，表示自啟動後的時間)：

  getRangingTimestampMillis()

• 嘗試測量的次數和成功測量的次數 (距離測量結果的依據)：

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• 用戶端裝置在 11az NTB 測量之間必須等待的最短和最長時間：

  getMinTimeBetweenNtbMeasurementsMicros() 和 getMaxTimeBetweenNtbMeasurementsMicros() 會傳回最短和最長時間。如果在最短時間經過前要求下一次測距測量，API 會傳回快取的測距結果。如果超過時間上限後才要求下一次測距，API 會終止非觸發測距工作階段，並與回應站協商新的測距工作階段。請避免要求新的測距工作階段，因為這會增加測距測量時間的負擔。如要充分利用 802.11az 非觸發式測距效率，請在先前 RangingResult 測量中指定的最小和最大測量時間之間，觸發下一個測距要求。

• 回應端和發起端站在 IEEE 802.11az NTB 結果的前導提示中，使用的長訓練欄位 (LTF) 重複次數：

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• 發起端基地台用於 IEEE 802.11az NTB 結果的傳輸和接收空間時間串流 (STS) 數量：

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

支援 Wi-Fi RTT 的 Android 裝置

下表列出部分支援 Wi-Fi RTT 的手機、存取點，以及零售、倉儲和配送中心裝置。這些只是部分範例，歡迎與我們聯絡，在此列出支援 RTT 的產品。

存取點

手機

零售、倉儲和配送中心裝置