Con Maps SDK for Android, puoi creare un'app indossabile 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 i polsi. Ad esempio, possono tracciare la loro posizione su un percorso, aumentare lo zoom per visualizzare i dettagli o toccare un indicatore per visualizzare una finestra informativa fornita dalla tua app.
Questa pagina descrive la funzionalità API disponibile su un dispositivo Wear e ti aiuta a iniziare a creare la tua app.
Iniziare a usare Wear OS
Creare un'app indossabile con l'SDK Maps for Android è fondamentalmente la stessa che creare un'app Google Maps per qualsiasi altro dispositivo Android. La differenza sta nel design del 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 di librerie e praticità di pacchettizzazione.
Per assistenza generica sulla progettazione di un'app indossabile, consulta le linee guida per la progettazione di Wear OS. Per informazioni sulla creazione della tua prima app indossabile, consulta la guida alla creazione di app indossabili.
Creazione della tua prima app per le mappe su Wear OS
Questa guida rapida presuppone che tu conosca l'SDK Maps per 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.
Aggiunta di dipendenze per il modulo Wear
Assicurati che le seguenti dipendenze siano incluse 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.2.0' // This dependency is necessary for ambient mode implementation 'androidx.wear:wear:1.3.0' }
Per ulteriori informazioni sulle dipendenze, consulta la guida per aggiungere un modulo Wear OS nel progetto esistente.
Implementazione di un gesto di scorrimento per ignorare e impostazione del colore di sfondo iniziale
È consigliabile utilizzare un SwipeDismissFrameLayout
per visualizzare la mappa sul
dispositivo indossabile. Con la classe SwipeDismissFrameLayout
, puoi implementare il gesto sScorri-to-dimiss per dare 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 effettivo dei riquadri della mappa.
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 da eseguire l'azione di ignorare necessaria, come mostrato di seguito:
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) } // ... }
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); } // ... }
Aggiunta di 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. Con il metodo di callback, puoi aggiungere indicatori o polilinee alla mappa, aggiungere listener o spostare la fotocamera. Nell'esempio seguente viene aggiunto un indicatore nei pressi del Teatro dell'opera di Sydney:
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)) }
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)); }
Attivazione della modalità Ambient
Maps SDK for Android supporta la modalità Ambient per le app indossabili. Le app che supportano la modalità Ambient a volte sono chiamate app sempre attive. La modalità Ambient viene attivata quando l'utente non sta più utilizzando attivamente l'app e consente all'app di rimanere visibile sul dispositivo indossabile.
L'SDK Maps for Android fornisce una visualizzazione semplificata a bassa colori della mappa per l'utilizzo in modalità Ambient e lo stile della mappa si regola automaticamente quando il dispositivo passa dalla modalità interattiva a quella Ambient. Tutti gli indicatori, gli oggetti e i controlli UI scompaiono in modalità Ambient. Ciò riduce il consumo energetico dell'app e garantisce un aspetto e uno stile coerenti con altre app Ambient, ad esempio i quadranti.
Per assicurarti che l'app utilizzi la modalità Ambient della mappa:
- 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 attività di passare alla modalità Ambient. Per informazioni su come aggiornare l'SDK, consulta la documentazione Android relativa all'aggiunta di pacchetti di SDK.
- Assicurati che il progetto abbia come target Android 6.0 o versioni successive impostando
targetSdkVersion
su 23 o versioni successive nel file manifest dell'app. - Aggiungi le dipendenze indossabili al file
build.gradle
della tua app. Consulta l'esempio in questa pagina. - Aggiungi la voce della libreria condivisa indossabile al file manifest dell'app indossabile, come descritto nel corso di formazione Android sul mantenere visibile l'app.
- Aggiungi l'autorizzazione
WAKE_LOCK
ai file manifest delle app per dispositivi portatili e indossabili, come descritto nel corso di formazione Android su come mantenere visibile l'app. - Richiama il metodo
AmbientModeSupport.attach()
nel metodoonCreate()
dell'attività. Questo indica al sistema operativo che l'applicazione è sempre attiva e, quando il dispositivo viene spento, deve entrare in modalità Ambient anziché tornare al quadrante orologio. - Implementa l'interfaccia
AmbientModeSupport.AmbientCallbackProvider
nella sezione Attività in modo che possa ricevere i cambiamenti di stato della modalità Ambient. - 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à oppure in modo programmatico impostandoGoogleMapOptions.ambientEnabled(true)
. Questa impostazione comunica all'API che deve precaricare i riquadri della mappa necessari per l'utilizzo in modalità Ambient. - Quando l'attività passa alla modalità Ambient, il sistema chiama il metodo
onEnterAmbient()
nell'AmbientCallback
che fornisci. Esegui l'override dionEnterAmbient()
e chiamaSupportMapFragment.onEnterAmbient(ambientDetails)
oMapView.onEnterAmbient(ambientDetails)
. L'API passa a un rendering non interattivo e a basso colore della mappa. - Analogamente, in
onExitAmbient()
chiamataSupportMapFragment.onExitAmbient()
oMapView.onExitAmbient()
. L'API passa al rendering normale della mappa.
Il seguente esempio di codice consente la modalità Ambient nell'attività:
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() } } } }
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(); } }; } }
Puoi aggiornare lo schermo mentre 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.
Utilizzare Street View su Wear OS
Street View è completamente supportato sui dispositivi indossabili.
Per consentire agli utenti di uscire dall'app quando visualizzano una panoramica in Street View, utilizza l'interfaccia
StreetViewPanorama.OnStreetViewPanoramaLongClickListener
per ascoltare il gesto del lungo clic. Quando un utente fa clic a lungo su un punto
su un'immagine di Street View, ricevi 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 Google di base su Wear OS.
Funzionalità supportate nell'API di Google Maps su Wear OS
Questa sezione illustra le differenze delle funzionalità supportate per le mappe sui dispositivi indossabili rispetto ai dispositivi portatili (smartphone e tablet). Tutte le funzionalità dell'API non menzionate di seguito devono funzionare come documentato per l'API completa.
Funzionalità | |
---|---|
Modalità completamente interattiva e Lite | Puoi utilizzare Maps SDK for Android in modalità completamente interattiva o Lite. Prendi in considerazione la modalità Lite se vuoi ottimizzare le prestazioni sul dispositivo indossabile e la tua app non deve supportare interazioni quali gesti o panoramica e zoom della mappa. In modalità Lite, l'intent per avviare l'app mobile Google Maps 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 della mappa | La barra degli strumenti della mappa è disattivata e non può essere attivata su un dispositivo indossabile. |
Controlli UI | I controlli UI sono disattivati per impostazione predefinita sui dispositivi indossabili. Sono inclusi lo zoom, la bussola e i controlli della mia posizione. Puoi abilitarli utilizzando il corso
UiSettings
come di consueto.
|
Gesti | I gesti single-touch funzionano come previsto. Ad esempio, tocca e trascina per spostarti nella mappa, tocca due volte per aumentare lo zoom e tocca con due dita per diminuire lo zoom. Il supporto varia per i gesti multi-touch in base al dispositivo dell'utente. Esempi di gesti multi-touch includono la spinta con due dita per inclinare la mappa, pizzicare per eseguire lo zoom e la rotazione con due dita. |
Mappe di interni ed edifici |
Le mappe di interni sono
disattivate per impostazione predefinita su un dispositivo indossabile. Puoi abilitarli chiamando
GoogleMap.setIndoorEnabled(true) . Se le mappe di interni sono abilitate, la mappa mostrerà il livello del piano predefinito.
L'elemento UI del selettore di livelli non è supportato sui dispositivi indossabili. |
Overlay riquadri | Gli overlay dei riquadri non sono supportati sui dispositivi indossabili. |
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 dovrebbe occupare un'ampia porzione dello schermo. Ciò è necessario per ottimizzare l'usabilità della mappa sul piccolo fattore di forma di un dispositivo indossabile.
- Quando progetti l'esperienza utente della tua app, tieni presente il fatto che la batteria di un dispositivo indossabile è in esaurimento. Mantenere lo schermo attivo e la mappa visibile influisce sulle prestazioni della batteria.