موقع Wi-Fi: بدءًا من ميزة "المراسلة النصية في الوقت الفعلي"

يمكنك استخدام وظيفة تحديد الموقع الجغرافي عبر شبكة Wi-Fi التي يوفّرها Wi-Fi RTT API لقياس المسافة إلى نقاط وصول Wi-Fi المجاورة المتوافقة مع RTT وأجهزة Wi-Fi Aware.

إذا قست المسافة إلى ثلاث نقاط وصول أو أكثر، يمكنك استخدام خوارزمية تحديد الموقع الجغرافي المتعدد لتقدير موضع الجهاز الذي يتناسب بشكل أفضل مع هذه القياسات. وتكون النتيجة دقيقة عادةً في نطاق يتراوح بين متر واحد ومترَين.

وبفضل هذه الدقة، يمكنك تطوير خدمات دقيقة مستندة إلى الموقع الجغرافي، مثل التنقّل في الأماكن المغلقة، والتحكّم الصوتي الواضح (على سبيل المثال، "أريد تشغيل هذا الضوء")، والمعلومات المستندة إلى الموقع الجغرافي (على سبيل المثال، "هل هناك عروض خاصة لهذا المنتج؟").

لا يحتاج الجهاز الذي يرسل الطلب إلى الاتصال بنقاط الوصول لقياس المسافة باستخدام Wi-Fi RTT. للحفاظ على الخصوصية، يمكن للجهاز الذي يطلب تحديد الموقع الجغرافي فقط تحديد المسافة إلى نقطة الوصول، ولا تتوفّر هذه المعلومات لنقاط الوصول. عمليات Wi-Fi RTT غير محدودة بالنسبة إلى التطبيقات التي تعمل في المقدّمة، ولكن يتم تقييدها بالنسبة إلى التطبيقات التي تعمل في الخلفية.

يتم تحديد إمكانات Wi-Fi RTT وقياس الوقت الدقيق (FTM) ذات الصلة بموجب معيار IEEE 802.11-2016. تتطلّب تقنية Wi-Fi RTT قياس الوقت بدقة الذي توفّره طريقة FTM، لأنّها تحتسب المسافة بين جهازَين من خلال قياس الوقت الذي تستغرقه الحزمة في التنقّل ذهابًا وإيابًا بين الجهازَين وضرب هذا الوقت بسرعة الضوء.

أتاح نظام التشغيل Android 15 (المستوى 35 لواجهة برمجة التطبيقات) استخدام تقنية تحديد المدى المستندة إلى المعيار IEEE 802.11az غير المستندة إلى المشغّل (NTB).

اختلافات التنفيذ استنادًا إلى إصدار Android

تم طرح تقنية Wi-Fi RTT في الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات). عند استخدام هذا البروتوكول لتحديد موضع الجهاز باستخدام التثليث المتعدد مع الأجهزة التي تعمل بنظام التشغيل Android 9، يجب أن يكون لديك إذن الوصول إلى بيانات المواقع الجغرافية المحدّدة مسبقًا لنقاط الوصول (AP) في تطبيقك. ويعود إليك تحديد كيفية تخزين هذه البيانات واسترجاعها.

على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن تمثيل بيانات الموقع الجغرافي لنقطة الوصول على شكل عناصر ResponderLocation تتضمّن خطوط الطول والعرض والارتفاع. بالنسبة إلى نقاط وصول Wi-Fi RTT التي تتوافق مع معلومات إعداد الموقع الجغرافي/تقرير الموقع الجغرافي المدني (بيانات LCI/LCR)، سيعرض البروتوكول عنصر ResponderLocation أثناء عملية تحديد المدى.

تتيح هذه الميزة للتطبيقات إرسال طلبات بحث إلى نقاط الوصول لسؤالها عن موقعها الجغرافي مباشرةً بدلاً من الحاجة إلى تخزين هذه المعلومات مسبقًا. وبالتالي، يمكن لتطبيقك العثور على نقاط الوصول وتحديد مواقعها حتى إذا لم تكن معروفة من قبل، مثلما يحدث عندما يدخل المستخدم مبنى جديدًا.

