API di Google Maps su Wear OS

Una mappa su un dispositivo indossabile

Con l'SDK Maps per Android, puoi creare un'app per dispositivi indossabili basata su mappe che viene eseguita direttamente sui dispositivi Wear OS by Google. Gli utenti della tua app possono vedere la loro posizione sulla mappa semplicemente guardando il polso. Possono tracciare la posizione su un percorso, ad esempio, aumentare lo zoom per visualizzare i dettagli o toccare un indicatore per visualizzare una finestra informativa fornita dalla tua app.

Questa pagina descrive le funzionalità dell'API disponibili su un dispositivo indossabile e ti aiuta a iniziare a creare l'app.

Guida introduttiva a Wear OS

Creare un'app indossabile con l'SDK Maps per Android è fondamentalmente la stessa di un'altra app Google Maps. La differenza sta nel design per il fattore di forma più piccolo del dispositivo indossabile, per ottimizzare l'usabilità e le prestazioni dell'app.

Android Studio è lo strumento consigliato per lo sviluppo di Wear OS, in quanto offre configurazione del progetto, inclusione della raccolta e pratiche di pacchetto.

Per assistenza generica sulla progettazione di un'app indossabile, consulta le linee guida per la progettazione di Wear OS. Per assistenza sulla creazione della tua prima app indossabile, consulta la guida alla creazione di app indossabili.

Creare la tua prima app Maps su Wear OS

Questa guida rapida presuppone che tu abbia dimestichezza con l'SDK Maps per Android, che tu abbia seguito le guide di Wear OS per creare un modulo indossabile nella tua app e che voglia aggiungere una mappa al modulo indossabile.

Aggiungere dipendenze per il modulo di usura

Assicurati di includere le seguenti dipendenze nel file build.gradle del modulo Wear OS dell'app:

dependencies {
    // ...
    compileOnly 'com.google.android.wearable:wearable:2.9.0'
    implementation 'com.google.android.support:wearable:2.9.0'
    implementation 'com.google.android.gms:play-services-maps:18.0.2'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.2.0'
}

Per ulteriori informazioni sulle dipendenze, consulta la guida all'aggiunta di un modulo Wear OS nel progetto esistente.

Implementare un gesto di scorrimento per ignorare e impostare il colore di sfondo iniziale

Si consiglia di utilizzare un SwipeDismissFrameLayout per visualizzare la mappa sul dispositivo indossabile. Utilizzando la classe SwipeDismissFrameLayout, puoi implementare il gesto scorri verso il basso per offrire agli utenti un modo per uscire dall'app scorrendo dal bordo più a sinistra dello schermo.

Per impostare un colore di sfondo iniziale personalizzato, utilizza l'attributo XML map:backgroundColor per definire il colore da visualizzare fino al caricamento dei riquadri della mappa effettivi.

Aggiungi gli elementi SwipeDismissFrameLayout e backgroundColor alla definizione del layout come contenitore di SupportMapFragment:

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

Quando ottieni l'oggetto SwipeDismissFrameLayout nella tua attività, aggiungi un callback e imposta il comportamento del callback per eseguire l'azione necessaria per ignorare, come mostrato di seguito:

Java


