Wi-Fi Suggest API für Internetverbindung

Auf Geräten mit Android 10 (API-Level 29) und höher kann Ihre App Netzwerkanmeldedaten für ein Gerät hinzufügen, damit es automatisch eine Verbindung zu einem WLAN-Zugangspunkt herstellen kann. Mit WifiNetworkSuggestion können Sie Vorschläge dazu machen, mit welchem Netzwerk eine Verbindung hergestellt werden soll. Die Plattform wählt letztendlich anhand der Eingaben Ihrer App und anderer Apps aus, welcher Zugangspunkt akzeptiert wird.

Hinweis: WLAN-Vorschläge sind keine gespeicherten Netzwerke und werden nicht auf der Seite „Gespeicherte Netzwerke“ angezeigt. Informationen zum Hinzufügen eines neuen WLANs mit Nutzerauswahl finden Sie in der ACTION_WIFI_ADD_NETWORKS Activity Action API. Über diese API wird der Nutzer aufgefordert, die Hinzufügung des Netzwerks zu genehmigen.

Android 11 (API-Level 30) und höher:

• Die Bereitstellung eines PasspointConfiguration wird von der Suggestion API unterstützt. Vor Android 11 ist für die Bereitstellung einer PasspointConfiguration die addOrUpdatePasspointConfiguration() API erforderlich.
• Das Framework erzwingt Sicherheitsanforderungen für TLS-basierte Vorschläge für Unternehmen (EAP-TLS, EAP-TTLS und EAP-PEAP). Vorschläge für solche Netzwerke müssen einen Root CA certificate und einen server domain name festlegen.

Hinweis :unsichere Vorschläge, die aus einer früheren Android-Version übernommen wurden, werden in Android 11 und höher ignoriert. Die App, die Vorschläge macht, muss ihre alten Vorschläge durch neue und sichere Vorschläge ersetzen.

• Das Framework erzwingt Eigentumsanforderungen für EAP-SIM-basierte Unternehmensvorschläge (EAP-SIM, EAP-AKA, EAP-AKA-PRIME). Solche Vorschläge sind nur von Apps zulässig, die vom Mobilfunkanbieter signiert wurden.
• Vorschlägen, die von einer vom Mobilfunkanbieter signierten App stammen, wird vom Framework automatisch eine Mobilfunkanbieter-ID zugewiesen, die der Mobilfunkanbietersignatur der App entspricht. Solche Vorschläge werden automatisch deaktiviert, wenn die entsprechende SIM-Karte aus dem Gerät entfernt wird.

Unter Android 12 (API-Level 31) und höher:

• Zusätzlicher Datenschutz kann durch die nicht persistente MAC-Zufallsmixung aktiviert werden, bei der die zufällige MAC-Adresse regelmäßig neu generiert wird. Verwenden Sie setMacRandomizationSetting, um den Grad der Zufallsmixung für Ihr Netzwerk anzugeben.

• isPasspointTermsAndConditionsSupported(): Nutzungsbedingungen ist eine Passpoint-Funktion, mit der bei Netzwerkbereitstellungen unsichere Captive Portals, die offene Netzwerke verwenden, durch ein sicheres Passpoint-Netzwerk ersetzt werden können. Wenn Nutzungsbedingungen akzeptiert werden müssen, wird dem Nutzer eine Benachrichtigung angezeigt. Apps, die Passpoint-Netzwerke vorschlagen, die durch Nutzungsbedingungen eingeschränkt sind, müssen zuerst diese API aufrufen, um sicherzustellen, dass das Gerät die Funktion unterstützt. Wenn das Gerät die Funktion nicht unterstützt, kann es keine Verbindung zu diesem Netzwerk herstellen. Es muss dann ein alternatives oder älteres Netzwerk vorgeschlagen werden.

• isDecoratedIdentitySupported(): Beim Authentifizieren in Netzwerken mit Präfixdekoration können Netzwerkbetreiber mit dem dekorierten Identitätspräfix den Network Access Identifier (NAI) aktualisieren, um ein explizites Routing über mehrere Proxys innerhalb eines AAA-Netzwerks durchzuführen. Weitere Informationen finden Sie unter RFC 7542.

  In Android 12 wird diese Funktion implementiert, um der WBA-Spezifikation für PPS-MO-Erweiterungen zu entsprechen. Apps, die Passpoint-Netzwerke vorschlagen, für die eine dekorierte Identität erforderlich ist, müssen zuerst diese API aufrufen, um sicherzustellen, dass das Gerät die Funktion unterstützt. Wenn das Gerät die Funktion nicht unterstützt, wird die Identität nicht dekoriert und die Authentifizierung im Netzwerk schlägt möglicherweise fehl.

Um einen Passpoint-Vorschlag zu erstellen, müssen Apps die Klassen PasspointConfiguration, Credential und HomeSp verwenden. Diese Klassen beschreiben das Passpoint-Profil, das in der Passpoint-Spezifikation der Wi‑Fi Alliance definiert ist.

Im folgenden Codebeispiel wird gezeigt, wie Anmeldedaten für ein offenes, ein WPA2-, ein WPA3- und ein Passpoint-Netzwerk angegeben werden:

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

Sobald die App zum ersten Mal einen Vorschlag macht, wird der Nutzer benachrichtigt. Der Benachrichtigungstyp hängt von der Android-Version ab, die auf dem Gerät ausgeführt wird:

• Unter Android 11 (API-Level 30) und höher wird dem Nutzer ein Dialogfeld angezeigt, wenn die App im Vordergrund ausgeführt wird, und eine Benachrichtigung, wenn die App im Hintergrund ausgeführt wird.
• Unter Android 10 (API-Level 29) wird dem Nutzer unabhängig davon eine Benachrichtigung angezeigt, ob die App im Vordergrund oder im Hintergrund ausgeführt wird.

Wenn die Plattform eine Verbindung zu einem der Netzwerkvorschläge herstellt, wird in den Einstellungen Text angezeigt, der die Netzwerkverbindung der entsprechenden App zuweist.

Umgang mit Nutzerunterbrechungen

Wenn der Nutzer über die WLAN-Auswahl explizit die Verbindung zu einem der Netzwerkvorschläge trennt, während er damit verbunden ist, wird dieses Netzwerk ignoriert, wenn es sich noch in Reichweite befindet. Während dieses Zeitraums wird dieses Netzwerk nicht für die automatische Verbindung berücksichtigt, auch wenn die App den entsprechenden Netzwerkvorschlag entfernt und wieder hinzufügt. Wenn der Nutzer über die WLAN-Auswahl explizit eine Verbindung zu einem Netzwerk herstellt, das zuvor getrennt war, wird dieses Netzwerk sofort für die automatische Verbindung berücksichtigt.

Freigabestatus für App ändern

Wenn ein Nutzer die Benachrichtigung zum Netzwerkvorschlag ablehnt, wird die Berechtigung CHANGE_WIFI_STATE von der App entfernt. Der Nutzer kann diese Genehmigung später erteilen, indem er das Menü „WLAN-Steuerung“ aufruft (Einstellungen > Apps und Benachrichtigungen > Spezieller App-Zugriff > WLAN-Steuerung > App name).