Con l'SDK di Maps per Android, puoi creare un'app indossabile basata su mappa che viene eseguita direttamente sui dispositivi Wear OS by Google. Gli utenti della tua app possono vedere la loro posizione sulla mappa semplicemente dando un'occhiata al polso. Ad esempio, possono tracciare la loro posizione su un percorso e poi 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 di usura e ti aiuta a iniziare a creare la tua app.
Iniziare a usare Wear OS
Creare un'app indossabile con l'SDK di Maps per Android è fondamentalmente la stessa cosa di creare un'app di Google Maps per qualsiasi altro dispositivo Android. La differenza sta nel design per il fattore di forma più piccolo del dispositivo indossabile, in modo da ottimizzare l'usabilità e le prestazioni dell'app.
Android Studio è lo strumento consigliato per lo sviluppo di Wear OS, in quanto offre configurazione dei progetti, inclusione della raccolta e pratiche di imballaggio.
Per assistenza generale nella progettazione di un'app indossabile, consulta le linee guida per la progettazione di Wear OS. Per creare la tua prima app indossabile, consulta la guida alla creazione di app indossabili.
Creazione della prima app Maps su Wear OS
Questa guida rapida presuppone che tu conosca l'SDK Maps per Android, che hai seguito le guide di Wear OS per creare un modulo indossabile nella tua app e che ora vuoi aggiungere una mappa al modulo indossabile.
Aggiunta di dipendenze per il modulo di usura
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.1.0'
// 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
Ti consigliamo di utilizzare un SwipeDismissFrameLayout per visualizzare la mappa sul
dispositivo indossabile. Con la classe SwipeDismissFrameLayout, puoi implementare il gesto di scorrimento per ignorare che offre 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 in modo che esegua 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 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 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))
}
Abilitazione della modalità Ambient
L'SDK di Maps per Android supporta la modalità Ambient per le app indossabili. Le app che supportano la modalità Ambient sono a volte chiamate app sempre attive. La modalità Ambient viene attivata quando l'utente non utilizza più attivamente l'app e consente all'app di rimanere visibile sul dispositivo indossabile.
L'SDK di Maps per Android offre una visualizzazione semplificata a basso colore della mappa per l'utilizzo in modalità Ambient e lo stile della 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 non sono più visualizzati in modalità Ambient. Questo riduce il consumo energetico dell'app e garantisce un aspetto e uno stile coerenti con altre app ambientali, come i quadranti.
Segui questi passaggi per assicurarti che la tua app utilizzi la modalità Ambient della mappa:
- Aggiorna il tuo SDK Android per includere la piattaforma Android 6.0 (API 23) o superiore, che fornisce le API che consentono l'attivazione delle attività in modalità Ambient. Per informazioni su come aggiornare l'SDK, consulta la documentazione di Android sull'aggiunta dei pacchetti SDK.
- Assicurati che il progetto abbia come target Android 6.0 o versioni successive impostando il valore
targetSdkVersionsu 23 o valori successivi nel file manifest dell'app. - Aggiungi le dipendenze indossabili al file
build.gradledella tua app. Guarda l'esempio in questa pagina. - Aggiungi la voce della libreria condivisa indossabile al manifest dell'app indossabile, come descritto nel corso di formazione Android su come mantenere visibile la tua app.
- Aggiungi l'autorizzazione
WAKE_LOCKai file manifest dell'app portatili e indossabili, come descritto nella lezione di addestramento di Android su come mantenere visibile l'app. - Nel metodo
onCreate()della tua attività, chiama il metodoAmbientModeSupport.attach(). Questo indica al sistema operativo che l'applicazione è sempre attiva, quindi quando il dispositivo si spegne dovrebbe entrare in modalità Ambient anziché tornare al quadrante. - Implementa l'interfaccia
AmbientModeSupport.AmbientCallbackProvidernell'attività in modo che possa ricevere i cambiamenti dello stato della modalità Ambient. - Configurare la mappa per supportare la modalità Ambient. Puoi farlo impostando l'attributo
map:ambientEnabled="true"nel file di layout XML dell'attività oppure farlo in modo programmatico impostandoGoogleMapOptions.ambientEnabled(true). Questa impostazione indica 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'oggettoAmbientCallbackfornito. SostituiscionEnterAmbient()e chiamaSupportMapFragment.onEnterAmbient(ambientDetails)oMapView.onEnterAmbient(ambientDetails). L'API passa a un rendering della mappa non interattivo e a colori. - Analogamente, in
onExitAmbient()chiamaSupportMapFragment.onExitAmbient()oMapView.onExitAmbient(). L'API passa al rendering normale della mappa.
Il seguente esempio di codice consente 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 su Android come mantenere visibile la tua app.
Utilizzo di 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 di Street View, utilizza l'interfaccia
StreetViewPanorama.OnStreetViewPanoramalongClickClick
per ascoltare il gesto di clic lungo. Quando un utente fa clic a lungo
su un'immagine di Street View, riceverai un
evento onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Chiama il numero DismissOverlayView.show() per visualizzare un pulsante di uscita.
Codice campione
Su GitHub è disponibile un'app di esempio che puoi usare come punto di partenza per la tua app. L'esempio mostra come configurare una mappa di Google Maps di base 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 (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 ha bisogno di supportare interazioni quali gesti o panoramica e zoom sulla mappa. In modalità Lite, l'intenzione di avviare l'app mobile Google Maps quando l'utente tocca la mappa è disattivata e non può essere attivata su un dispositivo indossabile. Per un elenco completo delle differenze tra la modalità Lite e la modalità completamente interattiva, consultate la documentazione sulla 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 dell'interfaccia utente sono disattivati per impostazione predefinita sui dispositivi indossabili. Ciò include
lo zoom, la bussola e i controlli di geolocalizzazione. Puoi abilitarli utilizzando la classe UiSettings come di consueto.
|
| Gesti | I gesti con un solo tocco funzionano come previsto. Alcuni esempi sono toccare e trascinare per esplorare la mappa, toccare due volte per aumentare lo zoom e toccare con due dita per diminuire lo zoom. Il supporto varia a seconda dei gesti multi-touch a seconda del dispositivo utilizzato dall'utente. Alcuni esempi di gesti multi-touch includono il tocco con due dita per inclinare la mappa, il tocco per eseguire lo zoom e la 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, la mappa mostrerà il livello del piano predefinito.
L'elemento UI del selettore di livelli non è supportato sui dispositivi indossabili. |
| Overlay riquadro | Gli overlay delle schede 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 deve 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, considera il fatto che il dispositivo indossabile ha la batteria in esaurimento. Mantenere lo schermo attivo e la mappa visibile influiscono sulle prestazioni della batteria.