Maps API on Wear OS

Using the Maps SDK for Android, you can create a map-based wearable app
that runs directly on Wear OS by Google devices. Users of your app
can see their location on the map just by glancing at their wrists. They can
plot their position on a route, for example, then zoom in for details, or tap a
marker to see an info window supplied by your app.

This page describes the API functionality available on a wear device and
helps you get started building your app.

Get started on Wear OS

Building a wearable app with the Maps SDK for Android is fundamentally the
same as building a Google Maps app for any other Android device. The difference
lies in your design for the smaller form factor of the wearable device, to
optimize the app's usability and performance.

Android Studio is the recommended tool for Wear OS development,
as it provides project setup, library inclusion, and packaging conveniences.

Build your first maps app on Wear OS

This quick guide assumes you are familiar with the Maps SDK for Android,
that you have followed the Wear OS guides to create a wearable module in
your app, and that you now want to add a map to the wearable module.

Add dependencies for your wear module

Ensure that the following dependencies are included in the build.gradle file
of your app's Wear OS module:

Include a dialog allowing users to exit the app

It's recommended that you use a DismissOverlayView to display the map on the
wearable device. Using the DismissOverlayView class, you can implement the
long-press-to-dismiss UI pattern, giving users a way
to exit the app by long-clicking (long-pressing) the screen. This pattern is
recommended because the Maps SDK for Android overrides the standard
left-to-right swipe usually used to exit a wearable app. In a Google Maps app,
the swipe gesture is used to pan the map.

Listen for a long-click gesture and call DismissOverlayView.show() to display
an exit button, which terminates your activity if the user clicks it:

public void onMapLongClick(LatLng point) {
mDismissOverlay.show();
}

Add a map

Use the onMapReady(GoogleMap) callback method as usual,
to get a handle to the GoogleMap object. The callback is
triggered when the map is ready to be used. In the callback method, you can
add markers or polylines to the map, add listeners, or move the camera. The
example below adds a marker near the Sydney Opera House:

Enable ambient mode

The Maps SDK for Android supports ambient mode for wearable
apps. Apps that support ambient mode are sometimes called always on apps.
Ambient mode is activated when the user is no longer actively using the app,
and allows the app to remain visible on the wearable device.

The Maps SDK for Android provides a simplified, low-color rendering
of the map for use in ambient mode, and the map style automatically adjusts when
the device swaps from interactive to ambient mode. All markers, objects, and UI
controls disappear in ambient mode. This reduces the power consumption of your
app and ensures a consistent look and feel with other ambient apps, such as
watch faces.

Take the following steps to ensure your app uses the map’s ambient mode:

Update your Android SDK to include the Android 5.1 (API 22) or higher
platform, which provides the APIs that allow activities to go into ambient
mode. For information on how to update your SDK, see the Android documentation
on adding SDK packages.

Make sure your project targets Android 5.1 or higher, by setting the
targetSdkVersion to 22 or higher in the app manifest.

In the onCreate() method of your activity, call the
setAmbientEnabled() method. This tells the operating
system that the application is always on, so that when the device powers down
it should enter ambient mode rather than returning to the watch face.

Set your map to support ambient mode. You can do this by setting the
attribute map:ambientEnabled="true" in the activity's XML layout file, or do
it programmatically by setting GoogleMapOptions.ambientEnabled(true).
This setting informs the API that it must pre-load the necessary map tiles for
use in ambient mode.

When the activity switches to ambient mode, the system calls the
onEnterAmbient() method in your wearable activity.
Override onEnterAmbient() and call
MapFragment.onEnterAmbient(ambientDetails) or
MapView.onEnterAmbient(ambientDetails). The API swaps to a non-interactive
and low-color rendering of the map.

Similarly, in onExitAmbient() call
MapFragment.onExitAmbient() or MapView.onExitAmbient(). The API swaps to
the normal rendering of the map.

The following code sample enables ambient mode in the app and in the map:

public class MainActivity extends WearableActivity
implements OnMapReadyCallback, GoogleMap.OnMapLongClickListener {
private MapFragment mMapFragment;
public void onCreate(Bundle savedState) {
super.onCreate(savedState);
// Enable ambient support, so the map remains visible in a simplified,
// low-color display when the user is no longer actively using the app
// and the app is still visible on the watch face.
setAmbientEnabled();
// ... Perform other activity setup processes here too ...
}
/**
* 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);
mMapFragment.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();
mMapFragment.onExitAmbient();
}
}

You can update the screen while the app is in ambient mode. For more details
about updating content and about ambient mode in general, see the Android
training class on keeping your app visible.

Use Street View on Wear OS

To allow users to exit from the app when viewing a Street View panorama, use the
StreetViewPanorama.OnStreetViewPanoramaLongClickListener
interface to listen for a long-click gesture. When a user long-clicks somewhere
on the Street View image, you will receive an
onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation) event. Call
DismissOverlayView.show() to display an exit button.

Sample code

A sample app is available on GitHub, which you can use as a
starting point for your app. The sample shows you how to set up
a basic Google Map on Wear OS.

Supported functionality in the Maps API on Wear OS

This section outlines the differences in supported functionality for maps on
wearable devices when compared with handheld devices (phones and tablets).
All API features not mentioned below should work as documented for the full API.

Functionality

Fully interactive mode and lite mode

You can use the Maps SDK for Android in fully interactive mode or
in lite mode. Consider lite mode if you want to optimize performance on
the wearable device and your app doesn't need to support
interaction such as gestures, or panning and zooming the map.

In lite mode, the intent to start the Google Maps mobile app when the
user taps the map is disabled and cannot be enabled on
a wearable device.

For a full list of differences between lite mode and fully interactive
mode, see the lite mode
documentation.

Map toolbar

The map
toolbar is disabled and cannot be enabled on a
wearable device.

UI controls

The UI
controls are disabled by default on wearable devices. This includes
the zoom, compass, and my location controls. You can enable them using the
UiSettings
class as usual.

Gestures

Single-touch
gestures
work as expected. Examples are touch and drag to pan the map, double-tap
to zoom in, and two-finger tap to zoom out.
Support varies for multi-touch gestures depending on the user's device.
Examples of multi-touch gestures include two-finger push to tilt the map,
pinch to zoom, and two-finger rotation.