تتوفّر ميزة تحديد المدى المستند إلى معيار IEEE 802.11az NTB على الأجهزة التي تعمل بالإصدار Android 15 (المستوى 35 لواجهة برمجة التطبيقات) والإصدارات الأحدث. وهذا يعني أنّه إذا كان الجهاز يتيح وضع بدء تشغيل بروتوكول IEEE 802.11az NTB (يُشار إليه بالرمز WifiRttManager.CHARACTERISTICS_KEY_BOOLEAN_NTB_INITIATOR)، يمكن لتطبيقك العثور على نقاط وصول متوافقة مع بروتوكولَي IEEE 802.11mc وIEEE 802.11az من خلال طلب نطاق واحد. تمت إضافة وظائف إلى واجهة برمجة التطبيقات RangingResult لتوفير معلومات حول الحد الأدنى والأقصى للقيمة التي يمكن استخدامها للفاصل الزمني بين قياسات النطاق، مع ترك الفاصل الزمني الدقيق تحت سيطرة تطبيقك.

المتطلبات

• يجب أن تتوافق الأجهزة التي ترسل طلبات تحديد المدى مع معيار 802.11-2016 FTM أو معيار 802.11az (تحديد المدى غير المستند إلى المشغّل).
• يجب أن يعمل الجهاز الذي يرسل طلب تحديد المدى بالإصدار 9 (المستوى 28 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث من نظام التشغيل Android. يتم تفعيل ميزة تحديد المدى المستندة إلى عدم التشغيل وفقًا لمعيار IEEE 802.11az على الأجهزة التي تعمل بالإصدار 15 من نظام التشغيل Android (المستوى 35 لواجهة برمجة التطبيقات) والإصدارات الأحدث.
• يجب أن يكون الجهاز الذي يرسل طلب تحديد المدى قد فعّل خدمات الموقع الجغرافي وميزة "فحص شبكة Wi-Fi" (ضمن الإعدادات > الموقع الجغرافي).
• إذا كان التطبيق الذي يرسل طلب تحديد المدى يستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يجب أن يتضمّن إذن NEARBY_WIFI_DEVICES. إذا كان هذا التطبيق يستهدف إصدارًا قديمًا من Android، يجب أن يتضمّن الإذن ACCESS_FINE_LOCATION بدلاً من ذلك.
• يجب أن يستعلم التطبيق عن نطاق نقاط الوصول عندما يكون التطبيق مرئيًا أو في خدمة تعمل في المقدّمة. لا يمكن للتطبيق الوصول إلى معلومات الموقع الجغرافي من الخلفية.
• يجب أن تنفّذ نقطة الوصول معيار FTM‏ IEEE 802.11-2016 أو معيار 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:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3- التحقّق من توفّر Wi-Fi RTT

قد تكون ميزة Wi-Fi RTT متوفّرة على الجهاز، ولكن قد لا تكون متاحة لأنّ المستخدم أوقف شبكة Wi-Fi. قد لا تتوافق بعض الأجهزة مع ميزة Wi-Fi RTT إذا تم استخدام SoftAP أو الربط، وذلك حسب إمكانيات الأجهزة والبرامج الثابتة. للتأكّد مما إذا كانت ميزة Wi-Fi RTT متاحة، اتّصِل بالرقم isAvailable().

قد يتغيّر مدى توفّر ميزة Wi-Fi RTT في أي وقت. يجب أن يسجّل تطبيقك BroadcastReceiver لتلقّي ACTION_WIFI_RTT_STATE_CHANGED، الذي يتم إرساله عند حدوث تغيير في حالة التوفّر. عندما يتلقّى تطبيقك Intent البث، عليه التحقّق من حالة التوفّر الحالية وتعديل سلوكه وفقًا لذلك.

مثلاً:

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) من خلال تحديد قائمة بنقاط الوصول أو الأجهزة المتوافقة مع 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()). تُجري الأجهزة المتوافقة مع تحديد المدى IEEE 802.11az NTB عملية تحديد المدى 802.11mc أو 802.11az، وذلك حسب إمكانية نقطة الوصول، مع استخدام 802.11az تلقائيًا عندما تتوافق نقطة الوصول مع كلتا العمليتين. تُجري الأجهزة التي لا تتوافق مع معيار IEEE 802.11az جميع عمليات تحديد المدى باستخدام بروتوكول IEEE 802.11mc.

وبالمثل، يمكن لطلب تحديد المدى إضافة جهاز Wi-Fi Aware مجاور باستخدام عنوان MAC أو PeerHandle، وذلك باستخدام الطريقتَين addWifiAwarePeer(MacAddress peer) وaddWifiAwarePeer(PeerHandle peer) على التوالي. لمزيد من المعلومات حول العثور على أجهزة 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: في معظم الأحيان، يتم تقديم عنوان MAC في ScanResult لتحديد نقطة وصول. يمكن الحصول على عنوان MAC من نتيجة تحديد المدى باستخدام طريقة getMacAddress().

