واجهة برمجة تطبيقات لاقتراح 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 والإصدارات الأحدث. يجب أن يستبدل التطبيق المقترِح اقتراحاته القديمة باقتراحات جديدة وآمنة.

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

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

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

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