Wi-Fi Suggest API für Internetverbindung

Bei Geräten mit Android 10 (API-Level 29) und höher kann deine App Netzwerkanmeldedaten für ein Gerät hinzufügen, um sich automatisch mit einem WLAN-Zugangspunkt zu verbinden. Mit WifiNetworkSuggestion können Sie Vorschläge machen, zu welchem Netzwerk eine Verbindung hergestellt werden soll. Die Plattform wählt anhand der Eingaben Ihrer App und anderer Nutzer einen Zugangspunkt aus, der 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 nach Abschluss durch den Nutzer findest du in der Activity Action API ACTION_WIFI_ADD_NETWORKS. Über diese API wird der Nutzer aufgefordert, das Hinzufügen des Netzwerks zu bestätigen.

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

• Die Bereitstellung eines PasspointConfiguration wird von der Suggest API unterstützt. Vor Android 11 erfordert die Bereitstellung eines PasspointConfiguration die addOrUpdatePasspointConfiguration() API.
• Das Framework erzwingt Sicherheitsanforderungen für TLS-basierte Enterprise-Vorschläge (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 erhalten wurden, werden unter Android 11 und höher ignoriert. Die Vorschlags-App muss ihre alten Vorschläge durch neue und sichere Vorschläge ersetzen.

• Das Framework erzwingt Inhaberschaftsanforderungen für EAP-SIM-basierte Enterprise-Vorschläge (EAP-SIM, EAP-AKA, EAP-AKA-PRIME). Solche Vorschläge sind nur von Apps zugelassen, die vom Mobilfunkanbieter signiert sind.
• Bei Vorschlägen, die von einer vom Mobilfunkanbieter signierten App bereitgestellt werden, weist das Framework automatisch eine Mobilfunkanbieter-ID zu, die der Mobilfunkanbieter-Signatur 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 über eine nicht persistente MAC-Randomisierung aktiviert werden, bei der die zufällige MAC-Adresse regelmäßig neu zufällig angeordnet wird. Verwenden Sie setMacRandomizationSetting, um die Ebene der Randomisierung für Ihr Netzwerk anzugeben.

• isPasspointTermsAndConditionsSupported(): Nutzungsbedingungen sind eine Passpoint-Funktion, mit der Netzwerkbereitstellungen unsichere Captive Portals, die offene Netzwerke verwenden, durch ein sicheres Passpoint-Netzwerk ersetzen können. Der Nutzer erhält eine Benachrichtigung, wenn die Nutzungsbedingungen akzeptiert werden müssen. Apps, die Passpoint-Netzwerke vorschlagen, die durch Nutzungsbedingungen geschützt sind, müssen zuerst diese API aufrufen, um sicherzustellen, dass das Gerät die Funktion unterstützt. Wenn das Gerät diese Funktion nicht unterstützt, kann keine Verbindung zu diesem Netzwerk hergestellt werden und es muss ein alternatives oder altes Netzwerk vorgeschlagen werden.

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

  Unter Android 12 wird diese Funktion gemäß der WBA-Spezifikation für PPS-MO-Erweiterungen implementiert. Apps, die Passpoint-Netzwerke vorschlagen, die eine dekorierte Identität erfordern, müssen zuerst diese API aufrufen, um sicherzustellen, dass das Gerät die Funktion unterstützt. Wenn das Gerät diese Funktion nicht unterstützt, wird die Identität nicht dekoriert und die Authentifizierung beim Netzwerk kann fehlschlagen.

Zum Erstellen eines Passpoint-Vorschlags müssen Anwendungen die Klassen PasspointConfiguration, Credential und HomeSp verwenden. Diese Klassen beschreiben das Passpoint-Profil, das in der Passpoint-Spezifikation der Wi-Fi Alliance definiert ist.

Das folgende Codebeispiel zeigt, wie Sie Anmeldedaten für ein offenes, ein WPA2-, ein WPA3-Netzwerk und ein Passpoint-Netzwerk bereitstellen:

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

Der Nutzer wird direkt nach der ersten Eingabe eines Vorschlags durch die App 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. Außerdem wird eine Benachrichtigung angezeigt, wenn die App im Hintergrund ausgeführt wird.
• Unter Android 10 (API-Level 29) sieht der Nutzer eine Benachrichtigung, unabhängig davon, 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 Vorschlags-App zuordnet.

Trennen der Verbindung durch Nutzer

Wenn der Nutzer die Verbindung zu einem der Vorschläge für ein Netzwerk bei einer Verbindung über die WLAN-Auswahl explizit trennt, wird dieses Netzwerk ignoriert, wenn es sich noch in Reichweite befindet. Während dieser Zeit wird das Netzwerk nicht für die automatische Verbindung berücksichtigt, auch wenn die Anwendung 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 wurde, wird dieses Netzwerk sofort als automatische Verbindung betrachtet.

Genehmigungsstatus für App ändern

Wenn ein Nutzer die Benachrichtigung zu Netzwerkvorschlägen ablehnt, wird die Berechtigung CHANGE_WIFI_STATE aus der App entfernt. Er kann die Genehmigung später über das WLAN-Steuerungsmenü erteilen (Einstellungen > Apps & Benachrichtigungen > Spezieller App-Zugriff > WLAN-Steuerung > App name).