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

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

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

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

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

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

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

اختلافات طريقة التنفيذ حسب إصدار Android

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

على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكن تمثيل بيانات الموقع الجغرافي لنقطة الوصول باستخدام ResponderLocation عناصر تشمل خط العرض وخط الطول والارتفاع. بالنسبة إلى نقاط APK التي تستخدم ميزة "المراسلة النصية في الوقت الفعلي" لشبكة Wi-Fi التي مع ميزة "معلومات ضبط الموقع الجغرافي" أو "التقرير المدني للموقع الجغرافي" (بيانات 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 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) أو إصدار أحدث. يتم تفعيل قياس المسافة غير المستند إلى عامل تشغيل 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، عليك اتّباع الخطوات التالية:

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 خطيران. لذا عليك طلبها في وقت التشغيل في كل مرة يريد فيها المستخدم إجراء عملية فحص باستخدام ميزة "مراسلة نصية في الوقت الفعلي" على تطبيقك طلب إذن العميل إذا لم يتم منحه من قبل. لمزيد من المعلومات عن أذونات وقت التشغيل، يُرجى الاطّلاع على طلب أذونات التطبيق.

‫2- التحقّق مما إذا كان الجهاز يتيح ميزة "المراسلة النصية في الوقت الفعلي" لشبكة Wi-Fi

للتحقّق مما إذا كان الجهاز متوافقًا مع ميزة "وقت الاستجابة للتحدث" عبر Wi-Fi، استخدِم واجهة برمجة التطبيقات PackageManager:

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_RTT)

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

3- التحقّق مما إذا كانت ميزة "وقت استجابة Wi-Fi" متاحة

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

يمكن أن يتغيّر مدى توفّر ميزة "المراسلة النصية في الوقت الفعلي" لشبكة Wi-Fi في أي وقت. يجب أن يسجِّل تطبيقك علامة إشتراك في 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) من خلال تحديد قائمة بنقاط الوصول أو الأجهزة المزوّدة بتقنية Wi-Fi Aware التي يتم طلب النطاق لها. يمكن تحديد نقاط وصول متعددة أو نظراء Wi-Fi في طلب أحادي النطاق يتم قياس المسافات بين جميع الأجهزة وإرجاعها.

على سبيل المثال، يمكن للطلب استخدام دالة 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، والذي يمكن الحصول عليه من خلال memanggil WifiManager.getScanResults(). يمكنك استخدام addAccessPoints(List<ScanResult>) لإضافة نقاط وصول متعددة في دفعة واحدة.

يمكن أن تحتوي كائنات ScanResult على كلٍّ من IEEE 802.11mc (is80211mcResponder()) و يتوافق معيار IEEE 802.11az مع نطاق غير مستند إلى المشغّل (is80211azNtbResponder()). نقاط الوصول. تعمل الأجهزة التي تتوافق مع معيار IEEE 802.11az NTB بمجال 802.11mc أو نطاق 802.11az وفقًا لقدرة 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 لتلقّي النتائج.

مثلاً:

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()

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

  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 هنا.

نقاط الوصول

الهواتف

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