واجهة برمجة تطبيقات لاقتراح Wi-Fi للاتصال بالإنترنت

تسمح الأجهزة التي تعمل بنظام التشغيل Android 10 (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث لتطبيقك بإضافة بيانات اعتماد الشبكة لكي يتم الاتصال تلقائيًا بنقطة وصول Wi-Fi. يمكنك تقديم اقتراحات للشبكة التي تريد الاتصال بها باستخدام WifiNetworkSuggestion. يختار النظام الأساسي في النهاية نقطة الوصول التي سيتم قبولها استنادًا إلى المعلومات الواردة من تطبيقك والتطبيقات الأخرى.

ملاحظة: لا تكون اقتراحات Wi-Fi شبكات محفوظة ولن تظهر في صفحة الشبكات المحفوظة. ولإضافة شبكة Wi-Fi جديدة مع إكمال المستخدمين، راجع ACTION_WIFI_ADD_NETWORKS واجهة برمجة تطبيقات إجراءات النشاط سيطلب من المستخدم الموافقة على إضافة

الشبكة.

على نظام التشغيل Android 11 (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث:

• جارٍ توفير المتطلبات اللازمة لـ PasspointConfiguration تدعمها واجهة برمجة تطبيقات الاقتراحات. قبل الإصدار 11 من Android، كان تجهيز PasspointConfiguration يتطلب استخدام واجهة برمجة التطبيقات addOrUpdatePasspointConfiguration() .
• يفرض إطار العمل متطلبات الأمان على اقتراحات Enterprise المستندة إلى بروتوكول أمان طبقة النقل (EAP-TLS وEAP-TTLS وEAP-PEAP)، ويجب أن تضبط الاقتراحات المُقدَّمة لهذه الشبكات Root CA certificate وserver domain name.

ملاحظة: يتم الاحتفاظ بالاقتراحات غير الآمنة التي تم الاحتفاظ بها من إصدار سابق من Android. تم تجاهلها في نظام التشغيل Android 11 والإصدارات الأحدث. يجب استبدال التطبيق المقترَح. الاقتراحات القديمة مع اقتراحات جديدة وآمنة.

• يفرض الإطار متطلبات الملكية لاقتراحات Enterprise المستندة إلى EAP-SIM (EAP-SIM وEAP-AKA وEAP-AKA-PRIME)، ولا يُسمح بهذه الاقتراحات إلا للتطبيقات التي وقّعها مشغّل شبكة الجوّال.
• بالنسبة إلى الاقتراحات المقدَّمة من تطبيق موقَّع من مشغّل شبكة الجوَّال، يمنح إطار العمل تلقائيًا رقم تعريف مشغّل شبكة الجوَّال المرتبط بتوقيع مشغّل شبكة الجوَّال للتطبيق. مثل يتم إيقاف الاقتراحات تلقائيًا في حال إزالة شريحة SIM المقابلة. من الجهاز.

على نظام التشغيل Android 12 (المستوى 31 لواجهة برمجة التطبيقات) والإصدارات الأحدث:

• يمكن تفعيل الخصوصية الإضافية من خلال التوزيع العشوائي غير الدائم لعنوان MAC. الذي يعيد ترتيب عنوان MAC العشوائي بشكل عشوائي. استخدِم setMacRandomizationSetting لتحديد مستوى العشوائية لشبكتك.

• isPasspointTermsAndConditionsSupported(): الأحكام والشروط هي ميزة Passpoint تسمح بعمليات نشر الشبكة لاستبدال المداخل المشروطة الوصول إليها غير الآمنة، التي تستخدم شبكات مفتوحة، بشبكة Passpoint آمنة. الإشعار هو عرض الإعلان للمستخدم عندما يلزم قبول الأحكام والشروط. بالنسبة إلى التطبيقات التي تقترح شبكات Passpoint التي تخضع لأحكام وشروط معيّنة، يجب أن تتصل أولاً بواجهة برمجة التطبيقات هذه للتأكّد من أنّ الجهاز يتيح هذه الميزة. وإذا كان الجهاز لا يوفّر هذه الميزة، لن يتمكّن من الاتصال هذه الشبكة، ويجب اقتراح شبكة بديلة أو قديمة.

• isDecoratedIdentitySupported(): عند المصادقة على الشبكات التي تتضمّن زخرفة بادئة، تسمح بادئة الهوية المزخرفة لمشغّلي الشبكة بتعديل معرّف الوصول إلى الشبكة (NAI) لإجراء توجيه صريح من خلال عدة خوادم وكيلة داخل شبكة إدارة الهوية وإمكانية الوصول (AAA) (اطّلِع على RFC 7542 للحصول علىمزيد من المعلومات حول هذا الموضوع).

  ينفِّذ نظام التشغيل Android 12 هذه الميزة للتوافق مع مواصفات WBA لإضافات PPS-MO . يجب على التطبيقات التي تقترح شبكات نقطة مرور تتطلب هوية مزينة. باستدعاء واجهة برمجة التطبيقات هذه أولاً للتأكد من أن الجهاز يدعم هذه الإمكانية. إذا لم يكن الجهاز متوافقًا مع هذه الميزة، لن يتم تزيين الهوية وقد يتعذّر إجراء المصادقة على الشبكة.

لإنشاء اقتراح Passpoint، يجب أن تستخدم التطبيقات فئات PasspointConfiguration و Credential و HomeSp. هذه الملف الشخصي لنقطة المرور، والمحدَّد في تحالف Wi-Fi Alliance نقطة مرور المواصفات.

يوضح نموذج الرمز البرمجي التالي كيفية تقديم بيانات الاعتماد لواحد مفتوح وآخر مفتوح. WPA2 وشبكة WPA3 واحدة وشبكة نقطة مرور واحدة:

KotlinJava

val suggestion1 = WifiNetworkSuggestion.Builder()
        .setSsid("test111111")
        .setIsAppInteractionRequired(true) // Optional (Needs location permission)
        .build();

val suggestion2 = WifiNetworkSuggestion.Builder()
        .setSsid("test222222")
        .setWpa2Passphrase("test123456")
        .setIsAppInteractionRequired(true) // Optional (Needs location permission)
        .build();

val suggestion3 = WifiNetworkSuggestion.Builder()
        .setSsid("test333333")
        .setWpa3Passphrase("test6789")
        .setIsAppInteractionRequired(true) // Optional (Needs location permission)
        .build();

val passpointConfig = PasspointConfiguration(); // configure passpointConfig to include a valid Passpoint configuration
val suggestion4 = WifiNetworkSuggestion.Builder()
        .setPasspointConfig(passpointConfig)
        .setIsAppInteractionRequired(true) // Optional (Needs location permission)
        .build();

val suggestionsList = listOf(suggestion1, suggestion2, suggestion3, suggestion4);

val wifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager;

val status = wifiManager.addNetworkSuggestions(suggestionsList);
if (status != WifiManager.STATUS_NETWORK_SUGGESTIONS_SUCCESS) {
    // do error handling here
}

// Optional (Wait for post connection broadcast to one of your suggestions)
val intentFilter = IntentFilter(WifiManager.ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION);

val broadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (!intent.action.equals(WifiManager.ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION)) {
            return;
        }
        // do post connect processing here
    }
};
context.registerReceiver(broadcastReceiver, intentFilter);

