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

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

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

الشبكة.

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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

Java

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