قد تختلف ترتيب قائمة نتائج تحديد المدى عن ترتيب الأجهزة المجاورة (نقاط الوصول) المحدّدة في طلب تحديد المدى، لذا عليك استخدام عنوان MAC لتحديد الجهاز المجاور، وليس ترتيب النتائج.

‫2- تحديد ما إذا كان كل قياس ناجحًا

لتحديد ما إذا كان القياس ناجحًا، استخدِم طريقة getStatus(). تشير أي قيمة أخرى غير STATUS_SUCCESS إلى حدوث خطأ. يشير الخطأ إلى أنّ جميع الحقول الأخرى في هذه النتيجة (باستثناء معرّف الطلب أعلاه) غير صالحة، وأنّ طريقة get* المقابلة ستتعذّر مع ظهور استثناء IllegalStateException.

3- الحصول على نتائج لكل قياس ناجح

بالنسبة إلى كل عملية قياس ناجحة (RangingResult)، يمكنك استرداد قيم النتائج باستخدام طرق get ذات الصلة:

• المسافة بالملليمتر والانحراف المعياري للقياس:

  getDistanceMm()

  getDistanceStdDevMm()

• مستوى إشارة RSSI للحِزم المستخدَمة في القياسات:

  getRssi()

• الوقت بالمللي ثانية الذي تم فيه إجراء القياس (ما يشير إلى الوقت منذ بدء التشغيل):

  getRangingTimestampMillis()

• عدد القياسات التي تمت محاولة إجرائها وعدد القياسات التي تمت بنجاح (والتي تستند إليها قياسات المسافة):

  getNumAttemptedMeasurements()

  getNumSuccessfulMeasurements()

• الحدّ الأدنى والأقصى للمدة التي يجب أن ينتظرها جهاز العميل بين قياسات NTB 11az:

  تعرض الدالتان getMinTimeBetweenNtbMeasurementsMicros() وgetMaxTimeBetweenNtbMeasurementsMicros() الحدّ الأدنى والأقصى للوقت. إذا تم طلب قياس النطاق التالي قبل انقضاء الحد الأدنى من الوقت، ستعرض واجهة برمجة التطبيقات نتيجة النطاق المخزّنة مؤقتًا. إذا تم طلب قياس النطاق التالي بعد انقضاء الحد الأقصى للوقت، ستنهي واجهة برمجة التطبيقات جلسة قياس النطاق غير المستندة إلى مشغّل وتتفاوض على جلسة قياس نطاق جديدة مع المحطة المستجيبة. يجب تجنُّب طلب جلسة تحديد مدى جديدة، لأنّ ذلك يضيف وقتًا إضافيًا إلى وقت قياس تحديد المدى. للاستفادة الكاملة من كفاءة تحديد المدى المستندة إلى 802.11az غير المستندة إلى مشغّل، شغِّل طلب تحديد المدى التالي بين الحدّ الأدنى والحدّ الأقصى لوقت القياس المحدّد في عملية القياس السابقة RangingResult.

• تكرارات حقل التدريب الطويل (LTF) التي تستخدمها محطات المستجيب والمبادر في الديباجة لنتيجة IEEE 802.11az NTB:

  get80211azResponderTxLtfRepetitionsCount()

  get80211azInitiatorTxLtfRepetitionsCount()

• عدد عمليات إرسال واستقبال تدفقات الوقت المكانية (STS) التي استخدمتها محطة البادئ للحصول على نتيجة IEEE 802.11az NTB:

  get80211azNumberOfTxSpatialStreams()

  get80211azNumberOfRxSpatialStreams()

أجهزة Android المتوافقة مع تقنية WiFi-RTT

تعرض الجداول التالية بعض الهواتف ونقاط الوصول وأجهزة البيع بالتجزئة والمستودعات ومراكز التوزيع التي تتوافق مع تقنية WiFi-RTT. وهي ليست شاملة. ننصحك بالتواصل معنا لإدراج منتجاتك المتوافقة مع تقنية RTT هنا.

نقاط الوصول

الهواتف

أجهزة البيع بالتجزئة والتخزين والتوزيع