Location Data

Una delle funzionalità uniche delle applicazioni mobile è la conoscenza della posizione. Gli utenti mobile portano con sé i propri dispositivi ovunque e l'aggiunta della conoscenza della posizione alla tua app offre loro un'esperienza più contestuale.

Esempi di codice

Il repository ApiDemos su GitHub include esempi che mostrano l'utilizzo della posizione su una mappa:

Kotlin

Java

Utilizzo dei dati sulla posizione

I dati sulla posizione disponibili per un dispositivo Android includono la posizione attuale del dispositivo, individuata utilizzando una combinazione di tecnologie, la direzione e il metodo di movimento e se il dispositivo ha attraversato un confine geografico predefinito o un recinto virtuale. A seconda delle esigenze della tua applicazione, puoi scegliere tra diversi modi di lavorare con i dati sulla posizione:

  • Il livello La mia posizione offre un modo semplice per visualizzare la posizione di un dispositivo sulla mappa. Non fornisce dati.
  • L'API di geolocalizzazione di Google Play Services è consigliata per tutte le richieste programmatiche di dati sulla posizione.
  • L'interfaccia LocationSource ti consente di fornire un provider di posizione personalizzato.

Autorizzazioni di accesso alla posizione

Se la tua app deve accedere alla posizione dell'utente, devi richiedere l'autorizzazione aggiungendo le relative autorizzazioni di accesso alla posizione di Android alla tua app.

Android offre due autorizzazioni di accesso alla posizione: ACCESS_COARSE_LOCATION e ACCESS_FINE_LOCATION. L'autorizzazione scelta determina l'accuratezza della posizione restituita dall'API.

Aggiungi le autorizzazioni al manifest dell'app

Se per il funzionamento della tua app è necessaria solo la posizione approssimativa, aggiungi l'autorizzazione ACCESS_COARSE_LOCATION al file manifest dell'app:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp" >
  ...
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  ...
</manifest>

Tuttavia, se è necessaria la posizione esatta, aggiungi entrambe le autorizzazioni ACCESS_COARSE_LOCATION e ACCESS_FINE_LOCATION al file manifest della tua app:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp" >
  ...
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  ...
</manifest>

Richiedi autorizzazioni di runtime

Android 6.0 (Marshmallow) introduce un nuovo modello per la gestione delle autorizzazioni, che semplifica la procedura per gli utenti quando installano ed eseguono l'upgrade delle app. Se la tua app ha come target il livello API 23 o versioni successive, puoi utilizzare il nuovo modello di autorizzazioni.

Se la tua app supporta il nuovo modello di autorizzazioni e il dispositivo utilizza Android 6.0 (Marshmallow) o versioni successive, l'utente non deve concedere alcuna autorizzazione quando installa o esegue l'upgrade dell'app. L'app deve verificare se dispone dell'autorizzazione necessaria in fase di runtime e richiederla se non ne dispone. Il sistema mostra all'utente una finestra di dialogo che richiede l'autorizzazione.

Per un'esperienza utente ottimale, è importante richiedere l'autorizzazione nel contesto. Se la posizione è essenziale per il funzionamento della tua app, devi richiedere l'autorizzazione di accesso alla posizione all'avvio dell'app. Un buon modo per farlo è utilizzare una schermata di benvenuto o una procedura guidata che spieghi agli utenti perché è necessaria l'autorizzazione.

Se l'app richiede l'autorizzazione solo per una parte della sua funzionalità, devi richiedere l'autorizzazione di accesso alla posizione nel momento in cui l'app esegue l'azione che richiede l'autorizzazione.

L'app deve gestire correttamente il caso in cui l'utente non conceda l'autorizzazione. Ad esempio, se l'autorizzazione è necessaria per una funzionalità specifica, l'app può disattivarla. Se l'autorizzazione è essenziale per il funzionamento dell'app, quest'ultima può disattivare tutte le sue funzionalità e informare l'utente che deve concedere l'autorizzazione.

Il seguente esempio di codice verifica l'autorizzazione utilizzando la libreria AndroidX prima di attivare il livello La mia posizione. Quindi, gestisce il risultato della richiesta di autorizzazione implementando ActivityCompat.OnRequestPermissionsResultCallback dalla libreria di assistenza:

Kotlin

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.example.kotlindemos

