API per suggerimenti di Wi-Fi per la connettività a Internet

I dispositivi con Android 10 (livello API 29) e versioni successive consentono alla tua app di aggiungere credenziali di rete per consentire al dispositivo di connettersi automaticamente a un punto di accesso Wi-Fi. Puoi fornire suggerimenti relativi alla rete a cui connetterti utilizzando WifiNetworkSuggestion. Alla fine la piattaforma sceglie quale punto di accesso accettare in base all'input della tua app e di altri.

Su Android 11 (livello API 30) e versioni successive:

  • Il framework applica requisiti di proprietà per i suggerimenti Enterprise basati su EAP-SIM (EAP-SIM, EAP-AKA, EAP-AKA-PRIME); questi suggerimenti sono consentiti solo dalle app firmate dall'operatore.
  • Per i suggerimenti forniti da un'app firmata dall'operatore, il framework assegna automaticamente all'app un ID dell'operatore corrispondente alla firma dell'operatore dell'app. Questi suggerimenti vengono disattivati automaticamente se la SIM corrispondente viene rimossa dal dispositivo.

Su Android 12 (livello API 31) e versioni successive:

  • È possibile abilitare un'ulteriore privacy tramite casualizzazione MAC non persistente, che periodicamente riordina periodicamente l'indirizzo MAC casuale. Usa setMacRandomizationSetting per specificare il livello di randomizzazione per la tua rete.

  • isPasspointTermsAndConditionsSupported(): Termini e condizioni è una funzionalità di Passpoint che consente ai deployment di rete di sostituire i captive portal non sicuri, che utilizzano reti aperte, con una rete Passpoint sicura. Quando termini e condizioni devono essere accettati, viene visualizzata una notifica all'utente. Le app che suggeriscono reti Passpoint controllate da termini e condizioni devono prima chiamare questa API per assicurarsi che il dispositivo supporti la funzionalità. Se il dispositivo non supporta questa funzionalità, non potrà connettersi a questa rete ed è necessario suggerire una rete alternativa o legacy.

  • isDecoratedIdentitySupported(): quando esegui l'autenticazione sulle reti con un prefisso, il prefisso di identità decorato consente agli operatori di rete di aggiornare l'identificatore di accesso alla rete (NAI) per eseguire il routing esplicito tramite più proxy all'interno di una rete AAA (per ulteriori informazioni, consulta il documento RFC 7542).

    Android 12 implementa questa funzionalità in conformità alla specifica WBA per le estensioni PPS-MO. Le app che suggeriscono reti Passpoint che richiedono un'identità definita devono chiamare prima questa API per assicurarsi che il dispositivo supporti la funzionalità. Se il dispositivo non supporta la funzionalità, l'identità non verrà decorata e l'autenticazione sulla rete potrebbe non riuscire.

Per creare un suggerimento di Passpoint, le app devono utilizzare le classi PasspointConfiguration, Credential e HomeSp. Queste classi descrivono il profilo Passpoint, definito nella specifica Passpoint di Wi-Fi Alliance.

Il seguente esempio di codice mostra come fornire le credenziali per una rete aperta, una rete WPA2, una rete WPA3 e una rete Passpoint:

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

Subito dopo che l'app inserisce un suggerimento per la prima volta, l'utente riceve una notifica. Il tipo di notifica dipende dalla versione di Android installata sul dispositivo:

  • Su Android 11 (livello API 30) e versioni successive, l'utente visualizza una finestra di dialogo se l'app è in esecuzione in primo piano e una notifica se l'app è in esecuzione in background.
  • Su Android 10 (livello API 29), l'utente vede una notifica, a prescindere dal fatto che l'app sia in esecuzione in primo piano o in background.

Quando la piattaforma si connette a uno dei suggerimenti di rete, le impostazioni mostrano il testo che attribuisce la connessione di rete all'app del suggeritore corrispondente.

Gestione delle disconnessioni degli utenti

Se l'utente utilizza il selettore Wi-Fi per disconnettersi esplicitamente da uno dei suggerimenti di rete quando è connesso, la rete viene ignorata quando è ancora nel raggio d'azione. Durante questo periodo, la rete non verrà considerata per la connessione automatica, anche se l'app rimuove e aggiunge nuovamente il suggerimento di rete corrispondente alla rete. Se l'utente utilizza il selettore Wi-Fi per connettersi esplicitamente a una rete che è stata disconnessa in precedenza, quella rete verrà considerata immediatamente per la connessione automatica.

Modifica dello stato di approvazione per l'app

Un utente che rifiuta la notifica di suggerimento di rete rimuove l'autorizzazione CHANGE_WIFI_STATE dall'app. L'utente può concedere questa approvazione in un secondo momento accedendo al menu di controllo del Wi-Fi (Impostazioni > App e notifiche > Accesso speciale per le app > Controllo Wi-Fi > App name).