Wi-Fi Suggest API für Internetverbindung

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

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

  • Die Bereitstellung eines PasspointConfiguration wird von der Suggest API unterstützt. Für die Bereitstellung einer PasspointConfiguration ist vor Android 11 die Verwendung der addOrUpdatePasspointConfiguration() API erforderlich.
  • Das Framework erzwingt Sicherheitsanforderungen für TLS-basierte Enterprise-Vorschläge (EAP-TLS, EAP-TTLS und EAP-PEAP). Für Vorschläge für solche Netzwerke müssen ein Root CA certificate und ein server domain name festgelegt werden.
  • Das Framework erzwingt Eigentumsanforderungen 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 ihnen automatisch eine Mobilfunkanbieter-ID zu, die der Mobilfunkanbieter-Signatur der App entspricht. Diese Vorschläge werden automatisch deaktiviert, wenn die entsprechende SIM 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 den Grad der Randomisierung für Ihr Netzwerk anzugeben.

  • isPasspointTermsAndConditionsSupported(): Nutzungsbedingungen sind ein Passpoint-Feature, mit dem Netzwerkbereitstellungen unsichere Captive Portals, die offene Netzwerke verwenden, durch ein sicheres Passpoint-Netzwerk ersetzen können. Wenn die Nutzungsbedingungen akzeptiert werden müssen, wird dem Nutzer eine Benachrichtigung angezeigt. Anwendungen, die Passpoint-Netzwerke vorschlagen, die durch Nutzungsbedingungen gegatet 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 es keine Verbindung zu diesem Netzwerk herstellen. In diesem Fall muss ein alternatives oder Legacy-Netzwerk vorgeschlagen werden.

  • isDecoratedIdentitySupported(): Bei der Authentifizierung bei Netzwerken mit einem Präfix-Dekor ermöglicht das dekorierte Identitätspräfix Netzwerkbetreibern, die Network Access ID (NAI) zu aktualisieren, um ein explizites Routing durch mehrere Proxys innerhalb eines AAA-Netzwerks auszufü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. Anwendungen, 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 diese Funktion unterstützt. Wenn das Gerät diese Funktion nicht unterstützt, wird die Identität nicht dekoriert und die Authentifizierung beim Netzwerk schlägt möglicherweise fehl.

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 Anmeldedaten für ein offenes, ein WPA2-, ein WPA3-Netzwerk 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);

Der Nutzer wird sofort, nachdem die App zum ersten Mal einen Vorschlag gemacht hat, 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 sieht der Nutzer ein Dialogfeld, wenn die App im Vordergrund ausgeführt wird, und eine Benachrichtigung, wenn sie 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 Vorschlagsanwendung zuordnet.

Umgang mit Verbindungstrennungen von Nutzern

Wenn der Nutzer die WLAN-Auswahl verwendet, um die Verbindung zu einem der Netzwerkvorschläge zu trennen, sobald eine Verbindung besteht, wird das Netzwerk ignoriert, solange es noch in Reichweite ist. Während dieses Zeitraums wird das Netzwerk nicht automatisch verbunden, auch wenn die App den Netzwerkvorschlag des Netzwerks entfernt und wieder hinzufügt. Wenn der Nutzer die WLAN-Auswahl verwendet, um eine explizite Verbindung zu einem Netzwerk herzustellen, das zuvor getrennt wurde, wird dieses Netzwerk sofort für die automatische Verbindung berücksichtigt.

Freigabestatus für App ändern

Wenn ein Nutzer die Benachrichtigung über die Netzwerkvorschläge ablehnt, wird die Berechtigung CHANGE_WIFI_STATE aus der App entfernt. Der Nutzer kann diese Genehmigung später im Menü für die WLAN-Steuerung erteilen (Einstellungen > Apps & Benachrichtigungen > Spezieller App-Zugriff > WLAN-Steuerung > App name).