final WifiNetworkSuggestion suggestion1 =
  new WifiNetworkSuggestion.Builder()
  .setSsid("test111111")
  .setIsAppInteractionRequired(true) // Optional (Needs location permission)
  .build();

final WifiNetworkSuggestion suggestion2 =
  new WifiNetworkSuggestion.Builder()
  .setSsid("test222222")
  .setWpa2Passphrase("test123456")
  .setIsAppInteractionRequired(true) // Optional (Needs location permission)
  .build();

final WifiNetworkSuggestion suggestion3 =
  new WifiNetworkSuggestion.Builder()
  .setSsid("test333333")
  .setWpa3Passphrase("test6789")
  .setIsAppInteractionRequired(true) // Optional (Needs location permission)
  .build();

final PasspointConfiguration passpointConfig = new PasspointConfiguration();
// configure passpointConfig to include a valid Passpoint configuration

final WifiNetworkSuggestion suggestion4 =
  new WifiNetworkSuggestion.Builder()
  .setPasspointConfig(passpointConfig)
  .setIsAppInteractionRequired(true) // Optional (Needs location permission)
  .build();

final List<WifiNetworkSuggestion> suggestionsList =
  new ArrayList<WifiNetworkSuggestion> {{
    add(suggestion1);
    add(suggestion2);
    add(suggestion3);
    add(suggestion4);
  }};

final WifiManager wifiManager =
  (WifiManager) context.getSystemService(Context.WIFI_SERVICE);

final int status = wifiManager.addNetworkSuggestions(suggestionsList);
if (status != WifiManager.STATUS_NETWORK_SUGGESTIONS_SUCCESS) {
// do error handling here…
}

// Optional (Wait for post connection broadcast to one of your suggestions)
final IntentFilter intentFilter =
  new IntentFilter(WifiManager.ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION);

final BroadcastReceiver broadcastReceiver = new BroadcastReceiver() {
  @Override
  public void onReceive(Context context, Intent intent) {
    if (!intent.getAction().equals(
      WifiManager.ACTION_WIFI_NETWORK_SUGGESTION_POST_CONNECTION)) {
      return;
    }
    // do post connect processing here...
  }
};
context.registerReceiver(broadcastReceiver, intentFilter);

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

• في الإصدار 11 من نظام Android (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يظهر للمستخدم مربّع حوار إذا كان التطبيق يعمل في المقدّمة، ويظهر له إشعار إذا كان التطبيق يعمل في الخلفية.
• في Android 10 (المستوى 29 لواجهة برمجة التطبيقات)، يظهر إشعار للمستخدم بغض النظر عمّا إذا كان التطبيق قيد التشغيل في المقدّمة أو الخلفية.

عندما تتصل المنصة بأحد اقتراحات الشبكات، تعرض الإعدادات نصًا ينسب اتصال الشبكة إلى تطبيق الاقتراح المقابل.

التعامل مع حالات انقطاع الاتصال بالمستخدم

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

تغيير حالة الموافقة على التطبيق

يؤدي رفض مستخدم لإشعار اقتراح الشبكة إلى إزالة إذن CHANGE_WIFI_STATE من التطبيق. يمكن للمستخدم منح هذه الموافقة لاحقًا عن طريق الانتقال إلى قائمة التحكم في شبكة Wi-Fi (الإعدادات > التطبيقات الإشعارات > تطبيق خاص وصول > التحكُّم في شبكة Wi-Fi > App name).