Richiedi autorizzazioni posizione

Per proteggere la privacy degli utenti, le app che utilizzano i servizi di geolocalizzazione devono richiedere le autorizzazioni di accesso alla posizione.

Quando richiedi le autorizzazioni di accesso alla posizione, segui le stesse best practice utilizzate per qualsiasi altra autorizzazione di runtime. Una differenza importante per quanto riguarda le autorizzazioni di accesso alla posizione è che il sistema include più autorizzazioni correlate alla posizione. Le autorizzazioni richieste e le modalità di richiesta dipendono dai requisiti della località per il caso d'uso della tua app.

Questa pagina descrive i diversi tipi di requisiti per le località e fornisce indicazioni su come richiedere le autorizzazioni di accesso alla posizione in ciascun caso.

Tipi di accesso alla posizione

Ogni autorizzazione ha una combinazione delle seguenti caratteristiche:

Posizione in primo piano

Se la tua app contiene una funzionalità che condivide o riceve informazioni sulla posizione solo una volta o per un periodo di tempo definito, tale funzionalità richiede l'accesso alla posizione in primo piano. Tra gli esempi di tali prodotti o servizi figurano:

  • In un'app di navigazione è presente una funzione che consente agli utenti di ricevere indicazioni stradali passo passo.
  • All'interno di un'app di messaggistica, una funzionalità consente agli utenti di condividere la propria posizione attuale con un altro utente.

Il sistema considera che la tua app utilizza la posizione in primo piano se una funzionalità dell'app accede alla posizione attuale del dispositivo in una delle seguenti situazioni:

  • Un'attività appartenente alla tua app è visibile.
  • La tua app esegue un servizio in primo piano. Quando un servizio in primo piano è in esecuzione, il sistema aumenta la consapevolezza degli utenti mostrando una notifica persistente. L'app conserva l'accesso quando è posizionata in background, ad esempio quando l'utente preme il pulsante Home sul proprio dispositivo o spegne il display del dispositivo.

    Inoltre, ti consigliamo di dichiarare un tipo di servizio in primo piano pari a location, come mostrato nello snippet di codice riportato di seguito. Su Android 10 (livello API 29) e versioni successive, devi dichiarare questo tipo di servizio in primo piano.

    <!-- Recommended for Android 9 (API level 28) and lower. -->
    <!-- Required for Android 10 (API level 29) and higher. -->
    <service
        android:name="MyNavigationService"
        android:foregroundServiceType="location" ... >
        <!-- Any inner elements would go here. -->
    </service>
    

Dichiari la necessità della posizione in primo piano quando l'app richiede l'autorizzazione ACCESS_COARSE_LOCATION o ACCESS_FINE_LOCATION, come mostrato nello snippet seguente:

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

Posizione in background

Un'app richiede l'accesso alla posizione in background se una funzionalità al suo interno condivide costantemente la posizione con altri utenti o se utilizza l'API Geofencing. Ecco alcuni esempi:

  • Una funzionalità consente agli utenti di condividere continuamente la posizione con i membri del gruppo Famiglia.
  • All'interno di un'app IoT, una funzionalità consente agli utenti di configurare i dispositivi per la casa in modo che si spengano quando l'utente esce di casa e si riaccendano quando l'utente torna a casa.

Il sistema considera che la tua app utilizza la posizione in background se accede alla posizione attuale del dispositivo in qualsiasi situazione diversa da quelle descritte nella sezione Posizione in primo piano. La precisione della posizione in background è uguale alla precisione della posizione in primo piano, che dipende dalle autorizzazioni di accesso alla posizione dichiarate dalla tua app.

Su Android 10 (livello API 29) e versioni successive, devi dichiarare l'autorizzazione ACCESS_BACKGROUND_LOCATION nel file manifest dell'app per richiedere l'accesso alla posizione in background in fase di runtime. Nelle versioni precedenti di Android, quando la tua app riceve l'accesso alla posizione in primo piano, riceve automaticamente anche l'accesso alla posizione in background.

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

