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

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

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

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

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

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

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

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

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

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

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

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

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 الذي يعمل على الجهاز:

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

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

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

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

جارٍ تغيير حالة الموافقة للتطبيق

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