API di Google Maps su Wear OS

Utilizzando Maps SDK for 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. Ad esempio, possono tracciare la loro posizione su un percorso, quindi ingrandire per visualizzare i dettagli o toccare un indicatore per visualizzare una finestra informativa fornita dalla tua app.

Questa pagina descrive la funzionalità dell'API disponibile su un dispositivo indossabile e ti aiuta a iniziare a creare la tua app.

Iniziare a utilizzare Wear OS

La creazione di un'app per dispositivi indossabili con Maps SDK for Android è fondamentalmente la stessa della creazione di un'app Google Maps per qualsiasi altro dispositivo Android. La differenza sta nella progettazione 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 fornisce praticità per la configurazione del progetto, l'inclusione di librerie e il packaging.

Per assistenza generale con la progettazione di un'app per dispositivi indossabili, consulta le linee guida di progettazione di Wear OS. Per assistenza nella creazione della tua prima app per dispositivi indossabili, consulta la guida alla creazione di app per dispositivi indossabili.

Creare la prima app di mappe su Wear OS

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

Aggiungere le dipendenze per il modulo indossabile

Assicurati che le seguenti dipendenze siano incluse nel file build.gradle.kts del modulo Wear OS della tua app:

dependencies {
    // ...
    // Modern Android projects use version catalogs to manage dependencies.  To include the necessary dependencies,
    // first add the following to your libs.versions.toml file:
    //
    // [versions]
    // playServicesMaps = "20.0.0"
    // wear = "1.3.0"
    // wearable = "2.9.0"
    //
    // [libraries]
    // play-services-maps = { group = "com.google.android.gms", name = "play-services-maps", version.ref = "playServicesMaps" }
    // wear = { group = "androidx.wear", name = "wear", version.ref = "wear" }
    // wearable-compile = { group = "com.google.android.wearable", name = "wearable", version.ref = "wearable" }
    // wearable-support = { group = "com.google.android.support", name = "wearable", version.ref = "wearable" }

    compileOnly(libs.wearable.compile)
    implementation(libs.wearable.support)
    implementation(libs.play.services.maps)

    // This dependency is necessary for ambient mode
    implementation(libs.wear)

    // Android Test Dependencies
    androidTestImplementation(libs.ext.junit)
    androidTestImplementation(libs.espresso.core)
    androidTestImplementation(libs.uiautomator)
    androidTestImplementation(libs.truth)
    androidTestImplementation(libs.junit)
    
    // If your project does not use a version catalog, you can use the following dependencies instead:
    //
    //    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:20.0.0")
    //    implementation("androidx.wear:wear:1.3.0")
    //    androidTestImplementation("androidx.test.ext:junit:1.1.5")
    //    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
    //    androidTestImplementation("androidx.test.uiautomator:uiautomator:2.3.0")
    //    androidTestImplementation("com.google.truth:truth:1.4.2")
    //    androidTestImplementation("junit:junit:4.13.2")
}

Per ulteriori informazioni sulle dipendenze, consulta la guida Aggiungere un modulo Wear OS al progetto esistente.

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

Ti consigliamo di utilizzare un SwipeDismissFrameLayout per visualizzare la mappa sul dispositivo indossabile. Utilizzando la classe SwipeDismissFrameLayout, puoi implementare il gesto di scorrimento per chiudere, consentendo agli utenti di 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 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 in modo che esegua l'azione di chiusura necessaria, come mostrato di seguito:

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


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

        // 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)
    }

    // ...
}

      

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

    // ...
}

      

Aggiungere una mappa

Utilizza il metodo di callback onMapReady(GoogleMap) come di consueto, per ottenere un handle per l'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 listener o spostare la videocamera. L'esempio seguente aggiunge un indicatore vicino al teatro dell'Opera di Sydney:

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

      

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

      

Attivare la modalità Ambient

Maps SDK for Android supporta la modalità Ambient per le app indossabili. Le app che supportano la modalità Ambient vengono talvolta chiamate app sempre accesa. La modalità Ambient viene attivata quando l'utente non utilizza più attivamente l'app e consente all'app di rimanere visibile sul dispositivo indossabile.