Accuratezza

Android supporta i seguenti livelli di precisione della posizione:

Approssimativa
Fornisce una stima della posizione del dispositivo. Se la località stimata è ricavata da LocationManagerService o FusedLocationProvider, questa stima è accurata entro circa 3 chilometri quadrati. La tua app può ricevere le posizioni con questo livello di precisione quando dichiari l'autorizzazione ACCESS_COARSE_LOCATION, ma non l'autorizzazione ACCESS_FINE_LOCATION.
Esatta
Fornisce una stima della posizione del dispositivo più accurata possibile. Se la stima della posizione è riferita a LocationManagerService o FusedLocationProvider, questa stima corrisponde in genere a circa 50 metri (160 piedi) e a volte è più precisa quanto pochi metri (10 piedi) o migliore. La tua app può ricevere le località con questo livello di precisione quando dichiari l'autorizzazione ACCESS_FINE_LOCATION.

Se l'utente concede l'autorizzazione di accesso alla posizione approssimativa, la tua app ha accesso soltanto alla posizione approssimativa, indipendentemente dalle autorizzazioni di accesso alla posizione dichiarate dall'app.

La tua app dovrebbe continuare a funzionare se l'utente concede solo l'accesso alla posizione approssimativa. Se una funzionalità della tua app richiede assolutamente l'accesso alla posizione esatta utilizzando l'autorizzazione ACCESS_FINE_LOCATION, puoi chiedere all'utente di consentire alla tua app di accedere alla posizione esatta.

Richiedi l'accesso alla posizione in fase di runtime

Quando una funzionalità della tua app richiede l'accesso alla posizione, attendi che l'utente interagisca con la funzionalità prima di effettuare la richiesta di autorizzazione. Questo flusso di lavoro segue la best practice per la richiesta delle autorizzazioni di runtime nel contesto, come descritto nella guida che spiega come richiedere le autorizzazioni app.

La figura 1 mostra un esempio di come eseguire questo processo. L'app contiene una funzionalità di "Condividi posizione" che richiede l'accesso alla posizione in primo piano. Tuttavia, l'app non richiede l'autorizzazione di accesso alla posizione finché l'utente non seleziona il pulsante Condividi posizione.

Dopo che l&#39;utente seleziona il pulsante Condividi posizione, viene visualizzata la finestra di dialogo dell&#39;autorizzazione di accesso alla posizione del sistema
Figura 1. La funzionalità di condivisione della posizione che richiede l'accesso alla posizione in primo piano. La funzionalità viene attivata se l'utente seleziona Consenti solo mentre l'app è in uso.

L'utente può concedere solo la posizione approssimativa

Su Android 12 (livello API 31) o versioni successive, gli utenti possono richiedere che l'app recuperi solo le informazioni sulla posizione approssimativa, anche quando richiede l'autorizzazione di runtime ACCESS_FINE_LOCATION.

Per gestire questo potenziale comportamento degli utenti, non richiedere autonomamente l'autorizzazione ACCESS_FINE_LOCATION. Richiedi invece sia l'autorizzazione ACCESS_FINE_LOCATION sia l'autorizzazione ACCESS_COARSE_LOCATION in un'unica richiesta di runtime. Se provi a richiedere solo ACCESS_FINE_LOCATION, il sistema ignora la richiesta su alcune release di Android 12. Se la tua app ha come target Android 12 o versioni successive, il sistema registra il seguente messaggio di errore in Logcat:

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

Quando la tua app richiede sia ACCESS_FINE_LOCATION sia ACCESS_COARSE_LOCATION, la finestra di dialogo delle autorizzazioni di sistema include le seguenti opzioni per l'utente:

  • Esatta. Consente all'app di ottenere informazioni sulla posizione esatta.
  • Approssimativa. Consente all'app di ricevere soltanto informazioni sulla posizione approssimativa.

