本頁面由 Cloud Translation API 翻譯而成。

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

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

如果你測量到三個以上存取點之間的距離，可以使用以便估算出最適合的裝置位置測量資料測量結果通常在 1 到 2 公尺以內。

有了準確度，您就能開發精細的適地性服務，例如視為室內導航、清楚易懂的語音控制功能 (例如「開啟這個功能」燈號」)，以及根據位置資訊 (例如「有特價優惠」) 。」)

提出要求的裝置不需要連線到存取點即可進行測量使用 Wi-Fi 即時文字訊息功能。為維護隱私，只有提出要求的裝置才能判斷存取點與存取點之間的距離；存取點沒有這些資訊針對前景應用程式，Wi-Fi RTT 作業沒有限制，但背景應用程式受到限制。

包括 Wi-Fi RTT 和相關的精細時間測量 (FTM) 功能已根據 IEEE 802.11-2016 標準指定。Wi-Fi RTT 需要精確的時間計算 FTM 用來計算方法是測量封包從並將時間乘以光速

各 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 並判斷其位置，例如使用者進入新建築物時

需求條件

發出測距要求的裝置硬體必須實作 802.11-2016 FTM 標準。
發出測距要求的裝置必須搭載 Android 9 (API 級別) 28) 以上版本。
發出測距要求的裝置必須啟用定位服務，並開啟掃描 Wi-Fi 功能 (位於「設定」>「位置」)。
如果發出測距要求的應用程式 Android 13 (API 級別 33) 以上版本，必須具備 NEARBY_WIFI_DEVICES敬上權限。如果這類應用程式指定較舊的 Android 版本，則必須提供 ACCESS_FINE_LOCATION敬上權限。
應用程式必須處於顯示狀態或位於以下位置時，查詢存取點的範圍前景服務應用程式無法透過以下瀏覽器存取位置資訊：背景。
存取點必須導入 IEEE 802.11-2016 FTM 標準。

設定

如要將應用程式設為使用 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 即時文字訊息

如要確認裝置是否支援 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 或網路共用功能，部分裝置可能不支援 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 感知對等點的清單要求。可以在單一測距要求就能測量並傳回所有裝置的距離。

舉例來說，請求可以使用 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) 分批新增多個存取點

同樣地，透過分距要求新增 Wi-Fi Aware 對等互連，也可使用其 MAC 位址或其 PeerHandle 這個 addWifiAwarePeer(MacAddress 對等點) 和 addWifiAwarePeer(PeerHandle 對等互連) 方法。如需進一步瞭解如何找出 Wi-Fi 感知的同儕，請參閱 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 位址，用於識別存取權點。MAC 位址可透過使用 getMacAddress() 方法。

範圍結果清單的順序可能與同類應用程式不同 (存取 )，因此您應該使用 MAC 位址，找出同儕，而非結果的順序。

2. 判斷各項評估是否成功

如要判斷評估是否成功，請使用 getStatus() 方法。除 STATUS_成功表示失敗。失敗是指此結果的所有其他欄位 (上述要求身分除外) 無效，而且對應的 get* 方法將會失敗，並傳回 IllegalStateException 例外狀況。

3. 每次成功評估成效

您可以針對每項成功的測量結果，使用個別的 get 方法：

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

getDistanceMm()

getDistanceStdDevMm()
用於測量的封包 RSSI：

getRssi()
測量作業的時間 (以毫秒為單位，表示時間) 開啟後)：

getRangingTimestampMillis()
嘗試的測量次數和測量次數成功信號 (距離測量結果的計算方法)：

getNumenteredMeasurements()

getNumSuccessMeasurements()

支援 Wi-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	支援
思科 9136	支援
思科 9166	支援
Cisco 9164	支援
阿魯巴 AP-505	支援
阿魯巴 AP-515	支援
阿魯巴 AP-575	支援
阿魯巴 AP-518	支援
阿魯巴 AP-505H	支援
阿魯巴 AP-565	支援
阿魯巴 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 以上版本
小米 Redmi Mi 9T Pro	9.0 以上版本
小米 Mi 9T	9.0 以上版本
小米 Mi 9	9.0 以上版本
小米 Mi Note 10	9.0 以上版本
小米 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 以上版本
小米 Redmi K20 Pro	9.0 以上版本
小米 Redmi K20	9.0 以上版本
小米 Redmi Note 5 Pro	9.0 以上版本
小米 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 以上版本
斑馬 MC93	10.0 以上版本
Zebra TC8300	10.0 以上版本
Zebra VC8300	10.0 以上版本
斑馬 EC30	10.0 以上版本
斑馬 ET51	10.0 以上版本
斑馬 ET56	10.0 以上版本
賽布拉第 10 級	10.0 以上版本
薩布拉 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 以上版本