Maps SDK for Android fornisce un rendering semplificato e a colori ridotti della mappa per l'utilizzo in modalità Ambient e lo stile di mappa si adatta automaticamente quando il dispositivo passa dalla modalità interattiva alla modalità Ambient. Tutti gli indicatori, gli oggetti e i controlli UI scompaiono in modalità Ambient. In questo modo si riduce il consumo di energia dell'app e si garantisce un aspetto coerente con altre app Ambient, come i quadranti.

Segui questi passaggi per assicurarti che la tua 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 alle Activity di passare alla modalità Ambient. Per informazioni su come aggiornare l'SDK, consulta la documentazione di Android su aggiunta di pacchetti SDK.
2. Assicurati che il tuo progetto sia destinato ad Android 6.0 o versioni successive impostando il targetSdkVersion su 23 o versioni successive nel manifest dell'app.
3. Aggiungi le dipendenze indossabili al file build.gradle.kts dell'app. Consulta l'esempio in questa pagina .
4. Aggiungi la voce della libreria condivisa per dispositivi indossabili al manifest dell'app per dispositivi indossabili, come descritto nella classe di formazione Android su come mantenere visibile l'app.
5. Aggiungi l'autorizzazione WAKE_LOCK ai manifest dell'app portatile e per dispositivi indossabili, come descritto nella classe di formazione Android su come mantenere visibile l'app.
6. Nel metodo onCreate() della tua attività, chiama il AmbientModeSupport.attach() metodo. In questo modo, il sistema operativo sa che l'applicazione è sempre attiva, quindi quando il dispositivo si spegne deve entrare in modalità Ambient anziché tornare al quadrante.
7. Implementa l'interfaccia AmbientModeSupport.AmbientCallbackProvider nella tua attività in modo che possa ricevere le modifiche dello stato della modalità Ambient.
8. Imposta la mappa in modo che supporti la modalità Ambient. Puoi farlo impostando l' attributo map:ambientEnabled="true" nel file di layout XML dell'attività o a livello di programmazione impostando GoogleMapOptions.ambientEnabled(true). Questa impostazione informa l'API che deve precaricare i riquadri mappa necessari per l'utilizzo in modalità Ambient.
9. Quando l'attività passa alla modalità Ambient, il sistema chiama il onEnterAmbient() metodo nel AmbientCallback che fornisci. Esegui l'override onEnterAmbient() e chiama SupportMapFragment.onEnterAmbient(ambientDetails) o MapView.onEnterAmbient(ambientDetails). L'API passa a un rendering non interattivo e a colori ridotti della mappa.
10. Allo stesso modo, in onExitAmbient() chiama SupportMapFragment.onExitAmbient() o MapView.onExitAmbient(). L'API passa al rendering normale della mappa.

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

class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

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

        // 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()
            }
        }
    }
}

      

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

      

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

Utilizzare Street View su Wear OS

Street View è completamente supportato sui dispositivi indossabili.

Per consentire agli utenti di uscire dall'app durante la visualizzazione di una panoramica in Street View, utilizza l'StreetViewPanorama.OnStreetViewPanoramaLongClickListener per rimanere in ascolto di un gesto di clic prolungato. Quando un utente fa clic prolungato su un punto dell'immagine di Street View, riceverai un evento onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Chiama DismissOverlayView.show() per visualizzare un pulsante di uscita.

Codice campione

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 su Wear OS.

Funzionalità supportate nell'API di Google Maps su Wear OS

Questa sezione illustra le differenze nelle funzionalità supportate per le mappe sui dispositivi indossabili rispetto ai dispositivi portatili (smartphone e tablet). Tutte le funzionalità dell'API non menzionate di seguito dovrebbero funzionare come documentato per l'API completa.

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

Come offrire la migliore esperienza utente nella tua app:

• La mappa deve occupare una parte consistente 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 che un dispositivo indossabile ha una batteria scarica. Mantenere lo schermo attivo e la mappa visibile influirà sulle prestazioni della batteria.