La Figura 3 mostra che la finestra di dialogo contiene un segnale visivo per entrambe le opzioni, per aiutare l'utente a scegliere. Dopo aver deciso la precisione della posizione, l'utente tocca uno dei tre pulsanti per selezionare la durata della concessione dell'autorizzazione.

Su Android 12 e versioni successive, gli utenti possono accedere alle impostazioni di sistema per impostare la precisione della posizione preferita per qualsiasi app, indipendentemente dalla versione dell'SDK target dell'app. Questo vale anche quando la tua app è installata su un dispositivo con Android 11 o versioni precedenti e successivamente l'utente esegue l'upgrade del dispositivo ad Android 12 o versioni successive.

La finestra di dialogo si riferisce solo alla posizione approssimativa e contiene tre pulsanti, uno sopra l&#39;altro
Figura 2. La finestra di dialogo delle autorizzazioni di sistema che viene visualizzata quando la tua app richiede solo ACCESS_COARSE_LOCATION.
La finestra di dialogo contiene due serie di opzioni, una sopra l&#39;altra
Figura 3. Finestra di dialogo delle autorizzazioni di sistema che viene visualizzata quando la tua app richiede sia ACCESS_FINE_LOCATION sia ACCESS_COARSE_LOCATION in un'unica richiesta di runtime.

La scelta dell'utente influisce sulle concessioni di autorizzazioni

La tabella seguente mostra le autorizzazioni che il sistema concede alla tua app, in base alle opzioni scelte dall'utente nella finestra di dialogo di runtime delle autorizzazioni:

Esatta Approssimativa
Mentre usi l'app ACCESS_FINE_LOCATION e
ACCESS_COARSE_LOCATION
ACCESS_COARSE_LOCATION
Solo questa volta ACCESS_FINE_LOCATION e
ACCESS_COARSE_LOCATION
ACCESS_COARSE_LOCATION
Rifiuta Nessuna autorizzazione di accesso alla posizione Nessuna autorizzazione di accesso alla posizione

Per determinare quali autorizzazioni sono state concesse dal sistema alla tua app, controlla il valore restituito della richiesta di autorizzazioni. Puoi utilizzare le librerie Jetpack in un codice simile al seguente oppure puoi usare le librerie della piattaforma in cui gestisci autonomamente il codice della richiesta di autorizzazione.

Kotlin

val locationPermissionRequest = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        when {
            permissions.getOrDefault(Manifest.permission.ACCESS_FINE_LOCATION, false) -> {
                // Precise location access granted.
            }
            permissions.getOrDefault(Manifest.permission.ACCESS_COARSE_LOCATION, false) -> {
                // Only approximate location access granted.
            } else -> {
                // No location access granted.
            }
        }
    }

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(arrayOf(
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION))

Java

ActivityResultLauncher<String[]> locationPermissionRequest =
    registerForActivityResult(new ActivityResultContracts
        .RequestMultiplePermissions(), result -> {
            Boolean fineLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_FINE_LOCATION, false);
            Boolean coarseLocationGranted = result.getOrDefault(
                    Manifest.permission.ACCESS_COARSE_LOCATION,false);
            if (fineLocationGranted != null && fineLocationGranted) {
                // Precise location access granted.
            } else if (coarseLocationGranted != null && coarseLocationGranted) {
                // Only approximate location access granted.
            } else {
                // No location access granted.
            }
        }
    );

// ...

// Before you perform the actual permission request, check whether your app
// already has the permissions, and whether your app needs to show a permission
// rationale dialog. For more details, see Request permissions.
locationPermissionRequest.launch(new String[] {
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.ACCESS_COARSE_LOCATION
});

Richiedi un upgrade alla posizione esatta