import android.Manifest
import android.annotation.SuppressLint
import android.content.pm.PackageManager
import android.location.Location
import android.os.Bundle
import android.view.View
import android.widget.Toast
import androidx.core.app.ActivityCompat
import androidx.core.app.ActivityCompat.OnRequestPermissionsResultCallback
import androidx.core.content.ContextCompat
import com.example.common_ui.R
import com.example.common_ui.catalog.Complexity
import com.example.common_ui.catalog.Framework
import com.example.common_ui.catalog.Sample
import com.example.kotlindemos.PermissionUtils.PermissionDeniedDialog.Companion.newInstance
import com.example.kotlindemos.PermissionUtils.isPermissionGranted
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.GoogleMap.OnMyLocationButtonClickListener
import com.google.android.gms.maps.GoogleMap.OnMyLocationClickListener
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment

/**
 * This demo shows how GMS Location can be used to check for changes to the users location.  The
 * "My Location" button uses GMS Location to set the blue dot representing the users location.
 * Permission for [Manifest.permission.ACCESS_FINE_LOCATION] and [Manifest.permission.ACCESS_COARSE_LOCATION]
 * are requested at run time. If either permission is not granted, the Activity is finished with an error message.
 */
@Sample(
    id = "com.example.kotlindemos.MyLocationDemoActivity",
    title = "My Location Layer",
    description = "Enabling blue dot location indicator and My Location button with runtime permissions.",
    category = "Location & Sensors",
    complexity = Complexity.SIMPLE,
    tags = ["#location", "#mylocation", "#permissions", "#bluedot"],
    purpose = "Demonstrates requesting ACCESS_FINE_LOCATION permissions and enabling the blue dot location layer.",
    successCriteria = "Tapping My Location button centers camera on user's current GPS position.",
    failureIndicators = "Permission denial causes unhandled crash or location button missing.",
    framework = Framework.KOTLIN_VIEWS,
)
class MyLocationDemoActivity :
    SamplesBaseActivity(),
    OnMyLocationButtonClickListener,
    OnMyLocationClickListener,
    OnMapReadyCallback,
    OnRequestPermissionsResultCallback {
    /**
     * Flag indicating whether a requested permission has been denied after returning in
     * [.onRequestPermissionsResult].
     */
    private var permissionDenied = false
    private lateinit var map: GoogleMap
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.my_location_demo)
        val mapFragment =
            supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment?
        mapFragment?.getMapAsync(this)
        applyInsets(findViewById(R.id.map_container))
    }

    override fun onMapReady(googleMap: GoogleMap) {
        map = googleMap
        googleMap.setOnMyLocationButtonClickListener(this)
        googleMap.setOnMyLocationClickListener(this)
        enableMyLocation()
    }

    /**
     * Enables the My Location layer if the fine location permission has been granted.
     */
    @SuppressLint("MissingPermission")
    private fun enableMyLocation() {
        // 1. Check if permissions are granted, if so, enable the my location layer
        if (ContextCompat.checkSelfPermission(
                this,
                Manifest.permission.ACCESS_FINE_LOCATION,
            ) == PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission(
                this,
                Manifest.permission.ACCESS_COARSE_LOCATION,
            ) == PackageManager.PERMISSION_GRANTED
        ) {
            map.isMyLocationEnabled = true
            return
        }

        // 2. If if a permission rationale dialog should be shown
        if (ActivityCompat.shouldShowRequestPermissionRationale(
                this,
                Manifest.permission.ACCESS_FINE_LOCATION,
            ) || ActivityCompat.shouldShowRequestPermissionRationale(
                this,
                Manifest.permission.ACCESS_COARSE_LOCATION,
            )
        ) {
            PermissionUtils.RationaleDialog.newInstance(
                LOCATION_PERMISSION_REQUEST_CODE,
                true,
            ).show(supportFragmentManager, "dialog")
            return
        }

        // 3. Otherwise, request permission
        ActivityCompat.requestPermissions(
            this,
            arrayOf(
                Manifest.permission.ACCESS_FINE_LOCATION,
                Manifest.permission.ACCESS_COARSE_LOCATION,
            ),
            LOCATION_PERMISSION_REQUEST_CODE,
        )
    }

    override fun onMyLocationButtonClick(): Boolean {
        Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT)
            .show()
        // Return false so that we don't consume the event and the default behavior still occurs
        // (the camera animates to the user's current position).
        return false
    }

    override fun onMyLocationClick(location: Location) {
        Toast.makeText(this, "Current location:\n$location", Toast.LENGTH_LONG)
            .show()
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
        if (requestCode != LOCATION_PERMISSION_REQUEST_CODE) {
            super.onRequestPermissionsResult(
                requestCode,
                permissions,
                grantResults,
            )
            return
        }

        if (isPermissionGranted(
                permissions,
                grantResults,
                Manifest.permission.ACCESS_FINE_LOCATION,
            ) || isPermissionGranted(
                permissions,
                grantResults,
                Manifest.permission.ACCESS_COARSE_LOCATION,
            )
        ) {
            // Enable the my location layer if the permission has been granted.
            enableMyLocation()
        } else {
            // Permission was denied. Display an error message
            // Display the missing permission error dialog when the fragments resume.
            permissionDenied = true
        }
    }

    override fun onResumeFragments() {
        super.onResumeFragments()
        if (permissionDenied) {
            // Permission was not granted, display error dialog.
            showMissingPermissionError()
            permissionDenied = false
        }
    }

    /**
     * Displays a dialog with error message explaining that the location permission is missing.
     */
    private fun showMissingPermissionError() {
        newInstance(true).show(supportFragmentManager, "dialog")
    }

    companion object {
        /**
         * Request code for location permission request.
         *
         * @see .onRequestPermissionsResult
         */
        private const val LOCATION_PERMISSION_REQUEST_CODE = 1
    }
}

