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

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

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

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

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

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

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

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

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

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

يوضح نموذج الرمز البرمجي التالي كيفية تقديم بيانات الاعتماد لواحدة مفتوحة، و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 الذي يعمل على الجهاز:

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

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

التعامل مع عمليات إلغاء ربط المستخدم

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

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

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