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

您可以使用 Wi-Fi RTT (Round-Trip-Time) API ，以便測量與附近支援 RTT 的 Wi-Fi 存取點和對等互連裝置之間的距離 Wi-Fi 感知裝置。

如果你測量到三個以上存取點之間的距離，可以使用 以便估算出最適合的裝置位置 測量資料結果通常會在 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 版本的實作差異

Android 9 (API 級別 28) 已導入 Wi-Fi RTT。使用這項通訊協定時 利用乘法功能與執行中的裝置，判斷裝置的位置 Android 9 版本必須具有預先指定存取點 (AP) 的存取權 應用程式中的資料資料的儲存及擷取方式完全由您決定。

在搭載 Android 10 (API 級別 29) 以上版本的裝置上，AP 位置資料可表示為 ResponderLocation 物件，其中包含緯度、經度和高度。針對符合下列條件的 Wi-Fi RTT AP 支援位置資訊設定資訊/位置公民報告 (LCI/LCR 資料)， 通訊協定會在工作階段期間傳回 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 即時文字訊息，請使用 PackageManager API：

Kotlin

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

Java

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

3. 檢查是否可使用 Wi-Fi 即時文字訊息

裝置可能支援 Wi-Fi RTT，但由於使用者已停用 Wi-Fi，因此可能無法使用。視硬體和韌體功能而定，部分裝置在使用 SoftAP 或 Tethering 時，可能不支援 Wi-Fi RTT。如要確認是否可使用 Wi-Fi 即時文字訊息功能，請撥打 isAvailable()。

系統隨時可能變更 Wi-Fi RTT 的可用性。您的應用程式應註冊 BroadcastReceiver 以便接收 ACTION_WIFI_RTT_STATE_CHANGED、 而是會在供應情形變更時傳送。應用程式收到廣播時 意圖，應用程式應檢查目前的可用性狀態，並調整其 進而影響使用者的行為

例如：

Kotlin

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)

Java

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() 方法，指定要測量距離的存取點：

Kotlin

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

Java

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()) 的無線基地台。支援 IEEE 802.11az NTB 測距功能的裝置會根據 AP 的功能執行 802.11mc 或 802.11az 測距功能，如果 AP 支援這兩種功能，則預設為 802.11az。不支援 IEEE 802.11az 的裝置執行所有操作 以 IEEE 802.11mc 協定執行。

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

要求量測範圍

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

例如：

Kotlin

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) { … }
})

Java

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 表示失敗。失敗表示此結果的所有其他欄位 (上述要求 ID 除外) 皆無效，且對應的 get* 方法會失敗，並擲回 IllegalStateException 例外狀況。

3. 取得每項成功評估的結果

對於每項成功的評估 (RangingResult)，您可以使用相應的 get 方法擷取結果值：

支援 WiFi-RTT 的 Android 裝置

下表列出部分手機、存取點，以及零售、倉儲和分銷中心裝置 皆支援 Wi-Fi-RTT 模式。這些絕非全面的解決方案。建議你與我們聯絡，將支援 RTT 的產品列入清單。

存取點

製造商和型號 支援日期
Nest Wifi Pro (Wi-Fi 6E) 支援
Compulab WILD AP 支援
Google Wi-Fi 支援
Google Nest Wi-Fi 路由器 支援
Google Nest Wi-Fi Point 支援
阿魯巴 AP-635 支援
思科 9130 支援
Cisco 9136 支援
思科 9166 支援
Cisco 9164 支援
Aruba AP-505 支援
阿魯巴 AP-515 支援
Aruba AP-575 支援
阿魯巴 AP-518 支援
阿魯巴 AP-505H 支援
阿魯巴 AP-565 支援
Aruba AP-535 支援

手機

製造商和型號 Android 版本
Pixel 6 9.0 以上版本
Pixel 6 Pro 9.0 以上版本
Pixel 5 9.0 以上版本
Pixel 5a 9.0 以上版本
Pixel 5a (5G) 9.0 以上版本
小米 Mi 10 Pro 9.0 以上版本
小米 Mi 10 9.0 以上
Xiaomi Redmi Mi 9T Pro 9.0 以上版本
小米 Mi 9T 9.0 以上版本
小米 Mi 9 9.0 以上
Xiaomi Mi Note 10 9.0 以上版本
Xiaomi Mi Note 10 Lite 9.0 以上
Xiaomi Redmi Note 9S 9.0 以上
Xiaomi Redmi Note 9 Pro 9.0 以上版本
Xiaomi Redmi Note 8T 9.0 以上版本
Xiaomi Redmi Note 8 9.0 以上
小米 Redmi K30 Pro 9.0 以上
Xiaomi Redmi K20 Pro 9.0 以上
Xiaomi Redmi K20 9.0 以上
小米 Redmi Note 5 Pro 9.0 以上
Xiaomi Mi CC9 Pro 9.0 以上
LG G8X ThinQ 9.0 以上
LG V50S ThinQ 9.0 以上
LG V60 ThinQ 9.0 以上版本
LG V30 9.0 以上版本
Samsung Galaxy Note 10+ 5G 9.0 以上
Samsung Galaxy S20+ 5G 9.0 以上版本
Samsung Galaxy S20+ 9.0 以上版本
Samsung Galaxy S20 5G 9.0 以上
Samsung Galaxy S20 Ultra 5G 9.0 以上
Samsung Galaxy S20 9.0 以上版本
Samsung Galaxy Note 10 以上版本 9.0 以上
Samsung Galaxy Note 10 5G 9.0 以上版本
Samsung Galaxy Note 10 9.0 以上
Samsung A9 Pro 9.0 以上版本
Google Pixel 4 XL 9.0 以上版本
Google Pixel 4 9.0 以上
Google Pixel 4a 9.0 以上版本
Google Pixel 3 XL 9.0 以上版本
Google Pixel 3 9.0 以上版本
Google Pixel 3a XL 9.0 以上版本
Google Pixel 3a 9.0 以上
Google Pixel 2 XL 9.0 以上版本
Google Pixel 2 9.0 以上
Google Pixel 1 XL 9.0 以上
Google Pixel 1 9.0 以上版本
Poco X2 9.0 以上
夏普 Aquos R3 SH-04L 9.0 以上版本

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

製造商和型號 Android 版本
賽布拉 PS20 (PS20) 10.0 以上版本
Zebra TC52/TC52HC 10.0 以上
Zebra TC57 10.0 以上
Zebra TC72 10.0 以上
Zebra TC77 10.0 以上
Zebra MC93 10.0 以上
Zebra TC8300 10.0 以上版本
Zebra VC8300 10.0 以上
Zebra EC30 10.0 以上版本
斑馬 ET51 10.0 以上版本
Zebra ET56 10.0 以上
Zebra L10 10.0 以上
Zebra CC600/CC6000 10.0 以上版本
Zebra MC3300x 10.0 以上
Zebra MC330x 10.0 以上
Zebra TC52x 10.0 以上
Zebra TC57x 10.0 以上版本
Zebra EC50 (LAN 和 HC) 10.0 以上版本
Zebra EC55 (WAN) 10.0 以上
澤布拉 WT6300 10.0 以上
Skorpio X5 10.0 以上版本