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

IEEE 802.11az NTB 定距支援搭載 Android 15 的裝置 (API 級別 35) 以上版本。也就是說,如果裝置支援 IEEE 802.11az NTB 回應器模式 (表示 WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_STA_RESPONDER), 您的應用程式只要有一個 IEEE 802.11mc 和 IEEE 802.11az 支援 AP, 範圍要求。RangingResult API 已擴充以提供資訊 可用來計算時間間隔的最小值和最大值 測量範圍,以便控制您的應用程式。

需求條件

  • 發出測距要求的裝置硬體必須實作 802.11-2016 FTM 標準或 802.11az 標準 (非觸發式測距)。
  • 發出測距要求的裝置必須搭載 Android 9 (API 級別) 28) 以上版本。裝置啟用了 IEEE 802.11az 非觸發式測距功能 搭載 Android 15 (API 級別 35) 以上版本。
  • 發出測距要求的裝置必須啟用定位服務 ,並開啟掃描 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_DEVICESACCESS_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,但可能無法使用,因為使用者可能會無法使用 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 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()) AP。支援 IEEE 802.11az NTB 範圍的裝置需執行 802.11mc 或 802.11az 範圍根據 AP 的功能而定,在 AP 時預設為 802.11az AP 都支援這兩種功能不支援 IEEE 802.11az 的裝置執行所有操作 以 IEEE 802.11mc 協定執行。

同樣地,透過分距要求新增 Wi-Fi Aware 對等互連,也可使用其 MAC 位址或其 PeerHandle 這個 addWifiAwarePeer(MacAddress peer)addWifiAwarePeer(PeerHandle peer) 方法。如需進一步瞭解如何找出 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_SUCCESS敬上 表示失敗。失敗是指此結果的所有其他欄位 (上述要求身分除外) 無效,而且對應的 get* 方法將會失敗,並傳回 IllegalStateException 例外狀況。

3. 每次成功評估成效

每項成功的測量結果 (RangingResult) 都可以擷取結果 分別使用 get 方法:

,瞭解如何調查及移除這項存取權。

支援 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 以上版本