Puoi chiedere all'utente di eseguire l'upgrade dell'accesso della tua app dalla posizione approssimativa alla posizione esatta. Prima di chiedere all'utente di eseguire l'upgrade dell'accesso della tua app alla posizione esatta, valuta se il caso d'uso della tua app richiede assolutamente questo livello di precisione. Se la tua app deve accoppiare un dispositivo con dispositivi nelle vicinanze tramite Bluetooth o Wi-Fi, potresti utilizzare l'accoppiamento di dispositivi associati o le autorizzazioni Bluetooth, anziché richiedere l'autorizzazione ACCESS_FINE_LOCATION.

Per richiedere all'utente di eseguire l'upgrade dell'accesso alla posizione della tua app da approssimativa a esatta, segui questi passaggi:

  1. Se necessario, spiega il motivo per cui la tua app ha bisogno dell'autorizzazione.
  2. Richiedi di nuovo le autorizzazioni ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION insieme. Poiché l'utente ha già consentito al sistema di concedere la posizione approssimativa alla tua app, questa volta la finestra di dialogo del sistema è diversa, come mostrato nella Figura 4 e nella Figura 5:
La finestra di dialogo contiene le opzioni &quot;Passa alla posizione esatta&quot;, &quot;Solo questa volta&quot; e &quot;Rifiuta&quot;.
Figura 4. L'utente in precedenza ha selezionato Approssimativa e Mentre usa l'app (nella finestra di dialogo della Figura 3).
La finestra di dialogo contiene le opzioni &quot;Solo questa volta&quot; e &quot;Rifiuta&quot;.
Figura 5. L'utente in precedenza ha selezionato Approssimativa e Solo questa volta (nella finestra di dialogo della Figura 3).

Richiedi inizialmente solo la posizione in primo piano

Anche se diverse funzionalità della tua app richiedono l'accesso alla posizione, è probabile che solo alcune di queste richiedano l'accesso alla posizione in background. Di conseguenza, ti consigliamo di eseguire richieste incrementali per le autorizzazioni di accesso alla posizione, che richiedono l'accesso alla posizione in primo piano e poi l'accesso alla posizione in background. Eseguendo richieste incrementali, offri agli utenti maggiore controllo e trasparenza perché possono capire meglio quali funzionalità della tua app richiedono l'accesso alla posizione in background.

La Figura 6 mostra un esempio di app progettata per gestire le richieste incrementali. Le funzionalità "Mostra posizione attuale" e "Consiglia luoghi nelle vicinanze" richiedono l'accesso alla posizione in primo piano. Tuttavia, solo la funzione "Consiglia luoghi nelle vicinanze" richiede l'accesso alla posizione in background.

Il pulsante che consente l&#39;accesso alla posizione in primo piano è posizionato a metà dello schermo di distanza dal pulsante che consente la posizione in background
Figura 6. Entrambe le funzionalità richiedono l'accesso alla posizione, ma solo la funzionalità "Consiglia funzionalità nelle vicinanze" richiede l'accesso alla posizione in background.

Il processo per l'esecuzione di richieste incrementali è il seguente:

  1. Inizialmente, l'app deve indirizzare gli utenti verso le funzionalità che richiedono l'accesso alla posizione in primo piano, ad esempio la funzionalità "Condividi la posizione" nella Figura 1 o la funzionalità "Mostra la posizione attuale" nella Figura 2.

    Ti consigliamo di disattivare l'accesso degli utenti alle funzionalità che richiedono l'accesso alla posizione in background finché l'app non avrà accesso alla posizione in primo piano.

  2. In un secondo momento, quando l'utente esplora funzionalità che richiedono l'accesso alla posizione in background, puoi richiedere l'accesso alla posizione in background.

Richiedere la posizione in background, se necessario

Figura 7. La pagina Impostazioni include un'opzione denominata Consenti sempre, che concede l'accesso alla posizione in background.

I contenuti delle finestre di dialogo delle autorizzazioni dipendono dalla versione dell'SDK di destinazione

