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.

For general help with designing a wearable app, refer to the Wear OS design guidelines. For help with creating your first wearable app, see the guide to creating wearable apps.

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:

dependencies {
  compile fileTree(dir: 'libs', include: ['*.jar'])
  compile 'com.google.android.support:wearable:1.2.0'
  provided 'com.google.android.wearable:wearable:1.0.0'
  compile 'com.google.android.gms:play-services-maps:17.0.0'
}

Note: The provided dependency ensures that the classes loaded at run time to support ambient mode are also available at compile time.

For more information about the dependencies, see the guide to defining layouts in Wear OS.

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.

Add the DismissOverlayView element to your layout definition:

<FrameLayout
   xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_height="match_parent"
   android:layout_width="match_parent">

  ...

  <android.support.wearable.view.DismissOverlayView
     android:id="@+id/dismiss_overlay"
     android:layout_height="match_parent"
     android:layout_width="match_parent"/>

</FrameLayout>

When you obtain the DismissOverlayView object in your activity, set some introductory text to inform users that they can exit the app with a long-click gesture, as shown below:

public class MainActivity extends WearableActivity
        implements OnMapReadyCallback, GoogleMap.OnMapLongClickListener {

    private MapFragment mMapFragment;
    private DismissOverlayView mDismissOverlay;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.basic_wear_demo);

        mDismissOverlay =
            (DismissOverlayView) findViewById(R.id.dismiss_overlay);
        mDismissOverlay.setIntroText(R.string.basic_wear_long_press_intro);
        mDismissOverlay.showIntroIfNecessary();

        mMapFragment = (MapFragment) getFragmentManager()
                .findFragmentById(R.id.map);
        mMapFragment.getMapAsync(this);
    }
    ...
}

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:

public class MainActivity extends WearableActivity
        implements OnMapReadyCallback, GoogleMap.OnMapLongClickListener {

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

    ...

    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;
        mMap.addMarker(new MarkerOptions().position(SYDNEY)
            .title("Sydney Opera House"));
        mMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
        mMap.setOnMapLongClickListener(this);
    }
}

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:

1. 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.
2. Make sure your project targets Android 5.1 or higher, by setting the targetSdkVersion to 22 or higher in the app manifest.
3. Add the wearable dependencies to your app's build.gradle file. See the sample on this page.
4. Add the wearable shared library entry into the wearable app manifest, as described in the Android training class on keeping your app visible.
5. Add the WAKE_LOCK permission to the handheld and wearable app manifests, as described in the Android training class on keeping your app visible.
6. Create an activity that extends WearableActivity.
7. 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.
8. 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.
9. 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.
10. 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

Street View is fully supported on wearable devices.

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.
Indoor maps and buildings	Indoor maps are disabled by default on a wearable device. You can enable them by calling GoogleMap.setIndoorEnabled(true). If indoor maps are enabled, the map will show the default floor level. The level picker UI element is not supported on wearable devices.
Tile overlays	Tile overlays are not supported on wearable devices.

Best practices for developing with the Maps API on Wear OS

How to provide the best user experience in your app:

• The map should occupy a large proportion of the screen. This is necessary to optimize the usability of the map on the small form factor of a wearable device.
• When designing the user experience of your app, take into account the fact that a wearable device has low battery power. Keeping the screen active and the map visible will impact battery performance.