Java

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.example.mapdemo;

import android.Manifest;
import android.Manifest.permission;
import android.annotation.SuppressLint;
import android.content.pm.PackageManager;
import android.location.Location;
import android.os.Bundle;
import android.widget.Toast;
import androidx.annotation.NonNull;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import com.example.common_ui.catalog.Complexity;
import com.example.common_ui.catalog.Framework;
import com.example.common_ui.catalog.Sample;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.GoogleMap.OnMyLocationButtonClickListener;
import com.google.android.gms.maps.GoogleMap.OnMyLocationClickListener;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;

/**
 * This demo shows how GMS Location can be used to check for changes to the users location. The "My
 * Location" button uses GMS Location to set the blue dot representing the users location.
 * Permission for {@link android.Manifest.permission#ACCESS_FINE_LOCATION} and {@link
 * android.Manifest.permission#ACCESS_COARSE_LOCATION} are requested at run time. If either
 * permission is not granted, the Activity is finished with an error message.
 */
@Sample(
        id = "my_location",
        title = "My Location Layer",
        description =
                "Enabling blue dot location indicator and My Location button with runtime permissions.",
        category = "Location & Sensors",
        complexity = Complexity.SIMPLE,
        tags = {"#location", "#mylocation", "#permissions", "#bluedot"},
        purpose =
                "Demonstrates requesting ACCESS_FINE_LOCATION permissions and enabling the blue dot location layer.",
        successCriteria =
                "Tapping My Location button centers camera on user's current GPS position.",
        failureIndicators = "Permission denial causes unhandled crash or location button missing.",
        framework = Framework.JAVA_VIEWS)
public class MyLocationDemoActivity extends SamplesBaseActivity
        implements OnMyLocationButtonClickListener,
                OnMyLocationClickListener,
                OnMapReadyCallback,
                ActivityCompat.OnRequestPermissionsResultCallback {

    /**
     * Request code for location permission request.
     *
     * @see #onRequestPermissionsResult(int, String[], int[])
     */
    private static final int LOCATION_PERMISSION_REQUEST_CODE = 1;

    /**
     * Flag indicating whether a requested permission has been denied after returning in {@link
     * #onRequestPermissionsResult(int, String[], int[])}.
     */
    private boolean permissionDenied = false;

    private GoogleMap map;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(com.example.common_ui.R.layout.my_location_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment)
                        getSupportFragmentManager()
                                .findFragmentById(com.example.common_ui.R.id.map);
        mapFragment.getMapAsync(this);
        applyInsets(findViewById(com.example.common_ui.R.id.map_container));
    }

    @Override
    public void onMapReady(@NonNull GoogleMap googleMap) {
        map = googleMap;
        map.setOnMyLocationButtonClickListener(this);
        map.setOnMyLocationClickListener(this);
        enableMyLocation();
    }

    /** Enables the My Location layer if the fine location permission has been granted. */
    @SuppressLint("MissingPermission")
    private void enableMyLocation() {
        // 1. Check if permissions are granted, if so, enable the my location layer
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)
                        == PackageManager.PERMISSION_GRANTED
                || ContextCompat.checkSelfPermission(this, permission.ACCESS_COARSE_LOCATION)
                        == PackageManager.PERMISSION_GRANTED) {
            map.setMyLocationEnabled(true);
            return;
        }

        // 2. Otherwise, request location permissions from the user.
        PermissionUtils.requestLocationPermissions(this, LOCATION_PERMISSION_REQUEST_CODE, true);
    }

    @Override
    public boolean onMyLocationButtonClick() {
        Toast.makeText(this, "MyLocation button clicked", Toast.LENGTH_SHORT).show();
        // Return false so that we don't consume the event and the default behavior still occurs
        // (the camera animates to the user's current position).
        return false;
    }

    @Override
    public void onMyLocationClick(@NonNull Location location) {
        Toast.makeText(this, "Current location:\n" + location, Toast.LENGTH_LONG).show();
    }

    @Override
    public void onRequestPermissionsResult(
            int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
        if (requestCode != LOCATION_PERMISSION_REQUEST_CODE) {
            super.onRequestPermissionsResult(requestCode, permissions, grantResults);
            return;
        }

        if (PermissionUtils.isPermissionGranted(
                        permissions, grantResults, Manifest.permission.ACCESS_FINE_LOCATION)
                || PermissionUtils.isPermissionGranted(
                        permissions, grantResults, Manifest.permission.ACCESS_COARSE_LOCATION)) {
            // Enable the my location layer if the permission has been granted.
            enableMyLocation();
        } else {
            // Permission was denied. Display an error message
            // Display the missing permission error dialog when the fragments resume.
            permissionDenied = true;
        }
    }


    @Override
    protected void onResumeFragments() {
        super.onResumeFragments();
        if (permissionDenied) {
            // Permission was not granted, display error dialog.
            showMissingPermissionError();
            permissionDenied = false;
        }
    }

    /** Displays a dialog with error message explaining that the location permission is missing. */
    private void showMissingPermissionError() {
        PermissionUtils.PermissionDeniedDialog.newInstance(true)
                .show(getSupportFragmentManager(), "dialog");
    }
}