Quando una funzionalità della tua app richiede la posizione in background su un dispositivo che esegue Android 10 (livello API 29), la finestra di dialogo delle autorizzazioni di sistema include un'opzione denominata Consenti sempre. Se l'utente seleziona questa opzione, la funzionalità dell'app ottiene l'accesso alla posizione in background.

Su Android 11 (livello API 30) e versioni successive, tuttavia, la finestra di dialogo di sistema non include l'opzione Consenti sempre. Gli utenti devono attivare la posizione in background in una pagina delle impostazioni, come mostrato nella Figura 7.

Puoi aiutare gli utenti a raggiungere questa pagina delle impostazioni seguendo le best practice per richiedere l'autorizzazione di accesso alla posizione in background. La procedura per concedere l'autorizzazione dipende dalla versione dell'SDK target dell'app.

L'app ha come target Android 11 o versioni successive

Se alla tua app non è stata concessa l'autorizzazione ACCESS_BACKGROUND_LOCATION e shouldShowRequestPermissionRationale() restituisce true, mostra agli utenti un'interfaccia utente didattica che includa quanto segue:

  • Una spiegazione chiara del motivo per cui la funzionalità dell'app richiede l'accesso alla posizione in background.
  • L'etichetta visibile all'utente dell'opzione delle impostazioni che concede la posizione in background (ad esempio, Consenti sempre nella figura 7). Puoi chiamare getBackgroundPermissionOptionLabel() per ottenere questa etichetta. Il valore restituito di questo metodo è localizzato in base alla preferenza della lingua del dispositivo dell'utente.
  • Un'opzione che consente agli utenti di negare l'autorizzazione. Se gli utenti rifiutano l'accesso alla posizione in background, devono essere in grado di continuare a utilizzare la tua app.
Gli utenti possono toccare la notifica di sistema per modificare le impostazioni di geolocalizzazione di un&#39;app
Figura 8. Notifica che ricorda all'utente che ha concesso a un'app l'accesso alla posizione in background.

L'app ha come target Android 10 o versioni precedenti

Quando una funzionalità dell'app richiede l'accesso alla posizione in background, gli utenti visualizzano una finestra di dialogo di sistema. Questa finestra di dialogo include un'opzione per accedere alle opzioni dell'autorizzazione di accesso alla posizione della tua app in una pagina delle impostazioni.

Se la tua app segue già le best practice per richiedere le autorizzazioni di accesso alla posizione, non è necessario apportare modifiche per supportare questo comportamento.

L'utente può influire sulla precisione della posizione in background

Se l'utente richiede la posizione approssimativa, le scelte dell'utente nella finestra di dialogo delle autorizzazioni di accesso alla posizione si applicano anche alla posizione in background. In altre parole, se l'utente concede alla tua app l'autorizzazione ACCESS_BACKGROUND_LOCATION, ma solo l'accesso alla posizione approssimativa in primo piano, anche la tua app ha accesso solo alla posizione approssimativa in background.

Promemoria per concessione posizione in background

Su Android 10 e versioni successive, quando una funzionalità della tua app accede alla posizione del dispositivo in background per la prima volta dopo che l'utente ha concesso l'accesso alla posizione in background, il sistema pianifica una notifica da inviare all'utente. Questa notifica ricorda all'utente che ha sempre consentito alla tua app di accedere alla posizione del dispositivo. Nella figura 8 viene visualizzata una notifica di esempio.

Verifica i requisiti di località nelle dipendenze dell'SDK della tua app

Controlla se la tua app utilizza SDK che dipendono dalle autorizzazioni di accesso alla posizione, in particolare dall'autorizzazione ACCESS_FINE_LOCATION. Consulta questo articolo su Medium Informazioni su Imparare a conoscere i comportamenti delle dipendenze SDK.

Risorse aggiuntive

Per ulteriori informazioni sulle autorizzazioni di accesso alla posizione in Android, visualizza i seguenti materiali:

Codelab

Video

Campioni

  • App di esempio per dimostrare l'uso delle autorizzazioni di accesso alla posizione.