public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {


    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {


    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

Aggiungere una mappa

Utilizza il metodo di callback onMapReady(GoogleMap) come di consueto, per ricevere un handle all'oggetto GoogleMap. Il callback viene attivato quando la mappa è pronta per essere utilizzata. Nel metodo di callback, puoi aggiungere indicatori o polilinee alla mappa, aggiungere ascoltatori o spostare la videocamera. Nell'esempio seguente viene aggiunto un indicatore vicino al Teatro dell'Opera di Sydney:

Java


private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

Kotlin


private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

Attivazione della modalità Ambient

L'SDK Maps per Android supporta la modalità Ambient per le app indossabili. Le app che supportano la modalità Ambient sono chiamate a volte app sempre attive. La modalità Ambient viene attivata quando l'utente non usa più attivamente l'app e consente all'app di rimanere visibile sul dispositivo indossabile.

L'SDK Maps per Android fornisce una visualizzazione semplificata a colori della mappa da utilizzare in modalità Ambient e lo stile mappa si regola automaticamente quando il dispositivo passa dalla modalità interattiva alla modalità Ambient. Tutti gli indicatori, gli oggetti e i controlli dell'interfaccia utente scompaiono in modalità Ambient. In questo modo si riduce il consumo energetico dell'app e si assicura un aspetto e uno stile coerenti con altre app ambientali, come i quadranti.

Per assicurarti che l'app utilizzi la modalità Ambient della mappa:

  1. Aggiorna l'SDK Android in modo da includere la piattaforma Android 6.0 (API 23) o versioni successive, che fornisce le API che consentono l'attivazione della modalità Ambient per le attività. Per informazioni su come aggiornare l'SDK, consulta la documentazione Android sull'aggiunta di pacchetti SDK.
  2. Assicurati che il tuo progetto abbia come target Android 6.0 o versioni successive, impostando il valore di targetSdkVersion su 23 o versioni successive nel file manifest dell'app.
  3. Aggiungi le dipendenze indossabili al file build.gradle dell'app. Visualizza l'esempio in questa pagina.
  4. Aggiungi la voce della libreria condivisa indossabile al manifest dell'app indossabile, come descritto nella lezione di formazione Android su come mantenere visibile l'app.
  5. Aggiungi l'autorizzazione WAKE_LOCK ai manifest dell'app portatile e indossabile, come descritto nella lezione di formazione di Android su come rendere visibile l'app.
  6. Nel metodo onCreate() della tua attività, chiama il metodo AmbientModeSupport.attach(). Questo indica al sistema operativo che l'applicazione è sempre attiva, in modo che, quando il dispositivo si spegne, dovrebbe entrare in modalità Ambient anziché tornare al quadrante.
  7. Implementa l'interfaccia AmbientModeSupport.AmbientCallbackProvider in Attività in modo che possa ricevere i cambiamenti di stato della modalità Ambient.
  8. Imposta la mappa per supportare la modalità Ambient. A tale scopo, imposta l'attributo map:ambientEnabled="true" nel file di layout XML dell'attività oppure, in modo programmatico, impostando GoogleMapOptions.ambientEnabled(true). Questa impostazione informa l'API che deve precaricare i riquadri della mappa necessari per l'utilizzo in modalità Ambient.
  9. Quando l'attività passa alla modalità Ambient, il sistema chiama il metodo onEnterAmbient() nella classe AmbientCallback da te fornita. Sostituisci onEnterAmbient() e chiama SupportMapFragment.onEnterAmbient(ambientDetails) o MapView.onEnterAmbient(ambientDetails). L'API passa a un rendering non interattivo e a colori della mappa.
  10. Analogamente, in onExitAmbient() chiama SupportMapFragment.onExitAmbient() o MapView.onExitAmbient(). L'API passa alla visualizzazione normale della mappa.

Il seguente esempio di codice abilita la modalità Ambient nell'attività:

Java


public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

Kotlin


class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

Puoi aggiornare lo schermo quando l'app è in modalità Ambient. Per ulteriori dettagli sull'aggiornamento dei contenuti e sulla modalità Ambient in generale, consulta il corso di formazione Android su come mantenere visibile l'app.

Utilizzo di Street View su Wear OS

Street View è completamente supportato sui dispositivi indossabili.

Per consentire agli utenti di uscire dall'app quando visualizzano un panorama di Street View, utilizza l'interfaccia StreetViewPanorama.OnStreetViewPanoramaLongClickListener per ascoltare un gesto di clic lungo. Quando un utente fa clic prolungati su un punto dell'immagine di Street View, riceverai un evento onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Chiama DismissOverlayView.show() per visualizzare un pulsante di uscita.

Codice di esempio

Su GitHub è disponibile un'app di esempio, che puoi utilizzare come punto di partenza per la tua app. L'esempio mostra come configurare una mappa di base di Google Maps su Wear OS.

Funzionalità supportate nell'API Maps su Wear OS

In questa sezione vengono illustrate le differenze tra le funzionalità supportate per le mappe sui dispositivi indossabili rispetto ai dispositivi portatili (telefoni e tablet). Tutte le funzionalità API non menzionate di seguito dovrebbero funzionare come documentato per l'API completa.

Funzionalità
Modalità completamente interattiva e modalità Lite

Puoi utilizzare l'SDK Maps per Android in modalità completamente interattiva o in modalità Lite. Valuta la modalità Lite se vuoi ottimizzare le prestazioni sul dispositivo indossabile e la tua app non deve supportare l'interazione, ad esempio i gesti, o la panoramica e lo zoom della mappa.

In modalità Lite, l'intento di avviare l'app Google Maps per dispositivi mobili quando l'utente tocca la mappa è disattivato e non può essere attivato su un dispositivo indossabile.

Per un elenco completo delle differenze tra la modalità Lite e la modalità completamente interattiva, consulta la documentazione relativa alla modalità Lite.

Barra degli strumenti Mappa La barra degli strumenti della mappa è disattivata e non può essere attivata su un dispositivo indossabile.
Controlli interfaccia utente Sui dispositivi indossabili, i controlli dell'interfaccia utente sono disattivati per impostazione predefinita. Ciò include lo zoom, la bussola e i controlli di geolocalizzazione. Puoi abilitarli utilizzando la classe UiSettings come di consueto.
Gesti I gesti single-touch funzionano come previsto. Ad esempio, tocca e trascina per eseguire la panoramica della mappa, tocca due volte per aumentare lo zoom e tocca con due dita per diminuire lo zoom. Il supporto varia in base ai gesti multi-touch a seconda del dispositivo utilizzato dall'utente. Ecco alcuni esempi di gesti multi-touch che consentono di premere due dita per inclinare la mappa, pizzicare per eseguire lo zoom e rotazione con due dita.
Mappe ed edifici per interni Le mappe interne sono disattivate per impostazione predefinita su un dispositivo indossabile. Puoi abilitarli chiamando GoogleMap.setIndoorEnabled(true). Se le mappe di interni sono abilitate, verrà visualizzato il livello minimo predefinito. L'elemento UI del selettore di livello non è supportato sui dispositivi indossabili.
Overlay riquadro Gli overlay del riquadro non sono supportati sui dispositivi indossabili.

Best practice per lo sviluppo con l'API di Maps su Wear OS

Come offrire la migliore esperienza utente nella tua app:

  • La mappa dovrebbe occupare gran parte dello schermo. Questo è necessario per ottimizzare l'usabilità della mappa sul fattore di forma ridotto di un dispositivo indossabile.
  • Quando progetti l'esperienza utente della tua app, tieni presente il fatto che la batteria di un dispositivo indossabile è quasi esaurita. Mantenere lo schermo attivo e la mappa visibile incidono sulle prestazioni della batteria.