Il livello La mia posizione

Puoi utilizzare il livello La mia posizione e il pulsante La mia posizione per mostrare all'utente la sua posizione attuale sulla mappa. Chiama mMap.setMyLocationEnabled() per attivare il livello La mia posizione sulla mappa.

L'esempio seguente mostra un utilizzo semplice del livello La mia posizione:

Kotlin

// TODO: Before enabling the My Location layer, you must request
// location permission from the user. This sample does not include
// a request for location permission.
map.setMyLocationEnabled(true)
map.setOnMyLocationButtonClickListener {
    Toast.makeText(context, "MyLocation button clicked", Toast.LENGTH_SHORT).show()
    // Return false so that we don't consume the event and the default behavior still occurs
    // (the camera animates to the user's current position).
    false
}
map.setOnMyLocationClickListener { location ->
    Toast.makeText(context, "Current location:\n$location", Toast.LENGTH_LONG).show()
}

Java

// TODO: Before enabling the My Location layer, you must request
// location permission from the user. This sample does not include
// a request for location permission.
map.setMyLocationEnabled(true);
map.setOnMyLocationButtonClickListener(
        new GoogleMap.OnMyLocationButtonClickListener() {
            @Override
            public boolean onMyLocationButtonClick() {
                Toast.makeText(context, "MyLocation button clicked", Toast.LENGTH_SHORT)
                        .show();
                // Return false so that we don't consume the event and the default behavior
                // still occurs
                // (the camera animates to the user's current position).
                return false;
            }
        });
map.setOnMyLocationClickListener(
        new GoogleMap.OnMyLocationClickListener() {
            @Override
            public void onMyLocationClick(@NonNull Location location) {
                Toast.makeText(context, "Current location:\n" + location, Toast.LENGTH_LONG)
                        .show();
            }
        });

Quando il livello La mia posizione è attivo, il pulsante Posizione viene visualizzato nell'angolo in alto a destra della mappa. Quando un utente fa clic sul pulsante, la fotocamera centra la mappa sulla posizione attuale del dispositivo, se nota. La posizione è indicata sulla mappa da un piccolo punto blu se il dispositivo è fermo o da un simbolo di spunta se il dispositivo è in movimento.

Lo screenshot seguente mostra il pulsante posizione in alto a destra e il punto blu La mia posizione al centro della mappa:

Puoi impedire la visualizzazione del pulsante Posizione chiamando UiSettings.setMyLocationButtonEnabled(false).

La tua app può rispondere ai seguenti eventi:

L'API di geolocalizzazione di Google Play Services

L'API di geolocalizzazione di Google Play Services è il metodo preferito per aggiungere la conoscenza della posizione alla tua app per Android. Include funzionalità che ti consentono di:

  • Determinare la posizione del dispositivo.
  • Rilevamento modifiche della posizione.
  • Determina il mezzo di trasporto, se il dispositivo è in movimento.
  • Crea e monitora regioni geografiche predefinite, note come geofence.

Le API di geolocalizzazione ti consentono di creare facilmente applicazioni con conoscenza della posizione a basso consumo energetico. Come Maps SDK for Android, l'API di geolocalizzazione viene distribuita nell'ambito dell'SDK Google Play Services. Per ulteriori informazioni sull'API di geolocalizzazione, consulta il corso di formazione per Android Rendi la tua app sensibile alla posizione o il Riferimento API di geolocalizzazione. Gli esempi di codice sono inclusi nell'SDK Google Play Services.